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.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

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.
nameaidb-architecture
descriptionComprehensive architectural reference for AIDB core and MCP integration.
version1.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 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

  1. Component Delegation - Focused components vs monolithic classes
  2. Language-Agnostic Design - Pluggable adapter architecture
  3. Human-Cadence Debugging - Breakpoints before execution, one step at a time
  4. Resource Lifecycle Management - Multi-tier cleanup with defense-in-depth
  5. Parent-Child Session Support - JavaScript subprocess debugging
  6. Single Request Path - No circular dependencies in DAP client
  7. Three-Tier Cleanup - DAP disconnect → process termination → port release

For detailed explanations, see patterns-and-resources.md.


Resource Management Summary

Three-Tier Cleanup Strategy:

  1. Tier 1: DAP disconnect (graceful adapter shutdown)
  2. Tier 2: Process termination (SIGTERM → SIGKILL escalation)
  3. 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)

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