AIOS Architecture Documentation Index

🌐 EN | PT | ES

Version: 2.1.1 Last Updated: 2026-01-26 Status: Official Reference

This index provides navigation to all architecture documentation for AIOS v4.

Note: Official framework documentation (coding-standards, tech-stack, source-tree) has been consolidated in docs/framework/. See Framework README for details.

📁 Directory Structure


docs/architecture/
├── ARCHITECTURE-INDEX.md     # This file
├── high-level-architecture.md # System overview
├── module-system.md          # 4-module architecture
├── mcp-system-diagrams.md    # MCP architecture diagrams
├── memory-layer.md           # Memory system architecture
├── adr/                      # Architectural Decision Records
└── [framework/]              # See docs/framework/ for standards

🎯 Quick Links by Topic

Core Architecture

Document	Description	Status
High-Level Architecture	Overview of AIOS v4 architecture	✅ Current
Module System	4-module modular architecture	✅ Current
Memory Layer	Memory system architecture	✅ Current

MCP & Integrations

Document	Description	Status
MCP System Diagrams	MCP architecture diagrams	✅ Current

Note: MCP management is handled via Docker MCP Toolkit (Story 5.11). Use @devops agent with *setup-mcp-docker for configuration.

Agent System

Document	Description	Status
Agent Responsibility Matrix	Agent roles and responsibilities	✅ Current
Agent Config Audit	Configuration audit	✅ Current

Tools & Utilities

Document	Description	Status
Utility Integration Guide	Utility integration	✅ Current
CI/CD	CI/CD pipeline documentation	✅ Current

Health Check System (HCS)

Document	Description	Status
HCS Check Specifications	Health check specs	✅ Current
HCS Execution Modes	Execution modes	✅ Current
HCS Self-Healing Spec	Self-healing specification	✅ Current

Squad System

Document	Description	Status
Squad Improvement Analysis	Improvement analysis	✅ Current
Squad Improvement Approach	Recommended approach	✅ Current

Architectural Decision Records (ADR)

Document	Description	Status
ADR COLLAB-1	Current state audit	✅ Current
ADR COLLAB-2	Proposed configuration	✅ Current
ADR HCS	Health Check System	✅ Current
ADR Isolated VM	Isolated VM decision	✅ Current

Reference Documents (Official in docs/framework/)

Document	Description	Status
Tech Stack	Technology decisions	✅ Current
Coding Standards	Code standards	✅ Current
Source Tree	Project structure	✅ Current

Note: These are linked to docs/framework/ which is the official location.

Research & Analysis

Document	Description	Status
Contribution Workflow Research	Contribution analysis	✅ Current
Introduction	Original intro (v2.0)	📦 Legacy

🏗️ Architecture Overview Diagram


┌─────────────────────────────────────────────────────────────────────────┐
│                     AIOS v4 ARCHITECTURE                              │
│                                                                         │
│   ┌─────────────────────────────────────────────────────────────────┐   │
│   │                    MULTI-REPO STRUCTURE                          │   │
│   │                                                                  │   │
│   │   SynkraAI/aios-core ◄───── Central Hub                       │   │
│   │          │                    - Framework core                   │   │
│   │          │                    - 11 base agents                   │   │
│   │          │                    - Discussions hub                  │   │
│   │          │                                                       │   │
│   │   ┌──────┴───────┐                                               │   │
│   │   │              │                                               │   │
│   │   ▼              ▼                                               │   │
│   │ aios-squads   mcp-ecosystem                                      │   │
│   │ (MIT)         (Apache 2.0)                                       │   │
│   └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│   ┌─────────────────────────────────────────────────────────────────┐   │
│   │                    MODULAR ARCHITECTURE                          │   │
│   │                                                                  │   │
│   │   .aios-core/                                                    │   │
│   │   ├── core/           ← Framework foundations                    │   │
│   │   ├── development/    ← Agents, tasks, workflows                 │   │
│   │   ├── product/        ← Templates, checklists                    │   │
│   │   └── infrastructure/ ← Scripts, tools, integrations             │   │
│   └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│   ┌─────────────────────────────────────────────────────────────────┐   │
│   │                    QUALITY GATES 3 LAYERS                        │   │
│   │                                                                  │   │
│   │   Layer 1: Pre-commit ──► Layer 2: PR ──► Layer 3: Human        │   │
│   │   (Husky/lint-staged)    (CodeRabbit)    (Strategic Review)     │   │
│   │        30%                  +50%              +20%               │   │
│   │                        (80% automated)                           │   │
│   └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

📚 Reading Order for New Contributors

Quick Start (30 min)

Deep Dive (2-3 hours)

Complete Mastery (1-2 days)

All documents in this index
ADR documents for architectural decisions
HCS documentation for health check system

📝 Document Status Legend

Status	Meaning
✅ Current	Up-to-date with v4.2
⚠️ Update needed	Needs terminology or content update
📦 Legacy	Historical reference
🆕 New	Recently created

Last Updated: 2026-01-26 Maintainer: @architect (Aria)