feat(#1): Set up monorepo scaffold with pnpm workspaces + TurboRepo
Implements the foundational project structure including: - pnpm workspaces configuration - TurboRepo for build orchestration - NestJS 11.1.12 API (apps/api) - Next.js 16.1.6 web app (apps/web) - Shared packages (config, shared, ui) - TypeScript strict mode configuration - ESLint + Prettier setup - Vitest for unit testing (19 passing tests) Fixes #1 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Jason Woltje
313
CLAUDE.md
Normal file
313
CLAUDE.md
Normal file
@@ -0,0 +1,313 @@
|
||||
**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
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user