stack/CLAUDE.md

Multi-tenant personal assistant platform with PostgreSQL backend, Authentik SSO, and MoltBot integration.

Project Overview

Mosaic Stack is a standalone platform that provides:

• Multi-user workspaces with team sharing
• Task, event, and project management
• Gantt charts and Kanban boards
• MoltBot integration via plugins (stock MoltBot + mosaic-plugin-*)
• PDA-friendly design throughout

Repository: git.mosaicstack.dev/mosaic/stack Versioning: Start at 0.0.1, MVP = 0.1.0

Technology Stack

Layer	Technology
Frontend	Next.js 16 + React + TailwindCSS + Shadcn/ui
Backend	NestJS + Prisma ORM
Database	PostgreSQL 17 + pgvector
Cache	Valkey (Redis-compatible)
Auth	Authentik (OIDC)
AI	Ollama (configurable: local or remote)
Messaging	MoltBot (stock + Mosaic plugins)
Real-time	WebSockets (Socket.io)
Monorepo	pnpm workspaces + TurboRepo
Testing	Vitest + Playwright
Deployment	Docker + docker-compose

Repository Structure

mosaic-stack/ ├── apps/ │ ├── api/ # mosaic-api (NestJS) │ │ ├── src/ │ │ │ ├── auth/ # Authentik OIDC │ │ │ ├── tasks/ # Task management │ │ │ ├── events/ # Calendar/events │ │ │ ├── projects/ # Project management │ │ │ ├── brain/ # MoltBot integration │ │ │ └── activity/ # Activity logging │ │ ├── prisma/ │ │ │ └── schema.prisma │ │ └── Dockerfile │ └── web/ # mosaic-web (Next.js 16) │ ├── app/ │ ├── components/ │ └── Dockerfile ├── packages/ │ ├── shared/ # Shared types, utilities │ ├── ui/ # Shared UI components │ └── config/ # Shared configuration ├── plugins/ │ ├── mosaic-plugin-brain/ # MoltBot skill: API queries │ ├── mosaic-plugin-calendar/ # MoltBot skill: Calendar │ ├── mosaic-plugin-tasks/ # MoltBot skill: Tasks │ └── mosaic-plugin-gantt/ # MoltBot skill: Gantt ├── docker/ │ ├── docker-compose.yml # Turnkey deployment │ └── init-scripts/ # PostgreSQL init ├── docs/ │ ├── SETUP.md │ ├── CONFIGURATION.md │ └── DESIGN-PRINCIPLES.md ├── .env.example ├── turbo.json ├── pnpm-workspace.yaml └── README.md

Development Workflow

Branch Strategy

• main — stable releases only
• develop — active development (default working branch)
• feature/* — feature branches from develop
• fix/* — bug fix branches

Starting Work

git checkout develop
git pull --rebase
pnpm install

Running Locally

# Start all services (Docker)
docker compose up -d

# Or run individually for development
pnpm dev           # All apps
pnpm dev:api       # API only
pnpm dev:web       # Web only

Testing

pnpm test          # Run all tests
pnpm test:api      # API tests only
pnpm test:web      # Web tests only
pnpm test:e2e      # Playwright E2E

Building

pnpm build         # Build all
pnpm build:api     # Build API
pnpm build:web     # Build Web

Design Principles (NON-NEGOTIABLE)

PDA-Friendly Language

NEVER use demanding language. This is critical.
┌─────────────┬──────────────────────┐
│  ❌ NEVER   │      ✅ ALWAYS       │
├─────────────┼──────────────────────┤
│ OVERDUE     │ Target passed        │
├─────────────┼──────────────────────┤
│ URGENT      │ Approaching target   │
├─────────────┼──────────────────────┤
│ MUST DO     │ Scheduled for        │
├─────────────┼──────────────────────┤
│ CRITICAL    │ High priority        │
├─────────────┼──────────────────────┤
│ YOU NEED TO │ Consider / Option to │
├─────────────┼──────────────────────┤
│ REQUIRED    │ Recommended          │
└─────────────┴──────────────────────┘
Visual Indicators

Use status indicators consistently:
- 🟢 On track / Active
- 🔵 Upcoming / Scheduled
- ⏸️ Paused / On hold
- 💤 Dormant / Inactive
- ⚪ Not started

Display Principles

1. 10-second scannability — Key info visible immediately
2. Visual chunking — Clear sections with headers
3. Single-line items — Compact, scannable lists
4. Date grouping — Today, Tomorrow, This Week headers
5. Progressive disclosure — Details on click, not upfront
6. Calm colors — No aggressive reds for status

Reference

See docs/DESIGN-PRINCIPLES.md for complete guidelines.
For original patterns, see: jarvis-brain/docs/DESIGN-PRINCIPLES.md

API Conventions

Endpoints

GET    /api/{resource}           # List (with pagination, filters)
GET    /api/{resource}/:id       # Get single
POST   /api/{resource}           # Create
PATCH  /api/{resource}/:id       # Update
DELETE /api/{resource}/:id       # Delete

Response Format

// Success
{
  data: T | T[],
  meta?: { total, page, limit }
}

// Error
{
  error: {
    code: string,
    message: string,
    details?: any
  }
}

Brain Query API

POST /api/brain/query
{
  query: "what's on my calendar",
  context?: { view: "dashboard", workspace_id: "..." }
}

Database Conventions

Multi-Tenant (RLS)

All workspace-scoped tables use Row-Level Security:
- Always include workspace_id in queries
- RLS policies enforce isolation
- Set session context for current user

Prisma Commands

pnpm prisma:generate   # Generate client
pnpm prisma:migrate    # Run migrations
pnpm prisma:studio     # Open Prisma Studio
pnpm prisma:seed       # Seed development data

MoltBot Plugin Development

Plugins live in plugins/mosaic-plugin-*/ and follow MoltBot skill format:

