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

| Topic                    | Resource                                                         | Contents                                                                        |
| ------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **MCP & Service Layers** | [api-mcp-layer.md](resources/api-mcp-layer.md)                   | 12 tools, handler pattern, response system, DebugService, execution/stepping    |
| **Session Layer**        | [session-layer.md](resources/session-layer.md)                   | Infrastructure hub, SessionState, SessionConnector, parent-child sessions       |
| **Adapter Layer**        | [adapter-architecture.md](resources/adapter-architecture.md)     | DebugAdapter base, ProcessManager, PortManager, lifecycle hooks, Python/JS/Java |
| **DAP Client**           | [dap-client.md](resources/dap-client.md)                         | Single request path, Future-based async, event handling, design decisions       |
| **Patterns & Resources** | [patterns-and-resources.md](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
1. **Language-Agnostic Design** - Pluggable adapter architecture
1. **Human-Cadence Debugging** - Breakpoints before execution, one step at a time
1. **Resource Lifecycle Management** - Multi-tier cleanup with defense-in-depth
1. **Parent-Child Session Support** - JavaScript subprocess debugging
1. **Single Request Path** - No circular dependencies in DAP client
1. **Three-Tier Cleanup** - DAP disconnect → process termination → port release

For detailed explanations, see [patterns-and-resources.md](resources/patterns-and-resources.md).

______________________________________________________________________

## Resource Management Summary

**Three-Tier Cleanup Strategy:**

1. **Tier 1:** DAP disconnect (graceful adapter shutdown)
1. **Tier 2:** Process termination (SIGTERM → SIGKILL escalation)
1. **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](resources/api-mcp-layer.md)                   | MCP server, 12 tools, handler pattern, Service layer, execution/stepping    |
| [session-layer.md](resources/session-layer.md)                   | Session architecture, infrastructure hub, state management, parent-child    |
| [adapter-architecture.md](resources/adapter-architecture.md)     | Adapter base class, components, lifecycle hooks, language-specific patterns |
| [dap-client.md](resources/dap-client.md)                         | DAP client design, single request path, Future-based async, events          |
| [patterns-and-resources.md](resources/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