Architecture

Architecture

Git is the source of truth. The database is only an index and a stats store. Static files on disk are the delivery mechanism.

flowchart LR
  Registry[Git: /registry] --> Builder[packages/builder] --> Static[Static /r/*.json on disk]
  Static --> CLI[apps/cli]
  CLI --> Events[POST /api/events]
  Events --> API[apps/api] --> DB[(Postgres)]
  Caddy[Caddy] --> Static
  Caddy --> API

Loading

Reading components (CLI or website) never hits the API or database — Caddy serves static files. The API handles only dynamic concerns: events/stats, likes, newsletter, admin.

Monorepo layout

Path	Description	Status
apps/api	Hono server: events, stats, likes, newsletter, RSS	Planned (stub)
apps/cli	@framebits/cli — init, add (list/search/diff/update planned)	Ready
apps/web	React + Vite catalog, detail pages, sandboxed playground	Ready
packages/shared	Zod schemas + inferred types (single source of truth)	Ready
packages/db	Drizzle schema, migrations, DB client, seed/sync	Planned (stub)
packages/builder	Registry build pipeline	Ready
packages/config	Shared tsconfig + ESLint config	Ready
registry/	Component sources — data, never executed by CLI/API/site	Ready
deploy/	Docker Compose, Caddyfile, deploy scripts	Placeholder

The builder pipeline

pnpm build:registry [--out dir] [--check]

1. Discover every meta.json under /registry
2. Validate all of them (collects every error, then fails)
3. Cross-validate: duplicate slugs, missing deps, cycles (with full path), slug/folder mismatches, missing sources or demos
4. Type-check all sources against pinned React + Tailwind types
5. Analyze imports (TS compiler API): undeclared externals fail; registry imports must use alias form and be declared
6. Security scan (AST + CSS): eval, Function, network/cookie access fail
7. Normalize line endings/BOM, map to CLI target paths
8. Hash canonical JSON (SHA-256, key-order independent, excludes version/title/timestamps)
9. Version via registry.lock.json (new → 1.0.0, changed → patch; immutable <slug>@<version>.json archives)
10. Emit atomically: byte-identical output on identical input
11. Index search (MiniSearch) + manifest + JSON schemas

--check runs everything and writes nothing — it gates every PR in CI.

Key contracts

Artifact	Schema	Notes
meta.json (human-written)	MetaSchema	Strict: unknown keys rejected
/r/<slug>.json	RegistryItemSchema	schemaVersion: 1, POSIX-only file paths
/r/index.json	RegistryIndexSchema	Published/deprecated only, sorted
framebits.json	CliConfigSchema	See Configuration

All schemas live in packages/shared — never duplicated. Details: docs/CONTRACTS.md and docs/BUILDER.md in the repo.