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 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
|