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 |
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
1---2name: aidb-architecture3description: 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.4---56# AIDB Architecture Skill78## Overview910This skill provides a comprehensive architectural reference for understanding AIDB's multi-layered architecture, focusing on `aidb` core library and `aidb_mcp` MCP integration.1112**Purpose:** Enable developers to navigate the codebase confidently, understand component responsibilities, trace data flows, and make correct architectural decisions.1314**Scope:**1516- **PRIMARY:** `aidb/` (core debugging library), `aidb_mcp/` (MCP server integration)17- **SECONDARY:** `aidb_common/`, `aidb_logging/` (supporting utilities)18- **EXCLUDED:** `aidb_cli/` (covered by `dev-cli-development` skill)1920______________________________________________________________________2122## When to Use This Skill2324**Use this skill when:**2526- Understanding overall system architecture27- Tracing data flow across layers (e.g., MCP tool call → DAP adapter)28- Identifying component responsibilities29- Making architectural decisions (which layer to modify)30- Understanding design patterns and rationale31- Debugging cross-layer issues3233**Do NOT use this skill for:**3435- Deep adapter implementation patterns → Use `adapter-development` skill36- DAP protocol details → Use `dap-protocol-guide` skill37- MCP tool development → Use `mcp-tools-development` skill3839______________________________________________________________________4041## 6-Layer Architecture4243```44┌─────────────────────────────────────────────────────────────┐45│ Layer 1: MCP Layer (aidb_mcp/) │46│ ├── 12 debugging tools for AI agents │47│ ├── Handler dispatch, response optimization │48│ └── Session management integration │49├─────────────────────────────────────────────────────────────┤50│ Layer 2: Service Layer (aidb/service/) │51│ ├── DebugService - Main entry point │52│ ├── SessionManager, SessionBuilder (in aidb/session/) │53│ └── .execution / .stepping / .breakpoints / .variables │54├─────────────────────────────────────────────────────────────┤55│ Layer 3: Session Layer (aidb/session/) │56│ ├── Session - Infrastructure hub │57│ ├── SessionState, SessionConnector │58│ ├── SessionRegistry, ResourceManager │59│ └── Parent-child session support (JavaScript) │60├─────────────────────────────────────────────────────────────┤61│ Layer 4: Adapter Layer (aidb/adapters/) │62│ ├── DebugAdapter - Component delegation base │63│ ├── ProcessManager, PortManager, LaunchOrchestrator │64│ └── Language Adapters - Python, JavaScript, Java │65├─────────────────────────────────────────────────────────────┤66│ Layer 5: DAP Client Layer (aidb/dap/client/) │67│ ├── DAPClient - Single request path │68│ ├── Transport, RequestHandler, EventProcessor │69│ └── MessageRouter, ConnectionManager │70├─────────────────────────────────────────────────────────────┤71│ Layer 6: Protocol Layer (aidb/dap/protocol/) │72│ └── Fully-typed DAP specification (see dap-protocol-guide) │73└─────────────────────────────────────────────────────────────┘74```7576______________________________________________________________________7778## Quick Navigation7980**"I want to understand..."**8182| Topic | Resource | Contents |83| ------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------- |84| **MCP & Service Layers** | [api-mcp-layer.md](resources/api-mcp-layer.md) | 12 tools, handler pattern, response system, DebugService, execution/stepping |85| **Session Layer** | [session-layer.md](resources/session-layer.md) | Infrastructure hub, SessionState, SessionConnector, parent-child sessions |86| **Adapter Layer** | [adapter-architecture.md](resources/adapter-architecture.md) | DebugAdapter base, ProcessManager, PortManager, lifecycle hooks, Python/JS/Java |87| **DAP Client** | [dap-client.md](resources/dap-client.md) | Single request path, Future-based async, event handling, design decisions |88| **Patterns & Resources** | [patterns-and-resources.md](resources/patterns-and-resources.md) | Architectural principles, three-tier cleanup, resource management, data flows |8990______________________________________________________________________9192## Key Architectural Principles93941. **Component Delegation** - Focused components vs monolithic classes951. **Language-Agnostic Design** - Pluggable adapter architecture961. **Human-Cadence Debugging** - Breakpoints before execution, one step at a time971. **Resource Lifecycle Management** - Multi-tier cleanup with defense-in-depth981. **Parent-Child Session Support** - JavaScript subprocess debugging991. **Single Request Path** - No circular dependencies in DAP client1001. **Three-Tier Cleanup** - DAP disconnect → process termination → port release101102For detailed explanations, see [patterns-and-resources.md](resources/patterns-and-resources.md).103104______________________________________________________________________105106## Resource Management Summary107108**Three-Tier Cleanup Strategy:**1091101. **Tier 1:** DAP disconnect (graceful adapter shutdown)1111. **Tier 2:** Process termination (SIGTERM → SIGKILL escalation)1121. **Tier 3:** Port release (registry updates)113114**Why Order Matters:** Prevents port conflicts and orphaned processes.115116**Key Components:**117118- Process Registry (`aidb/resources/pids.py`)119- Port Registry (`aidb/resources/ports.py`)120- Orphan Cleanup (`aidb/resources/orphan_cleanup.py`)121- ResourceManager (`aidb/session/resource.py`)122123______________________________________________________________________124125## Related Skills126127| Skill | Use For |128| ----------------------- | ------------------------------------------------- |129| `adapter-development` | Language-specific adapter implementation patterns |130| `dap-protocol-guide` | DAP protocol specification and usage |131| `mcp-tools-development` | MCP tool creation and agent optimization |132133______________________________________________________________________134135## Resources136137| Resource | Content |138| ---------------------------------------------------------------- | --------------------------------------------------------------------------- |139| [api-mcp-layer.md](resources/api-mcp-layer.md) | MCP server, 12 tools, handler pattern, Service layer, execution/stepping |140| [session-layer.md](resources/session-layer.md) | Session architecture, infrastructure hub, state management, parent-child |141| [adapter-architecture.md](resources/adapter-architecture.md) | Adapter base class, components, lifecycle hooks, language-specific patterns |142| [dap-client.md](resources/dap-client.md) | DAP client design, single request path, Future-based async, events |143| [patterns-and-resources.md](resources/patterns-and-resources.md) | Architectural principles, resource management, cleanup, data flows |144145**Documentation:**146147- Architecture overview → `docs/developer-guide/overview.md`148- Component source → `src/aidb/`, `src/aidb_mcp/`, `src/aidb_cli/`, `src/aidb_common/`, `src/aidb_logging/`149150______________________________________________________________________151152## Quick Reference153154**6 Layers:** MCP → Service → Session → Adapter → DAP Client → Protocol155156**Key Patterns:** Component delegation, language-agnostic, human-cadence debugging, resource lifecycle, parent-child sessions, single request path157158**5 Resource Files:** api-mcp-layer, session-layer, adapter-architecture, dap-client, patterns-and-resources
diegosouzapw