System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The ATMOS system architecture is designed as a modular, layered environment that facilitates deep codebase research and automated documentation generation. It leverages a "Local First" philosophy where documentation and metadata live alongside the source code in a structured directory format, allowing for seamless integration with AI agents and frontend interfaces. The architecture is primarily divided into a multi-layered documentation hierarchy and a specialized "Project Wiki" subsystem that automates technical knowledge extraction through deep source code analysis.
This architecture ensures that technical documentation is not merely a summary of README files but a high-fidelity representation of the actual implementation logic, business reasoning, and system evolution.
Sources: DOCUMENTATION.md:5-15, skills/project-wiki/SKILL.md:16-24, skills/project-wiki/README.md:13-25
Documentation Hierarchy
The project employs a four-layer documentation strategy to ensure progressive disclosure of information to different personas, ranging from new developers to automated AI agents.
Layered Structure
- Layer 1 (Entry Point): High-level overviews for quick navigation (README.md, AGENTS.md).
- Layer 2 (Deep Dive): Comprehensive architecture and technical specifications (docs/, specs/).
- Layer 3 (Component Work): Task-oriented instructions specific to applications and packages.
- Layer 4 (Code Structure): Deep dives into specific file and folder implementations.
Sources: DOCUMENTATION.md:21-55
The diagram above illustrates the progressive disclosure of information through the system's documentation layers.
Sources: DOCUMENTATION.md:21-55
Project Wiki Subsystem
The Project Wiki subsystem is a specialized architecture within ATMOS that automates the generation of research-grade documentation. It is designed to be agent-driven and schema-validated.
Core Components
| Component | Description |
|---|---|
Catalog (_catalog.json) | A hierarchical JSON tree defining the navigation structure and metadata. |
Metadata (_metadata/) | Collected Git history, PRs, and issues used to understand design intent. |
| Research Briefings | Intermediate documents used to guide subagents during deep-dive article generation. |
| Validation Scripts | Python/Bash utilities ensuring schema compliance and content depth. |
Sources: skills/project-wiki/references/output_structure.md:14-45, skills/project-wiki/SKILL.md:31-40
Data Flow and Generation Workflow
The generation of the wiki follows a sequential pipeline where metadata collection precedes research, which then informs the final Markdown content.
The workflow shows the transition from raw code analysis to validated documentation.
Sources: skills/project-wiki/SKILL.md:46-60, skills/project-wiki/SKILL.md:215-240
Frontend Wiki Integration
The architecture includes a dedicated "Wiki Tab" integration for the CenterStage UI, allowing users to view generated content directly within the application workspace.
Wiki Viewer Architecture
The Wiki Viewer utilizes a three-column resizable layout to provide a comprehensive reading experience.
- Navigation Sidebar: A recursive tree built from
_catalog.json. - Content Panel: Renders Markdown with support for frontmatter and custom components.
- Table of Contents (TOC): A heading-based navigation panel with scroll-spy capabilities.
Sources: specs/tech/project-wiki.md:28-40, specs/tech/project-wiki.md:118-131
State Management
State is managed via use-wiki-store.ts, a Zustand-based store that tracks catalog loading, active page content, and the existence of the .atmos/wiki/ directory.
The sequence illustrates the on-demand loading of wiki content via the system's WebSocket bridge.
Sources: specs/tech/project-wiki.md:73-88, specs/tech/project-wiki.md:188-210
Technical Standards
The system enforces strict technical standards for generated content to ensure architectural accuracy and readability.
- Diagram-Heavy: Every deep-dive article must contain at least 3 Mermaid diagrams to represent flows and structures.
- Source Traceability: Every code snippet or significant architectural claim must include a source file path citation.
- Metadata Specification: Articles must include YAML frontmatter for properties like
reading_time,level, andsources.
Sources: skills/project-wiki/references/output_structure.md:135-155, skills/project-wiki/SKILL.md:300-315
Summary
The ATMOS System Architecture prioritizes a structured, automated approach to documentation. By integrating deep Git metadata research with code-level analysis and a multi-layered frontend viewer, the system maintains a high degree of technical accuracy while remaining accessible to various developer personas.
Sources: DOCUMENTATION.md:195-205, skills/project-wiki/README.md:120-135