aidb-architecture
Comprehensive architectural reference for AIDB core and MCP integration. Covers 6-layer architecture (MCP, Service, Session, Adapter, DAP Client, Protocol), component organization, data flow patterns, and design decisions. Use when explaining overall system design or understanding how layers interact.
When & Why to Use This Skill
This Claude skill serves as a comprehensive architectural reference for the AIDB core and MCP (Model Context Protocol) integration. It provides a deep dive into a structured 6-layer architecture—ranging from the MCP layer to the Protocol layer—designed to help developers navigate complex codebases, understand component responsibilities, and trace data flows. By detailing design patterns like component delegation and three-tier resource cleanup, it empowers engineers to make informed architectural decisions and build scalable debugging tools for AI agents.
Use Cases
- System Onboarding: Use the 6-layer map to quickly orient new developers on the responsibilities of the MCP, Service, Session, Adapter, DAP Client, and Protocol layers.
- Data Flow Analysis: Trace the lifecycle of a debugging command, such as an MCP tool call being translated into a DAP (Debug Adapter Protocol) request.
- Architectural Decision Making: Determine the correct layer for implementing new features or modifications to ensure system integrity and maintain separation of concerns.
- Resource Management Optimization: Implement and debug complex cleanup sequences (DAP disconnect, process termination, and port release) to prevent orphaned processes and port conflicts.
- Cross-Layer Debugging: Identify and resolve bottlenecks or errors that occur during interaction between the high-level AI interface and low-level language adapters.
| name | aidb-architecture |
|---|---|
| description | Comprehensive architectural reference for AIDB core and MCP integration. |
| version | 1.0.0 |
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 bydev-cli-developmentskill)
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-developmentskill - DAP protocol details → Use
dap-protocol-guideskill - MCP tool development → Use
mcp-tools-developmentskill
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 | 12 tools, handler pattern, response system, DebugService, execution/stepping |
| Session Layer | session-layer.md | Infrastructure hub, SessionState, SessionConnector, parent-child sessions |
| Adapter Layer | adapter-architecture.md | DebugAdapter base, ProcessManager, PortManager, lifecycle hooks, Python/JS/Java |
| DAP Client | dap-client.md | Single request path, Future-based async, event handling, design decisions |
| Patterns & Resources | patterns-and-resources.md | Architectural principles, three-tier cleanup, resource management, data flows |
Key Architectural Principles
- Component Delegation - Focused components vs monolithic classes
- Language-Agnostic Design - Pluggable adapter architecture
- Human-Cadence Debugging - Breakpoints before execution, one step at a time
- Resource Lifecycle Management - Multi-tier cleanup with defense-in-depth
- Parent-Child Session Support - JavaScript subprocess debugging
- Single Request Path - No circular dependencies in DAP client
- Three-Tier Cleanup - DAP disconnect → process termination → port release
For detailed explanations, see patterns-and-resources.md.
Resource Management Summary
Three-Tier Cleanup Strategy:
- Tier 1: DAP disconnect (graceful adapter shutdown)
- Tier 2: Process termination (SIGTERM → SIGKILL escalation)
- 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 | MCP server, 12 tools, handler pattern, Service layer, execution/stepping |
| session-layer.md | Session architecture, infrastructure hub, state management, parent-child |
| adapter-architecture.md | Adapter base class, components, lifecycle hooks, language-specific patterns |
| dap-client.md | DAP client design, single request path, Future-based async, events |
| 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