# plugins/mosaic-plugin-brain/SKILL.md
---
name: mosaic-plugin-brain
description: Query Mosaic Stack for tasks, events, projects
version: 0.0.1
triggers:
  - "what's on my calendar"
  - "show my tasks"
  - "morning briefing"
tools:
  - mosaic_api
---

# Plugin instructions here...

Key principle: MoltBot remains stock. All customization via plugins only.

Environment Variables

See .env.example for all variables. Key ones:

# Database
DATABASE_URL=postgresql://mosaic:password@localhost:5432/mosaic

# Auth
AUTHENTIK_URL=https://auth.example.com
AUTHENTIK_CLIENT_ID=mosaic-stack
AUTHENTIK_CLIENT_SECRET=...

# Ollama
OLLAMA_MODE=local|remote
OLLAMA_ENDPOINT=http://localhost:11434

# MoltBot
MOSAIC_API_TOKEN=...

Issue Tracking

Issues are tracked at: https://git.mosaicstack.dev/mosaic/stack/issues

Labels

- Priority: p0 (critical), p1 (high), p2 (medium), p3 (low)
- Type: api, web, database, auth, plugin, ai, devops, docs, migration, security, testing,
performance, setup

Milestones

- M1-Foundation (0.0.x)
- M2-MultiTenant (0.0.x)
- M3-Features (0.0.x)
- M4-MoltBot (0.0.x)
- M5-Migration (0.1.0 MVP)

Commit Format

<type>(#issue): Brief description

Detailed explanation if needed.

Fixes #123
Types: feat, fix, docs, test, refactor, chore

Testing Requirements

- Minimum 85% coverage for new code
- Write tests before implementation (TDD)
- All tests must pass before PR merge

Docker Deployment

Turnkey (includes everything)

docker compose up -d

Customized (external services)

Create docker-compose.override.yml to:
- Point to external PostgreSQL/Valkey/Ollama
- Disable bundled services

See docs/DOCKER.md for details.

Key Documentation
┌───────────────────────────┬───────────────────────┐
│         Document          │        Purpose        │
├───────────────────────────┼───────────────────────┤
│ docs/SETUP.md             │ Installation guide    │
├───────────────────────────┼───────────────────────┤
│ docs/CONFIGURATION.md     │ All config options    │
├───────────────────────────┼───────────────────────┤
│ docs/DESIGN-PRINCIPLES.md │ PDA-friendly patterns │
├───────────────────────────┼───────────────────────┤
│ docs/DOCKER.md            │ Docker deployment     │
├───────────────────────────┼───────────────────────┤
│ docs/API.md               │ API documentation     │
└───────────────────────────┴───────────────────────┘
Related Repositories
┌──────────────┬──────────────────────────────────────────────┐
│     Repo     │                   Purpose                    │
├──────────────┼──────────────────────────────────────────────┤
│ jarvis-brain │ Original JSON-based brain (migration source) │
├──────────────┼──────────────────────────────────────────────┤
│ MoltBot      │ Stock messaging gateway                      │
└──────────────┴──────────────────────────────────────────────┘
---
Mosaic Stack v0.0.x — Building the future of personal assistants.