AxiomNode Documentation

Last updated: 2026-05-08.

Central documentation repository for AxiomNode architecture, operations, and platform governance.

Main sections

Architecture

• Architecture index
• Platform architecture
• Repository map
• Use cases
• C4 views (context, containers, components)
• Domain model
• Key sequence flows
• Quality attribute scenarios
• Glossary
• Master alignment (mapping with AI development master)
• Architecture Decision Records

Guides

• Guides index
• Platform functional overview
• Platform capability matrix
• Documentation architecture
• Capability analysis template
• Architecture document template
• Operations runbook template
• Repository documentation template
• Capability dossiers index
• Service communication model
• Local edge integration
• Backoffice React development
• Mobile app development (Firebase)
• Primary validation workflows
• Migration guide for existing repositories
• Repository standards adoption guide

Operations

• Operations index
• Environments and secrets
• Secrets distribution guide
• Deployment strategy
• Branch protection policy
• GitHub governance baseline
• CI/CD workflow map
• Repository minimum standards
• Functionality review baseline
• Test coverage policy
• Coverage baseline report
• Runtime routing and service targeting
• AI services recovery runbook

Recommended reading order

1. Start with architecture and repository map.
2. Read deployment strategy and CI/CD workflow map before changing delivery behavior.
3. Define or update contracts in contracts-and-schemas.
4. Regenerate SDK artifacts in shared-sdk-client.
5. Implement runtime changes in service repositories.
6. Review runtime routing implications when changes affect AI topology or service targeting.
7. Roll out through platform-infra and observe via observability-platform.

Documentation ownership model

The workspace intentionally separates project-wide documentation from repository-local documentation.

Documentation kept in this repository

Use this repository for cross-repository concerns:

• current platform architecture and repository topology
• deployment policy and CI/CD chain behavior
• runtime routing behavior that spans multiple repositories
• environment model, secret governance, and operational runbooks
• shared delivery rules, maintenance policy, and architectural constraints

This repository intentionally excludes roadmap, backlog, audit-history, and change-history documents. It should describe the current platform only.

Documentation kept in each repository

Each runtime or platform repository should document its own concrete implementation surface:

• repository responsibility and runtime role
• local development workflow
• public or private endpoints exposed by that repository
• persistent state owned by that repository
• repository-specific CI gates, smoke checks, and release constraints
• local architecture notes that do not need to be duplicated globally

Current platform snapshot

Layer	Repositories	Notes
Public edge	api-gateway	Single public ingress, stable client-facing boundary
Experience	bff-mobile, bff-backoffice, backoffice, mobile-app	Channel-specific contracts and operator experience
Domain runtime	microservice-users, microservice-quizz, microservice-wordpass	Private business services with owned persistence
AI capability	ai-engine	Generation API, stats API, cache, llama runtime
Platform governance	platform-infra, contracts-and-schemas, shared-sdk-client, secrets, observability-platform	Delivery, contracts, SDKs, secrets, and operations tooling

Backoffice access is role-gated through microservice-users. The current role model includes SuperAdmin, Admin, Inspector, Viewer, and Gamer; Inspector is a read-only review role that can inspect Backoffice role assignments without mutating user permissions.

Current runtime reality to document explicitly

• The deployed Kubernetes topology and the effective runtime topology are not always identical.
• Only ai-engine-api holds persisted runtime targeting state (the llama target); api-gateway and bff-backoffice hold none.
• Staging may run ai-engine-api and ai-engine-stats in-cluster while the llama runtime remains external, or it may render the optional full in-cluster AI overlay for controlled diagnostics.
• Documentation must distinguish environment defaults, persisted overrides, and live effective targets.

Documentation maintenance rules

• Update docs in the same PR/commit window as architecture or workflow changes.
• Avoid undocumented cross-repo decisions.
• Keep contract and SDK documentation synchronized.
• Preserve valid relative links across the repository; CI now checks Markdown link targets.

Documentation quality expectations

Core architectural and operational documents should be:

• current-state accurate rather than aspirational
• explicit about ownership, scope, and failure boundaries
• linked to the repositories and workflows they describe
• written so that operators and engineers can distinguish static deployment state from effective runtime state
• updated whenever delivery policy, topology, or runtime control behavior changes

Repository-local documentation should additionally be:

• concrete about ports, routes, stored state, and dependencies
• clear about what is owned locally versus inherited from the wider platform
• aligned with the central documents in this repository rather than restating conflicting summaries

Design assets

Brand and UI design assets are maintained in design/.