Cial

Closed Core. Editable Platform. One container per tenant. Multi-tenant App layer.

See PLAN.md for the build plan and /app/data/cial-production-infrastructure.md for the architecture rationale.

---

Repository layout

cial/                  ← repo root, mounted at /cial inside the tenant container
├─ core/               CLOSED — the harness shipped as a Docker image to every tenant
│   ├─ back/           Express + WS · AI sessions · auth · git engine · vault · DB proxy
│   ├─ front/          Next.js · the rescue UI served at /.cial/*
│   ├─ ui/             @cial/core-ui  — shared React components
│   ├─ sdk/            @cial/sdk      — Platform code talks to Core through this
│   ├─ protocol/       @cial/protocol — shared TS types + Zod schemas
│   ├─ edge/           @cial/edge     — edge proxy + supervisor (PID 1)
│   ├─ scripts/        dev-tenant.mjs · smoke.mjs · smoke-process.mjs
│   └─ docker/         Multi-stage Dockerfile · two Linux users (cial + agent)
│
├─ platform/           OPEN — starter cloned into the tenant container, agent-editable
│   ├─ front/          Next.js · the editable user-owned frontend
│   └─ back/           Node · the editable user-owned backend
│
├─ app/                CLOSED — multi-tenant ops layer (lives OUTSIDE the tenant container)
│   ├─ api/            Next.js · owner signup, billing, admin
│   ├─ orchestrator/   Fly Machines provisioning
│   ├─ router/         Subdomain → tenant Machine ID
│   ├─ scheduler/      Central cron / trigger fabric
│   └─ docker/         Dockerfile for App itself
│
├─ docs/               Architecture, ops, self-edit refs (start at file-structure.md)
└─ .claude/            Project skills (cial:self-edit, cial:build, cial:restart)

See docs/file-structure.md for the canonical, runtime-accurate map of paths inside the container.

---

Stack

• Node 22 · pnpm 9 · turbo 2
• TypeScript 5.7 strict · NodeNext
• Express 4 (Core Back, Platform Back, App orchestrator)
• Next.js 16 with Turbopack (Core Front, Platform Front, App api)
• better-sqlite3 (per-tenant DB) · Postgres + Drizzle (App DB)
• Better-Auth · Zod · pino
• ESLint 9 (flat) · Prettier

---

Common commands

pnpm install              # install all workspace deps
pnpm dev                  # run everything in parallel
pnpm build                # build everything
pnpm typecheck            # tsc --noEmit across packages
pnpm lint                 # eslint
pnpm format               # prettier --write
pnpm smoke                # boot all 5 services on isolated ports + probe

Per-package:

pnpm --filter @cial/back dev
pnpm --filter @cial/platform-front build

---

Architecture conventions (Express services)

• Modular layout: src/modules/<feature>/{routes,service,repository,schemas,types}.ts
• Routes never touch the database
• Services never touch Express (req/res)
• Repositories never touch services (data access only)
• Validation at the edge with Zod
• Dependency injection by hand at src/index.ts
• Centralized error middleware (last app.use)
• Structured logs via pino · no console.log
• Graceful shutdown on SIGTERM/SIGINT

---

Smoke harness

pnpm smoke boots every service on isolated high ports (18000–18100), polls each one until it responds, runs an HTTP probe matrix (health + a 501-stub envelope check on Core Back), then tears everything down. Exits 0 on success.

Service	Port	Probe
@cial/back	18080	/healthz → 200, /vault → 501 envelope
@cial/platform-back	18081	/health → 200
@cial/app-api	18100	/api/health → 200
@cial/front	18001	/.cial → 200
@cial/platform-front	18000	/ → 200

---

Status

Scaffolding only. See PLAN.md for the phased implementation plan.