Civility architecture specs #
The reference specs for how Civility works internally — data formats, protocols, interfaces, and invariants. These describe realized behavior: what the shipped code actually does. Design exploration, deferred ideas, and unrealized proposals are out of scope. When a realized feature has a known limitation, the spec notes it in one line.
For how to build apps against these packages, see docs/apps/; for how to run a
server, see docs/hosting/. Those are task guides — this directory is the
protocol/interface reference they link into.
Stable references (§N.S.T) #
Every feature is one numbered file under features/. A feature owns its number: its headings are ## N.S and ### N.S.T, so a section number is globally unique and its first digit resolves the file. Cite spec from anywhere — docs, code comments, commit messages — by the bare number, e.g. §1.1.1 = features/01_store.md → 1.1.1 Document, or §3.6.1 = features/03_sync.md → 3.6.1 Lazy Blob Sync.
| § | Feature | File | Primary package(s) |
|---|---|---|---|
| 1 | Store | features/01_store.md |
@civility/store |
| 2 | Blobs | features/02_blobs.md |
@civility/store/blobs |
| 3 | Sync | features/03_sync.md |
@civility/cloud |
| 4 | Data confidentiality | features/04_encryption.md |
Application-owned representations |
| 5 | Auth | features/05_auth.md |
@civility/hono/auth |
| 6 | Accounts | features/06_accounts.md |
@civility/hono (api/account/) |
| 7 | App Identity | features/07_app_identity.md |
@civility/cloud (manifest) + @civility/hono |
| 8 | User Identity | features/08_user_identity.md |
@civility/crypto (identity) + @civility/hono |
| 9 | Share | features/09_share.md |
@civility/cloud (+ @civility/hono) |
| 11 | Services | features/11_services.md |
@civility/services |
| 12 | Typed Contracts | features/12_types.md |
@civility/hono (share/type_registry.ts) |
| 13 | Server | features/13_server.md |
@civility/hono |
| 14 | Errors | features/14_errors.md |
@civility/errors |
| 15 | Billing | features/15_billing.md |
@civility/hono/billing (+ CLI civ api billing) |
| 16 | Admin | features/16_admin.md |
@civility/hono (ui/routes/admin/) |
| 17 | Cloud CLI | features/17_cli.md |
@civility/cli |
| 18 | UI Bindings | features/18_ui.md |
@civility/ui |
Package README.md files remain as external usage guides; the internal design notes that used to live in each package's SPEC.md are folded into the features above.
System architecture #
Two runtimes — a client app (built the Inro way; see Inro §1–§5) and a server (CivServer) — meet at the change log: an append-only sequence of JSON Patches stamped with HLC timestamps (§1.1.2, §3.1).
┌───────────────────────────────────────────────────────────────┐
│ App (an Inro PWA — @inro/ui, @inro/workers, @inro/cli) │
├───────────────────────────────────────────────────────────────┤
│ @civility/cloud — the Civility Cloud client │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ . store-bound — re-exports /api │ │
│ │ CloudStore — a Store that syncs (§3, §9) │ │
│ │ .share — CivShare publisher (§9) │ │
│ │ .shared(type) — cross-app replicas (§3.9.5) │ │
│ │ typed contracts (§12) │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ /api — Describes Civility Cloud API interaction │ │
│ │ getShare, … — anonymous reader (§9) │ │
│ │ identity/resolve — user + cross-server (§8) │ │
│ │ sessions — devices (§5.13) │ │
│ │ authorship — verify signatures │ │
│ │ request() — the one HTTP path (§14) │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ /manifest (zod) · /worker (§3.6) │ │
│ └──────────────────────────────────────────────────────┘ │
│ internal: Synced, CloudShare (via CloudStore) │
│ @civility/services — credentialed egress (§11) │
│ @civility/ui — civ-* components, bound (§18) │
│ structurally to the above │
├───────────────────────────────────────────────────────────────┤
│ @civility/store/blobs — local blob storage (§2) │
│ @civility/store — data, versioning, history, merge (§1) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Store / Collection<T> / Document<T> / Property<T> │ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ core/ — HLC, JSON Patch, merge, schema, validate, │ │
│ │ history (pure functions, zero I/O) │ │
│ ├──────────┬──────────┬───────────────────────────────┤ │
│ │ idb │ deno-fs │ memory │
│ └──────────┴──────────┴───────────────────────────────┘ │
└───────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────┐
│ CivServer │
├──────────────────────────────────────────────────────────────┤
│ @civility/hono — server framework (§13, §5) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ /auth /sync /admin /billing /services /share /social│ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ AuthAdapter / ChangeStore / ObjectStorage │ │
│ ├──────────┬──────────────────────────────────────────┤ │
│ │ sqlite │ shared adapter interfaces (§13.4) │ │
│ └──────────┴──────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────┐
│ @civility/errors — shared error codes & envelopes (§14) │
└──────────────────────────────────────────────────────────────┘
Package tiers #
Every package sits in a tier, and the tier is a rule about what it may import — not a description of what it happens to do today.
| Tier | Packages | Rule |
|---|---|---|
| internal | crypto, errors |
No other Civility dependencies. |
| local core | store, blobs |
Zero network. No knowledge a server exists. |
| cloud | cloud, services |
Everything that talks to a Civility server. |
| bindings | ui |
Structural collaborators only; renders Inro elements by tag. |
| server | hono, cli |
Runs a server; may depend on anything above. |
Boundary principle. @civility/store (§1) owns data, versioning, history, diffing, and merge.
@civility/cloud (§3) owns client-side connection and sync orchestration. @civility/hono (§13)
owns server-side HTTP handling, storage adapters, and auth (§5). App-owned
confidentiality (§4) is outside the change-log protocol; services (§11) are a
separate credentialed-egress subsystem.
The /api contract #
Within the cloud tier, a package that both talks to a server and wraps a local store splits into two surfaces:
…/api— free functions overfetch. Explicit arguments, typed results, raisesCivilityApiError(§14). May import@civility/errors,@civility/crypto, and pure subpaths such as@civility/store/validate. May not import@civility/storeitself — not evenimport type.- the root barrel — the store-bound orchestrator, which re-exports its own
/apisurface plus whatever store types it needs, so an app that has a store anyway needs only one import.
The point is that an anonymous page — a share viewer, a thread feed — can use the API surface with
no account, no CloudStore, and no storage backend.
Type-only imports count. import type { Collection } costs no runtime bytes but still makes the
store a resolution dependency, which is exactly the coupling the tier removes.
The directory groups by function; the barrel carries the guarantee. packages/cloud/api/ holds
every module whose job is talking to a server — including two that are deliberately not on the
published /api barrel: api/sync.ts (SyncApi), whose payloads are the store's own
EntryChange and so is store-coupled by nature, and api/social.ts, which
is store-free but unreleased (§10). Grouping by function keeps related code together; checking the
barrel rather than the directory is what keeps the guarantee true.
This is enforced, not documented-and-hoped: scripts/check_layers.ts resolves each guarded
entrypoint's full module graph with deno info and fails on any forbidden specifier at any depth.
It runs as deno task test:layers, a dependency of deno task test. Transitive leaks are the
whole reason it checks the graph rather than the import list — TypeDoc reached the store through
three hops of type-only imports before it was lifted out.
Every running server also serves its own generated API reference — Swagger UI at /api/v1,
OpenAPI JSON at /api/v1/doc — which always matches the deployed version.
Contributor docs #
testing.md— running the test suites (incl. the Postgres-backed tests).