Data View

Data Philosophy

The project is Postgres-centered.

PostgreSQL is the source of structured truth. Object storage is used for binary files. AI-readable documents describe intent and decisions.

Data Layers

PostgreSQL
  -> structured data
  -> relationships
  -> permissions
  -> metadata

Object Storage
  -> binary files
  -> attachments
  -> generated assets
  -> dataset files

Repository Docs
  -> domain model
  -> schema decisions
  -> architecture decisions

Current Database Target

• Provider: Neon PostgreSQL
• Schema authority: Drizzle
• Human admin: NocoDB or PostgreSQL-native alternatives
• Visual inspection: DBeaver / pgAdmin / Drizzle Studio depending on task

Direct vs Pooled Connections

Use direct connections for:

• Migrations
• Schema changes
• Introspection
• Manual database maintenance

Use pooled connections for:

• Serverless runtime
• Hono API
• n8n or automation runtime
• High-concurrency short requests

Object Storage

The system should use an S3-compatible abstraction.

Initial production target:

• Cloudflare R2

Possible local or future targets:

• S3-compatible local storage
• Backblaze B2 backup
• Other S3-compatible providers

Source-of-truth Documents

• docs/data/data-model.md
• docs/data/erd.mmd
• docs/data/schema-decisions.md
• packages/db/src/schema.ts