For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /reference/docs/decisions/0034-fresh-skeleton.md.

0034 — fresh service-first skeleton

Status: Accepted. Date: 30 September 2026.

A new fresh branch from main, replacing the existing application with an empty skeleton based on the sibling multilingual reference.

The branch starts at main 8046ea0f1 in the existing repository and is intended to merge back into main. The complete previous main tree is moved with git mv into legacy/, preserving its exact blobs and modes. The active root is replaced by the skeleton. The archive is excluded from active builds and checked against its recorded Git inventory. The original working checkout, its uncommitted work and running installations remain independent of this branch.

The selected topology is Next.js Web, Go API, Python Metallo, Go Themelio and Go Beto. Each domain service owns direct service-local folders, including an empty contexts directory. Preserve framework-independent cores, one-root transactions, canonical identity, receipts, outboxes, retry/dead-letter/replay, typed Protobuf contracts and server-authorised Centrifugo. No production business authority is assigned by these scaffolds.

The multilingual reference contributes independently built runtime foundations; its demo contexts, business payloads, routes and UI are removed. Shared envelopes and empty codec registries provide extension points, with no default permissive payload decoder or channel authority. Current-state persistence remains the choice.

Infrastructure source is architecture-reset at b228782dd, rather than main. Adapt its pinned GitHub Actions, ARM64 runner labels and Rocky development k3s bootstrap. The k3s role retains checksum-verified downloads, SELinux, secret at-rest encryption, firewall controls and guarded persistent mounts. Separate fresh ownership markers prevent adoption of its existing data. Provider registrations, product releases and Ceph-specific storage are omitted because this skeleton owns no corresponding capability. Shared PVCs use each cluster's default development storage class.

Minikube uses a dedicated containerd/Calico profile. Development k3s uses the same Kustomize base with a registry-image overlay. Full CI and optional signed image publication are separate from cluster activation. The Docker integration harness is disposable test infrastructure derived from the Kubernetes workload source.

Verification requires deterministic checks and real PostgreSQL/broker/browser lanes. A rendered manifest or a passing Docker test does not qualify Minikube, k3s, remote CI or production. Context onboarding must add the relevant owner, transaction, transport, security and browser recovery evidence.

Clarification, 9 October 2026: an internal aggregate can precede its browser feature. Metallo uses an explicit None projection registration to save that aggregate and its receipts without a realtime contract or notification rows. Unregistered aggregate keys remain errors. Once a browser projection is enabled, its typed bytes and delivery intent commit atomically with the state change. Instantiate and run assigns launch browser notifications to Milestone 2 (7A).

Amendment, 16 October 2026: Themelio uses Python, following the Operations service at multilingual reference commit a9d7bf6. It retains direct service-local folders, with Dependency Injector in services/composition and separate persistence, messaging, realtime and HTTP adaptors. Shared technical input/response models are schema-generated. Central command execution, durable private command reactions, private-domain publication and explicit realtime publication follow that baseline. The service owns no contexts or business registrations. Its versioned delivery extension is applied only to Themelio databases by administration tooling; Metallo and Beto retain their current persistence contracts. Existing Pharos wire envelopes, authentication and deployment boundaries remain in use.

Amendment, 26 October 2026: Web consumes the API's assembled browser OpenAPI document through a committed Orval Fetch and TanStack Query client. Contract generation produces the embedded Go document, typed browser operations, models and test fixtures together and drift checks compare the complete generated tree. AAI login start remains a native browser form navigation so the identity-provider redirect and callback-cookie protocol stay under browser control.

Page source

Source snapshot · Revision f928834c8.