Skip to content

Destynova2/cli-code-skills / cli-forge-arch

cli-forge-arch

Verified

Router for architecture design. Detects whether the user needs an HLD or LLD and delegates to the appropriate skill. Use when the user says 'design doc', 'architecture', or is ambiguous about HLD vs LLD. For explicit HLD requests, use cli-forge-hld directly. For explicit LLD requests, use cli-forge-lld directly.

FileKindSize
SKILL.mdskill md2.4 KB
references/estimation-cheatsheet.mdmarkdown7.4 KB
references/hld-template.mdmarkdown8.1 KB
references/lld-template.mdmarkdown11.2 KB

references/lld-template.md

View on GitHub
# LLD Template Reference

## Contents

- Document Structure
- Section Guidelines

---

Use this template when producing a Low-Level Design document. The LLD translates the HLD's "what" into the "how" β€” detailed enough that a developer can implement without ambiguity.

---

## Document Structure

```
# [Component/Service Name] β€” Low-Level Design

## 1. Overview and Scope
## 2. Component Architecture (C4 Level 3)
## 3. Class/Module Design
## 4. API Specification
## 5. Database Schema
## 6. Sequence Diagrams (Critical Flows)
## 7. State Machines
## 8. Error Handling and Resilience
## 9. Caching Strategy
## 10. Configuration and Feature Flags
## 11. Testing Strategy
## 12. Migration Plan
```

---

## Section Guidelines

### 1. Overview and Scope

- Reference the parent HLD document
- Identify which HLD container(s) this LLD covers
- List the specific functional requirements this component implements

### 2. Component Architecture (C4 Level 3)

Break the container into its internal components:

```mermaid
graph TB
    subgraph "Service A"
        Controller[🎯 Controller Layer<br/>HTTP handlers, validation]
        Service[βš™οΈ Service Layer<br/>Business logic]
        Repository[πŸ—„οΈ Repository Layer<br/>Data access]
        Domain[πŸ“ Domain Layer<br/>Entities, value objects]
        Client[πŸ“‘ External Clients<br/>API clients, SDK wrappers]
    end
    
    Controller --> Service
    Service --> Domain
    Service --> Repository
    Service --> Client
    Repository --> DB[(Database)]
    Client --> ExtAPI[External API]
```

For each component:

| Component | Responsibility | Dependencies | Interface |
|-----------|---------------|-------------|-----------|
| Controller | HTTP routing, input validation, response mapping | Service | REST endpoints |
| Service | Business rules, orchestration, transactions | Repository, Client, Domain | Internal methods |
| Repository | CRUD, queries, data mapping | Database driver | Data access interface |
| Domain | Entities, value objects, domain events | None (pure) | Types and methods |

### 3. Class/Module Design

Use Mermaid class diagrams. Follow SOLID and relevant design patterns.

```mermaid
classDiagram
    class OrderService {
        -orderRepo: OrderRepository
        -paymentClient: PaymentClient
        -eventBus: EventBus
        +createOrder(req: CreateOrderReq): Order
        +cancelOrder(id: OrderId): void
        +getOrder(id: OrderId): Order
    }
    
    class Order {
        +id: OrderId
        +userId: UserId
        +items: List~LineItem~
        +status: OrderStatus
        +createdAt: DateTime
        +totalAmount(): Money
        +cancel(): void
    }
    
    class OrderStatus {
        <<enumeration>>
        PENDING
        CONFIRMED
        SHIPPED
        DELIVERED
        CANCELLED
    }
    
    class OrderRepository {
        <<interface>>
        +save(order: Order): void
        +findById(id: OrderId): Option~Order~
        +findByUser(userId: UserId, page: Page): List~Order~
    }
    
    OrderService --> OrderRepository
    OrderService --> Order
    Order --> OrderStatus
    Order --> LineItem
```

**Design patterns to consider and document when used:**
- **Repository**: data access abstraction
- **Strategy**: swappable algorithms (e.g., pricing, notification channels)
- **Factory**: complex object creation
- **Observer/Event**: decoupled notifications
- **Circuit Breaker**: resilience to external failures
- **Retry with backoff**: transient error handling
- **Builder**: complex configuration objects

### 4. API Specification

For each endpoint, provide full detail:

