5-Layer Architecture Overview¶
Last Updated: 2026-07-11 Version: v0.2.0
Last Updated: 2026-01-20 Version: v0.2.0 Status: Production-Ready Coverage: 108+ Components
Reference¶
The Aries-Serpent/codex platform is organized into 5 horizontal layers, each handling specific responsibilities:
%%{init: {'accessibility': {'title': '5-Layer Architecture<br/>Layer 1: CLI/API<br/>Layer 2: ML Platform<br/>Layer 3: Data Pipeline<br/>Layer 4: Infrastructure<br/>Layer 5: Integration'}, 'theme': 'base', 'primaryColor': '#10b981', 'primaryBorderColor': '#059669', 'textColor': '#000'}}%%
graph TB
subgraph L1["Layer 1: Interface & CLI"]
CLI[" Command Line Interface<br/>Hydra configuration<br/>Command routing<br/>Help & documentation"]
API[" REST API Gateway<br/>Endpoint definitions<br/>Request validation<br/>Response formatting"]
end
subgraph L2["Layer 2: ML Platform"]
TRAIN[" Training Engine<br/>Model training loops<br/>Hyperparameter tuning<br/>Checkpoint management"]
EVAL[" Evaluation Engine<br/>Metric computation<br/>Benchmark runs<br/>Performance tracking"]
SERVE[" Serving/Inference<br/>Model loading<br/>Prediction pipeline<br/>Batch processing"]
end
subgraph L3["Layer 3: Data Pipeline"]
INGEST[" Code Ingestion<br/>File parsing<br/>AST analysis<br/>Token counting"]
RAG[" RAG System<br/>Vector indexing<br/>Semantic retrieval<br/>Context building"]
TRANSFORM[" Data Transformation<br/>Preprocessing<br/>Format conversion<br/>Feature extraction"]
end
subgraph L4["Layer 4: Infrastructure"]
CONFIG[" Configuration<br/>Hydra composition<br/>Secret management<br/>Environment handling"]
DB[" Database Layer<br/>Session storage<br/>Checkpoint persistence<br/>Metadata management"]
CACHE[" Caching<br/>Result caching<br/>Model cache<br/>Embedding cache"]
MONITOR[" Monitoring<br/>Metrics collection<br/>Health checks<br/>Alerts & notifications"]
end
subgraph L5["Layer 5: Integration"]
GH[" GitHub Integration<br/>PR automation<br/>Issue management<br/>Workflow triggers"]
ZENDESK[" Zendesk Integration<br/>Ticket sync<br/>Customer support<br/>CRM integration"]
CLOUD[" Cloud Services<br/>Storage backends<br/>Compute resources<br/>API services"]
AUTH[" Auth & Security<br/>User authentication<br/>Access control<br/>Audit logging"]
end
%% Dependencies flow upward
API --> TRAIN
API --> EVAL
API --> SERVE
CLI --> TRAIN
CLI --> EVAL
CLI --> SERVE
TRAIN --> INGEST
TRAIN --> RAG
TRAIN --> TRANSFORM
EVAL --> RAG
EVAL --> TRANSFORM
SERVE --> RAG
INGEST --> CONFIG
RAG --> DB
TRANSFORM --> CACHE
TRAIN --> MONITOR
EVAL --> MONITOR
SERVE --> MONITOR
GH -.integration.-> TRAIN
GH -.integration.-> EVAL
ZENDESK -.integration.-> SERVE
CLOUD -.backend.-> DB
CLOUD -.backend.-> CACHE
AUTH -.security.-> API
%% Styling
style L1 fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
style L2 fill:#dcfce7,stroke:#16a34a,stroke-width:2px
style L3 fill:#fef3c7,stroke:#d97706,stroke-width:2px
style L4 fill:#fce7f3,stroke:#db2777,stroke-width:2px
style L5 fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px
style CLI fill:#0284c7,stroke:#075985,stroke-width:2px,color:#fff
style API fill:#0284c7,stroke:#075985,stroke-width:2px,color:#fff
style TRAIN fill:#16a34a,stroke:#15803d,stroke-width:2px,color:#fff
style EVAL fill:#16a34a,stroke:#15803d,stroke-width:2px,color:#fff
style SERVE fill:#16a34a,stroke:#15803d,stroke-width:2px,color:#fff
style INGEST fill:#d97706,stroke:#b45309,stroke-width:2px,color:#fff
style RAG fill:#d97706,stroke:#b45309,stroke-width:2px,color:#fff
style TRANSFORM fill:#d97706,stroke:#b45309,stroke-width:2px,color:#fff
style CONFIG fill:#db2777,stroke:#9f1239,stroke-width:2px,color:#fff
style DB fill:#db2777,stroke:#9f1239,stroke-width:2px,color:#fff
style CACHE fill:#db2777,stroke:#9f1239,stroke-width:2px,color:#fff
style MONITOR fill:#db2777,stroke:#9f1239,stroke-width:2px,color:#fff
style GH fill:#7c3aed,stroke:#6d28d9,stroke-width:2px,color:#fff
style ZENDESK fill:#7c3aed,stroke:#6d28d9,stroke-width:2px,color:#fff
style CLOUD fill:#7c3aed,stroke:#6d28d9,stroke-width:2px,color:#fff
style AUTH fill:#7c3aed,stroke:#6d28d9,stroke-width:2px,color:#fff
Layer Descriptions¶
Layer 1: Interface & CLI¶
Responsibility: User interaction and request entry points Key Components: - CLI - Command-line interface with Hydra-based configuration management - REST API - HTTP endpoint gateway for programmatic access - Command Routing - Routes commands to appropriate layer 2 engines
Typical Flow:
Technologies: Click, Hydra, FastAPI
Layer 2: ML Platform¶
Responsibility: Core machine learning operations Key Components: - Training Engine - Model training with checkpoint management - Evaluation Engine - Metrics computation and benchmark execution - Serving/Inference - Model loading and prediction pipelines
Typical Flow:
Technologies: PyTorch, Ray, MLflow
Layer 3: Data Pipeline¶
Responsibility: Data ingestion, transformation, and retrieval Key Components: - Code Ingestion - Parses source files and generates ASTs - RAG System - Builds vector indices and retrieves relevant context - Transformation - Preprocesses and transforms data formats
Typical Flow:
Raw Files AST Analysis Token Encoding Vector Embedding Storage
Query Semantic Search Ranking Context Assembly Return
Technologies: tokenizers, transformers, FAISS/Pinecone, SentenceBERT
Layer 4: Infrastructure¶
Responsibility: System support, persistence, and observability Key Components: - Configuration - Hydra composition and secret management - Database - Session/checkpoint/metadata persistence - Caching - Results, model, and embedding caches - Monitoring - Metrics, health checks, alerts
Typical Flow:
Config Files Hydra Composition Validated Config Layer 2/3 Operations
Operations Metrics Monitoring Stack Alerts/Dashboards
Technologies: OmegaConf, SQLite, Redis/Memcached, Prometheus
Layer 5: Integration¶
Responsibility: External system connections Key Components: - GitHub Integration - PR automation, issue management - Zendesk Integration - CRM and support ticket sync - Cloud Services - Storage, compute, API services - Auth & Security - User management and access control
Typical Flow:
Technologies: GitHub API, Zendesk API, Cloud SDKs, OAuth/JWT
Data Flow Through Layers¶
graph LR
U[" User/System"] -->|"Input<br/>(command/API)"| L1["Layer 1<br/>Interface"]
L1 -->|"Validated<br/>Request"| L2["Layer 2<br/>ML Platform"]
L2 -->|"Data Need"| L3["Layer 3<br/>Data Pipeline"]
L3 -->|"Processed<br/>Data"| L2
L2 -->|"Metrics/Model"| L4["Layer 4<br/>Infrastructure"]
L4 -->|"Stored<br/>State"| L2
L2 -->|"Results"| L1
L1 -->|"Output<br/>(response)"| U
L2 -.->|"Events"| L5["Layer 5<br/>Integration"]
L5 -.->|"External<br/>Updates"| U
style U fill:#f0f0f0,stroke:#333,stroke-width:2px
style L1 fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
style L2 fill:#dcfce7,stroke:#16a34a,stroke-width:2px
style L3 fill:#fef3c7,stroke:#d97706,stroke-width:2px
style L4 fill:#fce7f3,stroke:#db2777,stroke-width:2px
style L5 fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px
Component Inventory by Layer¶
| Layer | Component | Status | Docs |
|---|---|---|---|
| L1 | CLI | Production | docs/cli |
| L1 | API Gateway | Production | docs/api |
| L2 | Training Engine | Production | docs/training |
| L2 | Evaluation Engine | Production | docs/evaluation |
| L2 | Serving | Production | src/inference/ |
| L3 | Code Ingestion | Production | src/codex/ingestion/ |
| L3 | RAG System | Production | docs/rag |
| L3 | Data Transform | Production | src/codex/data/ |
| L4 | Configuration | Production | docs/configuration |
| L4 | Database | Production | docs/database |
| L4 | Caching | Production | src/codex/cache/ |
| L4 | Monitoring | Production | docs/monitoring |
| L5 | GitHub Integration | Production | docs/integration |
| L5 | Zendesk Integration | Production | docs/zendesk |
| L5 | Cloud Services | Production | infrastructure/ |
| L5 | Auth & Security | Production | docs/security |
Key Design Principles¶
- Separation of Concerns - Each layer has a single responsibility
- Layered Dependency - Higher layers depend on lower layers, not vice versa
- Modularity - Components within layers are independently testable
- Scalability - Each layer can scale independently based on demand
- Observability - Layer 4 provides insights into all other layers
Next Steps¶
- See System Context Diagram for user/external system perspective
- See End-to-End Request Flow for request lifecycle
- See Component Dependencies for module relationships
- See individual layer docs for detailed architecture
Related Documentation: - ARCHITECTURE.md - Full architecture documentation - CODEBASE_MERMAID_MAPS.md - All system diagrams - System Context - C4 Context diagram