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..."

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)

Related Skills

Resources

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