```
### POST /api/v1/orders

**Purpose:** Create a new order

**Authentication:** Bearer JWT (role: user)

**Rate limit:** 10 req/min per user

**Request:**
```json
{
  "items": [
    {
      "product_id": "string (UUID)",
      "quantity": "integer (min: 1, max: 100)"
    }
  ],
  "shipping_address_id": "string (UUID)",
  "payment_method_id": "string (UUID)"
}
```

**Response 201:**
```json
{
  "id": "string (UUID)",
  "status": "PENDING",
  "items": [...],
  "total_amount": { "value": 4999, "currency": "EUR" },
  "created_at": "2025-01-15T10:30:00Z"
}
```

**Error responses:**

| Code | Condition | Body |
|------|-----------|------|
| 400 | Invalid input | `{"error": "INVALID_INPUT", "details": [...]}` |
| 401 | Missing/invalid token | `{"error": "UNAUTHORIZED"}` |
| 404 | Product/address not found | `{"error": "NOT_FOUND", "resource": "product"}` |
| 409 | Insufficient stock | `{"error": "CONFLICT", "reason": "INSUFFICIENT_STOCK"}` |
| 429 | Rate limited | `{"error": "RATE_LIMITED", "retry_after": 30}` |
| 500 | Internal error | `{"error": "INTERNAL_ERROR", "trace_id": "..."}` |
```

**Idempotency:** Support `Idempotency-Key` header for safe retries.

**Pagination pattern** (for list endpoints):
```
GET /api/v1/orders?cursor=abc123&limit=20

Response includes:
{
  "data": [...],
  "pagination": {
    "next_cursor": "def456",
    "has_more": true
  }
}
```

### 5. Database Schema

```mermaid
erDiagram
    orders {
        uuid id PK
        uuid user_id FK
        varchar status
        bigint total_amount_cents
        varchar currency
        uuid shipping_address_id FK
        timestamp created_at
        timestamp updated_at
    }
    
    line_items {
        uuid id PK
        uuid order_id FK
        uuid product_id FK
        int quantity
        bigint unit_price_cents
    }
    
    orders ||--|{ line_items : contains
```

For each table, document:

| Column | Type | Constraints | Index | Notes |
|--------|------|------------|-------|-------|
| id | UUID | PK, NOT NULL | btree (PK) | Generated by app |
| user_id | UUID | FK β†’ users.id, NOT NULL | btree | Frequent query filter |
| status | VARCHAR(20) | NOT NULL, CHECK IN (...) | btree | State machine values |
| created_at | TIMESTAMPTZ | NOT NULL, DEFAULT now() | btree | For cursor pagination |

**Index strategy:**
```sql
-- Primary lookup
CREATE INDEX idx_orders_user_status ON orders(user_id, status);

-- Pagination
CREATE INDEX idx_orders_created ON orders(created_at DESC);

-- Admin queries
CREATE INDEX idx_orders_status ON orders(status) WHERE status IN ('PENDING', 'CONFIRMED');
```

**Migration strategy:**
- All schema changes via versioned migrations (Flyway, golang-migrate, etc.)
- Backward-compatible changes only (additive columns, new tables)
- Breaking changes require multi-phase migration (add new β†’ backfill β†’ switch β†’ drop old)

### 6. Sequence Diagrams (Critical Flows)

For each critical user flow, provide a sequence diagram:

```mermaid
sequenceDiagram
    actor User
    participant API as API Gateway
    participant Auth as Auth Service
    participant Svc as Order Service
    participant DB as Database
    participant MQ as Message Queue
    participant Pay as Payment Service
    
    User->>API: POST /orders
    API->>Auth: Validate JWT
    Auth-->>API: OK (user_id)
    API->>Svc: createOrder(req, user_id)
    
    Svc->>DB: BEGIN TX
    Svc->>DB: Check stock availability
    DB-->>Svc: Stock OK
    Svc->>DB: INSERT order
    Svc->>DB: UPDATE stock (reserve)
    Svc->>DB: COMMIT TX
    
    Svc->>MQ: Publish OrderCreated event
    Svc-->>API: 201 Created
    API-->>User: 201 + order JSON
    
    MQ->>Pay: OrderCreated
    Pay->>Pay: Process payment
    Pay->>MQ: Publish PaymentCompleted
    MQ->>Svc: PaymentCompleted
    Svc->>DB: UPDATE order status β†’ CONFIRMED
```

