stack/CLAUDE.md

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

## Conditional Documentation Loading

| When working on...                       | Load this guide                                                     |
| ---------------------------------------- | ------------------------------------------------------------------- |
| Orchestrating autonomous task completion | `~/.claude/agent-guides/orchestrator.md`                            |
| Security remediation (review findings)   | `docs/reports/codebase-review-2026-02-05/01-security-review.md`     |
| Code quality fixes                       | `docs/reports/codebase-review-2026-02-05/02-code-quality-review.md` |
| Test coverage gaps                       | `docs/reports/codebase-review-2026-02-05/03-qa-test-coverage.md`    |

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

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

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