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
  ```bash
  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

  Test-Driven Development (TDD) - REQUIRED

  **All code must follow TDD principles. This is non-negotiable.**

  TDD Workflow (Red-Green-Refactor)

  1. **RED** — Write a failing test first
     - Write the test for new functionality BEFORE writing any implementation code
     - Run the test to verify it fails (proves the test works)
     - Commit message: `test(#issue): add test for [feature]`

  2. **GREEN** — Write minimal code to make the test pass
     - Implement only enough code to pass the test
     - Run tests to verify they pass
     - Commit message: `feat(#issue): implement [feature]`

  3. **REFACTOR** — Clean up the code while keeping tests green
     - Improve code quality, remove duplication, enhance readability
     - Ensure all tests still pass after refactoring
     - Commit message: `refactor(#issue): improve [component]`

  Testing Requirements

  - **Minimum 85% code coverage** for all new code
  - **Write tests BEFORE implementation** — no exceptions
  - Test files must be co-located with source files:
    - `feature.service.ts` → `feature.service.spec.ts`
    - `component.tsx` → `component.test.tsx`
  - All tests must pass before creating a PR
  - Use descriptive test names: `it("should return user when valid token provided")`
  - Group related tests with `describe()` blocks
  - Mock external dependencies (database, APIs, file system)

  Test Types

  - **Unit Tests** — Test individual functions/methods in isolation
  - **Integration Tests** — Test module interactions (e.g., service + database)
  - **E2E Tests** — Test complete user workflows with Playwright

  Running Tests

  ```bash
  pnpm test              # Run all tests
  pnpm test:watch        # Watch mode for active development
  pnpm test:coverage     # Generate coverage report
  pnpm test:api          # API tests only
  pnpm test:web          # Web tests only
  pnpm test:e2e          # Playwright E2E tests
  ```

  Coverage Verification

  After implementing a feature, verify coverage meets requirements:
  ```bash
  pnpm test:coverage
  # Check the coverage report in coverage/index.html
  # Ensure your files show ≥85% coverage
  ```

  TDD Anti-Patterns to Avoid

  ❌ Writing implementation code before tests
  ❌ Writing tests after implementation is complete
  ❌ Skipping tests for "simple" code
  ❌ Testing implementation details instead of behavior
  ❌ Writing tests that don't fail when they should
  ❌ Committing code with failing tests

  Example TDD Session

  ```bash
  # 1. RED - Write failing test
  # Edit: feature.service.spec.ts
  # Add test for getUserById()
  pnpm test:watch  # Watch it fail
  git add feature.service.spec.ts
  git commit -m "test(#42): add test for getUserById"

  # 2. GREEN - Implement minimal code
  # Edit: feature.service.ts
  # Add getUserById() method
  pnpm test:watch  # Watch it pass
  git add feature.service.ts
  git commit -m "feat(#42): implement getUserById"

  # 3. REFACTOR - Improve code quality
  # Edit: feature.service.ts
  # Extract helper, improve naming
  pnpm test:watch  # Ensure still passing
  git add feature.service.ts
  git commit -m "refactor(#42): extract user mapping logic"
  ```

  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.