Architecture

This is the public system cartography of Apollia OS, written as an arc42 structure with a C4 model. It is the map a contributor, an integrator, or a technical evaluator reads to understand how the runtime is built and why.

What this section is, and is not

It describes the shape of the system: its goals, its constraints, its parts, how they fit, and where the debt is. It does not repeat the reference material. Whenever a fact belongs to the API, the CLI, or the SDK, this section links to the generated reference rather than restating it, so there is one source per fact:

• HTTP API reference for the host driving contract.
• CLI reference for the command surface.
• SDK / ctx contract for what the Python of a package calls.
• Configuration and the native tool catalog.

Concepts that deserve their own narrative live under Explanation, for example the accountability model. This section links to them instead of duplicating them.

Honesty policy

Every claim here is anchored to what the code actually does, not to what older design notes hoped it would do. Where a capability is partial or absent, it is stated plainly in Risks and technical debt. A cartography that hides its gaps is not a map, it is a brochure.

Reading order

1. Introduction and goals
2. Constraints
3. Context and scope
4. Solution strategy
5. Building block view
6. Runtime view
7. Cross-cutting concepts
8. Architecture decisions
9. Risks and technical debt
10. Glossary