Provide sequence diagrams for:
- Happy path (main flow)
- Key error paths (payment failure, timeout, conflict)
- Async flows (background jobs, event processing)

### 7. State Machines

For entities with lifecycle states:

```mermaid
stateDiagram-v2
    [*] --> PENDING: Order created
    PENDING --> CONFIRMED: Payment successful
    PENDING --> CANCELLED: Payment failed / User cancels
    CONFIRMED --> SHIPPED: Shipped by warehouse
    SHIPPED --> DELIVERED: Delivery confirmed
    CONFIRMED --> CANCELLED: Admin cancels
    CANCELLED --> [*]
    DELIVERED --> [*]
```

Document transitions:

| From | To | Trigger | Side Effects |
|------|----|---------|-------------|
| PENDING | CONFIRMED | PaymentCompleted event | Send confirmation email, notify warehouse |
| PENDING | CANCELLED | PaymentFailed event or user action | Release stock, refund if partial |
| CONFIRMED | SHIPPED | Warehouse scan | Send tracking email |

### 8. Error Handling and Resilience

**Error classification:**

| Category | Examples | Strategy |
|----------|----------|----------|
| Transient | Network timeout, 503 | Retry with exponential backoff (base: 100ms, max: 10s, jitter: Β±50%) |
| Client error | 400, 404, 422 | Return error immediately, no retry |
| Dependency down | External API unavailable | Circuit breaker (threshold: 5 failures in 30s, recovery: 60s) |
| Data inconsistency | Partial write | Saga pattern with compensating transactions |
| Rate limited | 429 | Respect Retry-After header, queue and replay |

**Circuit breaker configuration:**
```
failure_threshold: 5
success_threshold: 3
timeout: 30s
half_open_max_calls: 3
```

**Retry policy:**
```
max_retries: 3
initial_interval: 100ms
multiplier: 2
max_interval: 10s
jitter: 0.5
retryable_codes: [408, 429, 500, 502, 503, 504]
```

**Dead letter queue (DLQ):** Messages that fail N times go to DLQ for manual inspection. Alert on DLQ depth > 0.

### 9. Caching Strategy

| Data | Cache | TTL | Invalidation | Justification |
|------|-------|-----|-------------|---------------|
| User profile | Redis | 15min | On update (write-through) | High read:write ratio |
| Product catalog | Redis | 5min | TTL expiry | Eventual consistency OK |
| Session | Redis | 30min (sliding) | On logout | Must be fast |
| Static assets | CDN | 1 year | Cache-bust via hash in URL | Immutable content |

**Cache patterns used:**
- **Cache-aside** (default): app checks cache, on miss reads DB and populates cache
- **Write-through**: for data that must always be fresh in cache
- **Write-behind**: for high-write scenarios where eventual consistency is OK

### 10. Configuration and Feature Flags

```yaml
# Example config structure
service:
  port: 8080
  read_timeout: 30s
  write_timeout: 30s

database:
  host: ${DB_HOST}
  port: 5432
  max_connections: 20
  idle_timeout: 5m

cache:
  host: ${REDIS_HOST}
  pool_size: 10

feature_flags:
  new_pricing_engine: false
  async_notifications: true
```

Configuration hierarchy: env vars > config file > defaults. Secrets always via vault/env, never in config files.

### 11. Testing Strategy

| Level | Scope | Tools | Coverage Target |
|-------|-------|-------|----------------|
| Unit | Business logic, domain | Go test / pytest / cargo test | > 80% |
| Integration | DB queries, cache, external clients | Testcontainers | Critical paths |
| Contract | API compatibility | Pact / Schemathesis | All public APIs |
| E2E | Full user flows | Playwright / k6 | Happy + key error paths |
| Load | Performance under stress | k6, Locust | Validate capacity estimates |

### 12. Migration Plan

If this LLD modifies an existing system:

| Phase | Action | Rollback | Duration |
|-------|--------|----------|----------|
| 1 | Deploy new schema (additive) | Drop new columns | 1 sprint |
| 2 | Deploy dual-write code | Revert to old code | 1 sprint |
| 3 | Backfill historical data | Re-run from backup | 1-2 days |
| 4 | Switch reads to new schema | Revert read path | 1 sprint |
| 5 | Drop old columns/tables | Restore from backup | After validation |
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 321kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall