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

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:

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

Quality Rails - Mechanical Code Quality Enforcement

Status: ACTIVE (2026-01-30) - Strict enforcement enabled ✅

Quality Rails provides mechanical enforcement of code quality standards through pre-commit hooks and CI/CD pipelines. See docs/quality-rails-status.md for full details.

What's Enforced (NOW ACTIVE):

• ✅ Type Safety - Blocks explicit any types (@typescript-eslint/no-explicit-any: error)
• ✅ Return Types - Requires explicit return types on exported functions
• ✅ Security - Detects SQL injection, XSS, unsafe regex (eslint-plugin-security)
• ✅ Promise Safety - Blocks floating promises and misused promises
• ✅ Code Formatting - Auto-formats with Prettier on commit
• ✅ Build Verification - Type-checks before allowing commit
• ✅ Secret Scanning - Blocks hardcoded passwords/API keys (git-secrets)

Current Status:

• ✅ Pre-commit hooks: ACTIVE - Blocks commits with violations
• ✅ Strict enforcement: ENABLED - Package-level enforcement
• 🟡 CI/CD pipeline: Ready (.woodpecker.yml created, not yet configured)

How It Works:

Package-Level Enforcement - If you touch ANY file in a package with violations, you must fix ALL violations in that package before committing. This forces incremental cleanup while preventing new violations.

Example:

• Edit apps/api/src/tasks/tasks.service.ts
• Pre-commit hook runs lint on ENTIRE @mosaic/api package
• If @mosaic/api has violations → Commit BLOCKED
• Fix all violations in @mosaic/api → Commit allowed

Next Steps:

1. Fix violations package-by-package as you work in them
2. Priority: Fix explicit any types and type safety issues first
3. Configure Woodpecker CI to run quality gates on all PRs

Why This Matters:

Based on validation of 50 real production issues, Quality Rails mechanically prevents ~70% of quality issues including:

• Hardcoded passwords
• Type safety violations
• SQL injection vulnerabilities
• Build failures
• Test coverage gaps

Mechanical enforcement works. Process compliance doesn't.

See docs/quality-rails-status.md for detailed roadmap and violation breakdown.

Example TDD Session

# 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.