Connected apps with 3rd-party data hosts jsr.io/@civility
README.md

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 over fetch. Explicit arguments, typed results, raises CivilityApiError (§14). May import @civility/errors, @civility/crypto, and pure subpaths such as @civility/store/validate. May not import @civility/store itself — not even import type.
  • the root barrel — the store-bound orchestrator, which re-exports its own /api surface 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).