stack/CLAUDE.md

CLAUDE.md — Mosaic Stack

Project

Self-hosted, multi-user AI agent platform. TypeScript monorepo.

Stack

• API: NestJS + Fastify adapter (apps/gateway)
• Web: Next.js 16 + React 19 (apps/web)
• ORM: Drizzle ORM + PostgreSQL 17 + pgvector (packages/db)
• Auth: BetterAuth (packages/auth)
• Agent: Pi SDK (packages/agent, packages/mosaic)
• Queue: Valkey 8 (packages/queue)
• Build: pnpm workspaces + Turborepo
• CI: Woodpecker CI
• Observability: OpenTelemetry → Jaeger

Commands

pnpm typecheck        # TypeScript check (all packages)
pnpm lint             # ESLint (all packages)
pnpm format:check     # Prettier check
pnpm test             # Vitest (all packages)
pnpm build            # Build all packages

# Database
pnpm --filter @mosaicstack/db db:generate  # Offline migration artifact generation
mosaic-db-migrator --run                   # Sole PostgreSQL DDL runner
mosaic-db-migrator --verify                # Verified readiness; no URL/SQL/schema/role argv
# db:push is disposable-local-only; db:migrate/storage migrate --run must delegate only to the runner.

# Dev
docker compose up -d                  # Start PG, Valkey, OTEL, Jaeger
pnpm --filter @mosaicstack/gateway exec tsx src/main.ts  # Start gateway

Conventions

• ESM everywhere ("type": "module", .js extensions in imports)
• NodeNext module resolution
• Explicit @Inject() decorators in NestJS (tsx/esbuild doesn't support emitDecoratorMetadata)
• DTOs in *.dto.ts files at module boundaries
• OTEL tracing imported before NestJS bootstrap (import './tracing.js')
• All three gates must pass before push: typecheck, lint, format:check