---

name: aidb-architecture description: 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. version: 1.0.0 tags:

• architecture
• session
• service
• 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: 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)

---

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