2. Core Subsystems
2.1 Subsystem Inventory​
Batho is composed of tightly-integrated subsystems that work together to provide code intelligence capabilities. Each subsystem has a well-defined responsibility and can be tested independently.
| Subsystem | Purpose | Status |
|---|---|---|
| AST Extraction | tree-sitter based multi-language parsing | Production |
| Code Graph | In-memory hypergraph with adjacency indexing | Production |
| Arrow Graph Backend | Columnar memory-mapped graph storage with CSR/CSC adjacency indexes | Production |
| BSG Map & Compression | Flat symbol index, priority token budgeting, and rule loaders | Production |
| Dependency Indexer | stdlib and installed virtual environment dependency indexer | Production |
| Storage Registry | Arrow IPC database manager, BSG scratch store, and unified cache | Production |
| Integrity Verification | Database checker, repair engine, and report generation | Production |
| Orchestrator Layer | High-level command implementations (build, patch, export, load, gc) | Production |
| Community Detection | Greedy modularity clustering based code network grouping | Production |
| MCP Server | Model Context Protocol server exposing code graph capabilities | Production |
| Shared Utilities | Hashing, file I/O, encoding, ignore patterns, logging, path sanitization, memory monitoring | Production |
| CLI Command Suite | Command interface parsing and subcommand orchestration | Production |
2.2 Technology Stack​
Runtime Environment​
| Layer | Technology | Version |
|---|---|---|
| Language Runtime | Python | 3.12+ |
| AST Parsing | tree-sitter | 0.25+ |
| Language Pack | tree-sitter-language-pack | Latest |
| Configuration | Pydantic | 2.x |
Interface Layer​
| Layer | Technology | Purpose |
|---|---|---|
| CLI Framework | argparse (stdlib) | Command-line interface |
| Data Export | JSON / Pretty | Programmatic data output |
| MCP Protocol | FastMCP | Model Context Protocol server (stdio) |
Data Layer​
| Layer | Technology | Purpose |
|---|---|---|
| Registry / Cache | msgpack + Arrow IPC | Durable database storage and high-speed memory-mapping |
| Artifact Bundle | ZIP ZSTD Archive | Transport packaging format |
Development & Testing​
| Layer | Technology | Purpose |
|---|---|---|
| Testing | pytest + pytest-cov | 8.x / 5.x |
| Build Tool | uv | Latest |
| Linting | ruff, mypy | Code quality |
2.3 Subsystem Interactions​
Subsystems communicate through well-defined interfaces:
Figure 4: Subsystem Interactions - Dependency graph showing how Batho subsystems communicate through well-defined interfaces.
2.4 Data Flow Between Subsystems​
- Command Phase: CLI → Orchestrator (parse options, load config)
- Extraction Phase: Orchestrator → Extractor → Cache + Graph
- Resolution Phase: Graph → SymbolIndex → Graph (cross-file resolution)
- Intelligence Phase: Graph → BSG → Rules → BSG (semantic tagging)
- Storage & Serialization: BSG → Storage Registry (Arrow IPC views)
- Output Phase: Storage Registry → Orchestrator → CLI (Command output / JSON Export)