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