47 lines
1.7 KiB
Markdown
47 lines
1.7 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|