Skip to content
Architecture

Understand Your System

Module maps, concept extraction, and ADR management. Understand system design at a glance.

Key Features

Module maps and dependency graphs
Concept extraction for domain vocabulary
ADR (Architectural Decision Records) management
Origin explanation for code provenance
Automatic documentation generation
Codebase health metrics

Module Architecture

$ ckb architecture

Project Architecture
====================

Modules (6):
  api/          → HTTP handlers, middleware, routing
  internal/     → Core business logic
  pkg/          → Shared libraries (exported)
  cmd/          → Application entrypoints
  config/       → Configuration loading
  migrations/   → Database migrations

Dependency Graph:
  cmd/server → api/ → internal/ → pkg/
                   ↘ config/
  cmd/worker → internal/ → pkg/

Key Metrics:
  Total symbols:     2,847
  Public API size:   156 symbols
  Internal:          2,691 symbols
  Cyclic deps:       0 (clean!)
  Avg module depth:  3.2

Hottest modules (last 30 days):
  1. internal/checkout  (47 commits)
  2. api/v2             (32 commits)
  3. pkg/auth           (28 commits)

Domain Concept Extraction

Automatically extract domain vocabulary from your codebase. Great for onboarding and documentation.

$ ckb concepts

Key Concepts in Codebase
========================

Entities (12):
  User          - Core user model with auth
  Order         - Purchase order with line items
  Product       - Catalog item with pricing
  Cart          - Shopping cart (session-based)
  Payment       - Payment transaction record
  ...

Actions (8):
  Checkout      - Cart → Order conversion
  Fulfillment   - Order shipping process
  Refund        - Payment reversal
  ...

Patterns (5):
  Repository    - Data access pattern (internal/repo/)
  Service       - Business logic layer (internal/svc/)
  Handler       - HTTP request handling (api/)
  ...

Usage: ckb explain <concept> for details

Architectural Decision Records

Track why decisions were made. Link ADRs to code so future developers understand the reasoning.

# Create an ADR

$ ckb adr new "Use PostgreSQL"

Created: docs/adr/0012-use-postgresql.md

Title: Use PostgreSQL
Status: Proposed
Date: 2024-01-15

## Context
[Describe the context...]

## Decision
[Describe the decision...]

## Consequences
[Describe consequences...]

# Link ADR to code

$ ckb adr link 0012 internal/repo/

Linked ADR-0012 to:
  internal/repo/postgres.go
  internal/repo/migrations/

Now when someone asks:
  "Why PostgreSQL?"

CKB can explain:
  See ADR-0012: Use PostgreSQL
  Decision date: 2024-01-15
  Author: @sarah

MCP Tools

getArchitecture

Get module maps and dependency graphs

ckb architecture
explainSymbol

AI-powered explanation of any symbol

ckb explain UserService
explainFile

Get a summary of what a file does

ckb explain internal/api/handler.go
listKeyConcepts

Extract domain vocabulary from your codebase

ckb concepts
recordDecision

Create and manage ADRs (Architectural Decision Records)

ckb adr new "Use PostgreSQL for persistence"

See the big picture

Understand your architecture without reading every file.

DocumentationGet Started