C4 Level4 Code

C4 Level 4: Code Diagram

The Code diagram is the lowest level of detail, showing how a single component is implemented. It's usually optional — only use it when the internal implementation is too complex to understand without a visual map.

> "The code level is typically only used to describe complex parts of the codebase, or when you want to generate diagrams from the code." — Simon Brown

---

🎯 When to Use Level 4

| Situation | Diagram Type | Why | |-----------|-------------|-----| | Complex domain model with many entities | UML Class Diagram | Show inheritance, composition, associations | | Database schema with 10+ tables | ER Diagram | Show relationships, keys, constraints | | State machine logic | State Diagram | Show states and transitions | | Complex algorithm | Activity/Sequence Diagram | Show flow and decision points | | API contract design | OpenAPI/Interface Diagram | Show endpoints, request/response types |

When NOT to use: Simple CRUD, standard patterns, or when the code is self-explanatory.

---

🛠 UML Class Diagram

Notation Reference

┌─────────────────────┐
│     ClassName       │  ← Class/Interface name
├─────────────────────┤
│ + publicField: Type │  ← Attributes (+ public, - private, # protected)
│ - _privateField: int│
├─────────────────────┤
│ + method(): Return  │  ← Methods
│ - _helper(): void   │
└─────────────────────┘

Relationships:
  ───────▶   Association (A uses B)
  ──────◆   Composition (A owns B, B cannot exist without A)
  ──────◇   Aggregation (A has B, B can exist independently)
  ────▷   Inheritance (A extends B)
  - - -▷   Implementation (A implements B)
  ─────▶  Dependency (A depends on B)

Mermaid Template: Domain Model

classDiagram
    class Order {
        +UUID id
        +UUID customerId
        +Money total
        +OrderStatus status
        +DateTime createdAt
        +pay(payment: Payment)
        +cancel(reason: String)
        +ship(trackingNumber: String)
    }

    class OrderItem {
        +UUID id
        +UUID productId
        +int quantity
        +Money unitPrice
        +Money subtotal()
    }

    class Money {
        +Decimal amount
        +Currency currency
        +add(other: Money): Money
        +multiply(factor: int): Money
    }

    class Customer {
        +UUID id
        +Email email
        +Address shippingAddress
        +placeOrder(items: OrderItem[]): Order
    }

    class Payment {
        +UUID id
        +Money amount
        +PaymentMethod method
        +PaymentStatus status
        +process(): Result
    }

    Order "1" *-- "0..*" OrderItem : contains
    Order "1" --> "1" Money : total
    Customer "1" --> "0..*" Order : places
    Order "1" --> "0..1" Payment : has
    OrderItem "1" --> "1" Money : unitPrice

Mermaid Template: Repository Pattern

classDiagram
    class OrderRepository {
        >
        +findById(id: UUID): Order
        +findByCustomer(customerId: UUID): Order[]
        +save(order: Order): Order
        +delete(id: UUID): void
    }

    class PostgresOrderRepository {
        -db: *sql.DB
        -mapper: OrderMapper
        +findById(id: UUID): Order
        +findByCustomer(customerId: UUID): Order[]
        +save(order: Order): Order
        +delete(id: UUID): void
    }

    class OrderMapper {
        +toEntity(row: sql.Row): Order
        +toModel(order: Order): OrderRecord
    }

    class OrderService {
        -repo: OrderRepository
        -eventBus: EventPublisher
        +placeOrder(cmd: PlaceOrderCommand): Result
        +cancelOrder(id: UUID, reason: String): Result
    }

    OrderRepository  OrderMapper : uses
    OrderService --> OrderRepository : depends on

---

🗄 ER Diagram (Entity Relationship)

Notation Reference

Cardinality:
  ||--o{   One-to-Many (1:N)
  ||--||   One-to-One (1:1)
  }o--o{   Many-to-Many (N:M)

Keys:
  PK = Primary Key
  FK = Foreign Key
  UK = Unique Key

Mermaid Template: E-Commerce Database

erDiagram
    USER ||--o{ ORDER : places
    USER ||--o{ ADDRESS : has
    ORDER ||--|{ ORDER_ITEM : contains
    ORDER ||--o{ PAYMENT : has
    PRODUCT ||--o{ ORDER_ITEM : "ordered in"
    PRODUCT }o--o{ CATEGORY : "belongs to"

    USER {
        uuid id PK
        varchar email UK
        varchar password_hash
        varchar first_name
        varchar last_name
        timestamp created_at
    }

    ADDRESS {
        uuid id PK
        uuid user_id FK
        varchar street
        varchar city
        varchar postal_code
        varchar country
        boolean is_default
    }

    ORDER {
        uuid id PK
        uuid user_id FK
        decimal total_amount
        varchar currency
        varchar status
        timestamp created_at
        timestamp updated_at
    }

    ORDER_ITEM {
        uuid id PK
        uuid order_id FK
        uuid product_id FK
        int quantity
        decimal unit_price
    }

    PRODUCT {
        uuid id PK
        varchar name
        text description
        decimal price
        int stock_quantity
        boolean is_active
    }

    CATEGORY {
        uuid id PK
        varchar name
        uuid parent_id FK
    }

    PAYMENT {
        uuid id PK
        uuid order_id FK
        decimal amount
        varchar method
        varchar status
        varchar transaction_id UK
        timestamp processed_at
    }

---

💻 Language-Specific Templates

Go: Structs and Interfaces

// Value Object — immutable, validated at creation
type Money struct {
    Amount   decimal.Decimal
    Currency string // ISO 4217: USD, EUR, VND
}

func NewMoney(amount decimal.Decimal, currency string) (Money, error) {
    if !isValidCurrency(currency) {
        return Money{}, fmt.Errorf("invalid currency: %s", currency)
    }
    if amount.IsNegative() {
        return Money{}, fmt.Errorf("amount cannot be negative")
    }
    return Money{Amount: amount, Currency: currency}, nil
}

func (m Money) Add(other Money) (Money, error) {
    if m.Currency != other.Currency {
        return Money{}, fmt.Errorf("cannot add different currencies")
    }
    return NewMoney(m.Amount.Add(other.Amount), m.Currency)
}

// Entity — has identity, mutable state with business rules
type Order struct {
    ID        uuid.UUID
    CustomerID uuid.UUID
    Items     []OrderItem
    Total     Money
    Status    OrderStatus
    CreatedAt time.Time
    events    []DomainEvent // unexported: internal only
}

func (o *Order) Pay(payment Payment) error {
    if o.Status != OrderStatusPending {
        return fmt.Errorf("cannot pay order with status %s", o.Status)
    }
    if !payment.Amount.Equals(o.Total) {
        return fmt.Errorf("payment amount %v does not match order total %v", 
            payment.Amount, o.Total)
    }
    o.Status = OrderStatusPaid
    o.events = append(o.events, OrderPaidEvent{OrderID: o.ID})
    return nil
}

func (o *Order) PullEvents() []DomainEvent {
    events := o.events
    o.events = nil
    return events
}

// Repository Interface (Port in Hexagonal)
type OrderRepository interface {
    FindByID(ctx context.Context, id uuid.UUID) (*Order, error)
    FindByCustomer(ctx context.Context, customerID uuid.UUID) ([]*Order, error)
    Save(ctx context.Context, order *Order) error
    Delete(ctx context.Context, id uuid.UUID) error
}

Python: Dataclasses and Protocols

from dataclasses import dataclass, field
from decimal import Decimal
from typing import Protocol, List
from uuid import UUID, uuid4
from datetime import datetime

# Value Object — frozen dataclass
@dataclass(frozen=True)
class Money:
    amount: Decimal
    currency: str  # ISO 4217

    def __post_init__(self):
        if self.amount  "Money":
        if self.currency != other.currency:
            raise ValueError("Cannot add different currencies")
        return Money(self.amount + other.amount, self.currency)

    def multiply(self, factor: int) -> "Money":
        return Money(self.amount * factor, self.currency)

# Entity
@dataclass
class Order:
    id: UUID = field(default_factory=uuid4)
    customer_id: UUID = field(default_factory=uuid4)
    items: List["OrderItem"] = field(default_factory=list)
    total: Money = field(default_factory=lambda: Money(Decimal("0"), "USD"))
    status: "OrderStatus" = field(default="PENDING")
    created_at: datetime = field(default_factory=datetime.utcnow)
    _events: List["DomainEvent"] = field(default_factory=list, repr=False)

    def pay(self, payment: "Payment") -> None:
        if self.status != "PENDING":
            raise ValueError(f"Cannot pay order with status {self.status}")
        if payment.amount != self.total:
            raise ValueError("Payment amount does not match order total")
        self.status = "PAID"
        self._events.append(OrderPaidEvent(order_id=self.id))

    def pull_events(self) -> List["DomainEvent"]:
        events = self._events.copy()
        self._events.clear()
        return events

# Repository Protocol (Port)
class OrderRepository(Protocol):
    def find_by_id(self, order_id: UUID) -> Order: ...
    def find_by_customer(self, customer_id: UUID) -> List[Order]: ...
    def save(self, order: Order) -> Order: ...
    def delete(self, order_id: UUID) -> None: ...

TypeScript: Classes and Interfaces

// Value Object — immutable, validated
class Money {
    constructor(
        public readonly amount: Decimal,
        public readonly currency: string // ISO 4217
    ) {
        if (amount.isNegative()) {
            throw new Error('Amount cannot be negative');
        }
        if (!isValidCurrency(currency)) {
            throw new Error(`Invalid currency: ${currency}`);
        }
    }

    add(other: Money): Money {
        if (this.currency !== other.currency) {
            throw new Error('Cannot add different currencies');
        }
        return new Money(this.amount.add(other.amount), this.currency);
    }

    multiply(factor: number): Money {
        return new Money(this.amount.mul(factor), this.currency);
    }

    equals(other: Money): boolean {
        return this.amount.equals(other.amount) && this.currency === other.currency;
    }
}

// Entity
class Order {
    private _events: DomainEvent[] = [];

    constructor(
        public readonly id: UUID,
        public readonly customerId: UUID,
        public items: OrderItem[],
        public total: Money,
        public status: OrderStatus = OrderStatus.PENDING,
        public readonly createdAt: Date = new Date()
    ) {}

    pay(payment: Payment): void {
        if (this.status !== OrderStatus.PENDING) {
            throw new Error(`Cannot pay order with status ${this.status}`);
        }
        if (!payment.amount.equals(this.total)) {
            throw new Error('Payment amount does not match order total');
        }
        this.status = OrderStatus.PAID;
        this._events.push(new OrderPaidEvent(this.id));
    }

    pullEvents(): DomainEvent[] {
        const events = [...this._events];
        this._events = [];
        return events;
    }
}

// Repository Interface (Port)
interface OrderRepository {
    findById(id: UUID): Promise;
    findByCustomer(customerId: UUID): Promise;
    save(order: Order): Promise;
    delete(id: UUID): Promise;
}

---

🚫 Level 4 Anti-Patterns

| Anti-Pattern | Symptom | Fix | |-------------|---------|-----| | Diagram Entire Codebase | 50+ classes in one diagram | Focus on 5-10 key classes that represent the component's value | | Outdated Diagrams | Code changed, diagram didn't | Generate from code (IDE plugins) or accept L4 as temporary | | Wrong Abstraction Level | Showing utility classes, DTOs | Focus on domain entities, aggregates, and key interfaces | | Missing Multiplicity | Associations without cardinality | Always specify 1:1, 1:N, N:M | | Wrong Relationship Type | Using inheritance for "has-a" | Composition for ownership, aggregation for reference |

---

✅ Level 4 Review Checklist

• [ ] Is this diagram necessary for understanding the component?
• [ ] Are relationships (inheritance, association, composition) correctly labeled?
• [ ] Is the diagram focused on only the most important parts (≤10 classes/tables)?
• [ ] Does it correctly reflect the actual codebase structure?
• [ ] Are cardinalities specified on all associations?
• [ ] Are keys (PK, FK) marked in ERDs?
• [ ] Would a new developer understand this component after reading the diagram?

---

📚 References

• C4 Model — Code Diagram — Simon Brown
• Mermaid Class Diagram
• Mermaid ER Diagram
• UML Class Diagram Reference

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kinhluan
• Source: kinhluan/skills
• License: MIT

Install and usage instructions live in the source repository linked above.