# Aidb Architecture > Comprehensive architectural reference for AIDB core and MCP integration. Use when this capability is needed. - Skill: `tomevault-io/aidb-architecture` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/aidb-architecture` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/aidb-architecture/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/aidb-architecture --- # AIDB Architecture Skill ## Overview This skill provides a comprehensive architectural reference for understanding AIDB's multi-layered architecture, focusing on `aidb` core library and `aidb_mcp` MCP integration. **Purpose:** Enable developers to navigate the codebase confidently, understand component responsibilities, trace data flows, and make correct architectural decisions. **Scope:** - **PRIMARY:** `aidb/` (core debugging library), `aidb_mcp/` (MCP server integration) - **SECONDARY:** `aidb_common/`, `aidb_logging/` (supporting utilities) - **EXCLUDED:** `aidb_cli/` (covered by `dev-cli-development` skill) ______________________________________________________________________ ## When to Use This Skill **Use this skill when:** - Understanding overall system architecture - Tracing data flow across layers (e.g., MCP tool call → DAP adapter) - Identifying component responsibilities - Making architectural decisions (which layer to modify) - Understanding design patterns and rationale - Debugging cross-layer issues **Do NOT use this skill for:** - Deep adapter implementation patterns → Use `adapter-development` skill - DAP protocol details → Use `dap-protocol-guide` skill - MCP tool development → Use `mcp-tools-development` skill ______________________________________________________________________ ## 6-Layer Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ Layer 1: MCP Layer (aidb_mcp/) │ │ ├── 12 debugging tools for AI agents │ │ ├── Handler dispatch, response optimization │ │ └── Session management integration │ ├─────────────────────────────────────────────────────────────┤ │ Layer 2: Service Layer (aidb/service/) │ │ ├── DebugService - Main entry point │ │ ├── SessionManager, SessionBuilder (in aidb/session/) │ │ └── .execution / .stepping / .breakpoints / .variables │ ├─────────────────────────────────────────────────────────────┤ │ Layer 3: Session Layer (aidb/session/) │ │ ├── Session - Infrastructure hub │ │ ├── SessionState, SessionConnector │ │ ├── SessionRegistry, ResourceManager │ │ └── Parent-child session support (JavaScript) │ ├─────────────────────────────────────────────────────────────┤ │ Layer 4: Adapter Layer (aidb/adapters/) │ │ ├── DebugAdapter - Component delegation base │ │ ├── ProcessManager, PortManager, LaunchOrchestrator │ │ └── Language Adapters - Python, JavaScript, Java │ ├─────────────────────────────────────────────────────────────┤ │ Layer 5: DAP Client Layer (aidb/dap/client/) │ │ ├── DAPClient - Single request path │ │ ├── Transport, RequestHandler, EventProcessor │ │ └── MessageRouter, ConnectionManager │ ├─────────────────────────────────────────────────────────────┤ │ Layer 6: Protocol Layer (aidb/dap/protocol/) │ │ └── Fully-typed DAP specification (see dap-protocol-guide) │ └─────────────────────────────────────────────────────────────┘ ``` ______________________________________________________________________ ## Quick Navigation **"I want to understand..."** | Topic | Resource | Contents | | ------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------- | | **MCP & Service Layers** | [api-mcp-layer.md](resources/api-mcp-layer.md) | 12 tools, handler pattern, response system, DebugService, execution/stepping | | **Session Layer** | [session-layer.md](resources/session-layer.md) | Infrastructure hub, SessionState, SessionConnector, parent-child sessions | | **Adapter Layer** | [adapter-architecture.md](resources/adapter-architecture.md) | DebugAdapter base, ProcessManager, PortManager, lifecycle hooks, Python/JS/Java | | **DAP Client** | [dap-client.md](resources/dap-client.md) | Single request path, Future-based async, event handling, design decisions | | **Patterns & Resources** | [patterns-and-resources.md](resources/patterns-and-resources.md) | Architectural principles, three-tier cleanup, resource management, data flows | ______________________________________________________________________ ## Key Architectural Principles 1. **Component Delegation** - Focused components vs monolithic classes 1. **Language-Agnostic Design** - Pluggable adapter architecture 1. **Human-Cadence Debugging** - Breakpoints before execution, one step at a time 1. **Resource Lifecycle Management** - Multi-tier cleanup with defense-in-depth 1. **Parent-Child Session Support** - JavaScript subprocess debugging 1. **Single Request Path** - No circular dependencies in DAP client 1. **Three-Tier Cleanup** - DAP disconnect → process termination → port release For detailed explanations, see [patterns-and-resources.md](resources/patterns-and-resources.md). ______________________________________________________________________ ## Resource Management Summary **Three-Tier Cleanup Strategy:** 1. **Tier 1:** DAP disconnect (graceful adapter shutdown) 1. **Tier 2:** Process termination (SIGTERM → SIGKILL escalation) 1. **Tier 3:** Port release (registry updates) **Why Order Matters:** Prevents port conflicts and orphaned processes. **Key Components:** - Process Registry (`aidb/resources/pids.py`) - Port Registry (`aidb/resources/ports.py`) - Orphan Cleanup (`aidb/resources/orphan_cleanup.py`) - ResourceManager (`aidb/session/resource.py`) ______________________________________________________________________ ## Related Skills | Skill | Use For | | ----------------------- | ------------------------------------------------- | | `adapter-development` | Language-specific adapter implementation patterns | | `dap-protocol-guide` | DAP protocol specification and usage | | `mcp-tools-development` | MCP tool creation and agent optimization | ______________________________________________________________________ ## Resources | Resource | Content | | ---------------------------------------------------------------- | --------------------------------------------------------------------------- | | [api-mcp-layer.md](resources/api-mcp-layer.md) | MCP server, 12 tools, handler pattern, Service layer, execution/stepping | | [session-layer.md](resources/session-layer.md) | Session architecture, infrastructure hub, state management, parent-child | | [adapter-architecture.md](resources/adapter-architecture.md) | Adapter base class, components, lifecycle hooks, language-specific patterns | | [dap-client.md](resources/dap-client.md) | DAP client design, single request path, Future-based async, events | | [patterns-and-resources.md](resources/patterns-and-resources.md) | Architectural principles, resource management, cleanup, data flows | **Documentation:** - Architecture overview → `docs/developer-guide/overview.md` - Component source → `src/aidb/`, `src/aidb_mcp/`, `src/aidb_cli/`, `src/aidb_common/`, `src/aidb_logging/` ______________________________________________________________________ ## Quick Reference **6 Layers:** MCP → Service → Session → Adapter → DAP Client → Protocol **Key Patterns:** Component delegation, language-agnostic, human-cadence debugging, resource lifecycle, parent-child sessions, single request path **5 Resource Files:** api-mcp-layer, session-layer, adapter-architecture, dap-client, patterns-and-resources --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/ai-debugger-inc) — claim your Tome and manage your conversions.