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

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

aidb-architecture

Install Skill

SKILL.md