| name | aidb-architecture |
| description | Comprehensive architectural reference for AIDB core and MCP integration. Covers 6-layer architecture (MCP, API, Session, Adapter, DAP Client, Protocol), component organization, data flow patterns, and design decisions. Use when explaining overall system design or understanding how layers interact. |
| version | 1.0.0 |
| tags | ["architecture","session","api","dap","mcp","design-patterns","components","data-flow"] |
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: API Layer (aidb/api/) โ
โ โโโ DebugAPI - Main entry point โ
โ โโโ SessionManager, SessionBuilder โ
โ โโโ .introspection / .orchestration operations โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Layer 3: Session Layer (aidb/session/) โ
โ โโโ Session - Component delegation 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.py) โ
โ โโโ Fully-typed DAP specification (see dap-protocol-guide) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Quick Navigation
"I want to understand..."
| Topic | Resource | Contents |
|---|
| MCP & API Layers | api-mcp-layer.md | 12 tools, handler pattern, response system, DebugAPI, introspection/orchestration |
| Session Layer | session-layer.md | Component delegation, 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, API layer, introspection/orchestration |
| session-layer.md | Session architecture, component delegation, 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 โ API โ 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
