System architecture

Scope

This page owns how Zenith works as a technical system. It routes from the stable conceptual boundaries into implementation specs. Data rights belong in Zenith Research - data and intelligence. Epistemic structures belong in Zenith Research - knowledge and epistemics.

Current answer

A Zenith deployment has two stable substrates:

• Hub: the runtime node that executes agents and tools, exposes APIs and MCP, handles intake and queues, and connects to other hubs.
• Vault: the persistent knowledge substrate that remains readable and useful independent of any one agent runtime.

Frank coordinates information in motion. Raziel maintains what the organization knows. Processes declare work. Skills provide reusable workflow knowledge. Executors perform units of work. Review and telemetry close the learning loop.

The intended deployment model is self-hosted or organization-controlled. Federation happens between hubs through explicit interfaces and synchronization contracts, not by merging every participant into one hosted database.

Evidence and influences

• base architecture: ARCHITECTURE.
• system boundary: ai-os-hub-concept - Hub, Vault, Arena, and Space relationships.
• runtime substrate: ai-os-infrastructure-layer.
• orchestration: ai-os-orchestration-layer.
• agent model: ai-os-agent-model.
• executor model: ai-os-executor-model.
• process model: ai-os-process-schema.
• filesystem and knowledge layout: ai-os-file-system.
• implementation inventory: hg-agent-code-inventory.

Runtime ontology

• ai-os-the-system - the live operational context agents inhabit.
• ai-os-prompt-taxonomy - where persistent, persona, process, skill, and request instructions belong.
• ai-os-memory-model - conversation, episodic, and profile memory boundaries.
• ai-os-raziel - vault-level archivist and knowledge agent.
• ai-os-codebase-mapping - base repository mapping and gaps.
• zenith-root-hub-config - root-hub configuration and inherited deployment model.

Hub and workspace implementation

• zenith-hub repo — Phase 0 architecture and stack - current web and infrastructure stack.
• Zenith hub workspace architecture — Forgejo repos, tiered storage, and federated hub access - workspace and storage boundary.
• Zenith hub review surface — asset routing, capability matrix, and comment anchor model - artifact review kernel.
• zenith-research.ca serves three surfaces — review, repo display, and assets display with workspace-styled Obsidian-like Markdown rendering - prior three-surface architecture.
• documents rendered on zenith-research.ca inherit the styling of the workspace that produced them - origin-scoped presentation.

Public wiki and ontology distribution

The canonical company wiki is authored in the private Vault and will be published as a selective, read-only projection at zenith-research.ca/wiki. The zenith-landing application is the renderer and deployment surface, not an authoring authority.

The public company-wiki vocabulary extends the existing versioned Zenith Ontology distributed at zenith-research.ca/ontology. Devgraph remains the ontology authority. The company-wiki profile is additive and does not create runtime graph labels unless a later accepted decision changes that boundary.

Zenith Research wiki publication contract defines the repository boundaries, routes, visibility gate, sanitization rules, JSON-LD output, and release sequence.

Federation

• the hub is a node and client in a distributed mesh where each hub exposes an API and MCP interface and vaults plug into it from outside - current mesh model.
• WorkspaceSync service — swappable internal boundary for hub-to-hub workspace publishing.
• Zenith consortium — hub registry and relay for the connected workspace mesh.
• hub namespacing on Zenith is the routing primitive that enables white-label clients to receive bucket drops through the Zenith network.
• vault-to-hub publishing routes through the hub API with checksums so published content can be validated and reconciled across both sides.

Intake, queue, and process execution

• ISS-047 - unified Hub Event System specification.
• the bucket drop is the universal hub intake primitive across all three entry routes.
• the hub intake system is an AI interview engine over a high-throughput queue with hub-owner-defined schemas for each intake type.
• IO contracts are defined by the receiving hub so the inbox owner controls the schema of what it accepts.
• Frank is strictly a dispatcher and coordinator — he does not execute work himself.
• self-identification is a hub push operation not a Frank-dispatched intake event — the push direction is user to hub and Frank's involvement is a downstream reaction.
• session types are directories with CLAUDE.md files — the directory is the invocation context and the session type is the persona.
• ISS-049 - session-type directory implementation.

Skills and context architecture

• frank skill files should have a references subdirectory for deep workflow docs loaded on demand.
• skills provide workflow knowledge while MCP provides tool access — neither is sufficient alone.
• skills are portable across Claude surfaces because they are instruction text, not platform-specific integrations.
• the skill description field is the only signal Claude uses to decide whether to load a skill.
• three-level progressive disclosure minimizes token usage while preserving specialized skill expertise.
• iterating on one hard task until success then extracting the winning approach produces better skills than broad testing.

Authentication, security, and privacy

• Zenith auth architecture — ADA wallet, BetterAuth, and cross-subdomain sessions.
• GDPR compliance in Zenith — report and implementation requirements.
• the hub intake boundary is the natural GDPR compliance gate — personal data is classified consented encrypted and routed at a single point.
• personal data must never enter git — only anonymized identifiers belong in version control so right to erasure is a clean database delete.
• self-sovereign personal data encrypted with the user's public key means the platform operator cannot be compelled to produce readable data.
• GDPR applies based on the residency of data subjects not the location of the server.
• Canada's PIPEDA adequacy decision with the EU gives Canadian-operated services a clean legal path for processing EU personal data.
• psychographic profiling is special-category data under GDPR Article 9 requiring explicit documented consent.
• Anonymous permanent machine exclusion from turn signing requires a hidden hardware root and finalized revocation - specialized identity and revocation research.

Implementation record

• 2026-03-20-hub-architecture-session-report - event, queue, Rolodex, and publishing decisions from the architecture session.
• zenith-hub-foundation-initiative - foundation work decomposition.
• the hub ships a native Mac OS transcription app that logs voice input and agent responses to a local SQLite database with PostgreSQL as the upgrade path - local client substrate.

Open questions and tensions

• Which architecture note is the single active replacement for overlapping early ai-os-* specs?
• What is the minimal supported deployment topology for the first external organization?
• Which modules require independent databases and APIs versus routes on the main Hub gateway?
• How do rights envelopes and review trails persist across Vault, operational database, Git, and object storage?
• What federation protocol is committed for Phase 1 rather than merely swappable in theory?
• Which agent-runtime behavior is live, partially implemented, or still represented only by Claude Code conventions?

Related canonical pages

• Zenith Research - products and capabilities - product surfaces built from this architecture.
• Zenith Research - knowledge and epistemics - Vault and Raziel semantics.
• Zenith Research - data and intelligence - data, review, and rights contracts.
• Zenith Research - roadmap decisions and open questions - implementation sequence and unresolved architecture choices.