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 only
# PostgreSQL execution is held until KBN-101-00/-03/-05 land. Do not invoke a runner,
# init SQL, or Compose PostgreSQL service from this checkout.

# Dev: local PGlite data-layer work needs no PostgreSQL. Optional local queue service only:
docker compose up -d valkey
# Do not start Gateway/Web or root pnpm dev as a local PGlite route: the current unguarded dotenv
# loader can inherit a daemon PostgreSQL DSN. KBN-101-02 must make that state fail closed first.

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