Claude-skill-registry aidb-architecture

Comprehensive architectural reference for AIDB core and MCP integration.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/aidb-architecture" ~/.claude/skills/majiayu000-claude-skill-registry-aidb-architecture && rm -rf "$T"

manifest: skills/data/aidb-architecture/SKILL.md

source content

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