Skip to main content
skill CX Codex

code-architecture — Claude Code skill: application architecture patterns and code organization

code-architecture is a Claude Code skill for organizing code within a single application. It covers clean and hexagonal architecture, feature-based folders, dependency inversion, and module boundaries.

MIT 169 installs ★ 274 updated 2026-10-30

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add curiositech/some_claude_skills --skill code-architecture -a claude-code
Open on GitHub

What code-architecture does

This skill covers decisions made at the module and application level. It deliberately stays away from service decomposition and database schema design — those belong to separate skills in the same repository: microservices-patterns and database-design-patterns.

A flowchart inside picks a pattern based on team size and domain complexity. Solo developers with simple CRUD can stay with layered MVC. A team of 3–8 people with rich business rules gets pointed toward clean architecture or vertical slices. Larger groups end up with feature-based organization. The skill spells out the dependency rule: code dependencies point inward only. Entities know nothing about use cases, controllers know nothing about database drivers.

For hexagonal architecture, ports and adapters get their own breakdown. Business logic calls interfaces; PostgreSQL, SendGrid, and Redis implement them from the outside. The skill says this model beats clean architecture when infrastructure swapping matters — in-memory for tests, Postgres for production. It also contrasts layer-based and feature-based folder layouts: changing orders in a layered tree means touching controllers, services, and repositories at once. Triggers include "fat controller", "circular dependency", and "IoC container". With Bash, Grep, and Glob available, it can inspect the actual project structure. Inside the skill collection, it pairs with refactoring-surgeon, which implements the patterns this skill prescribes.

What it helps with

  • pick an architecture pattern for team size and domain complexity
  • untangle fat controllers and circular dependencies
  • apply dependency inversion to tightly coupled code
  • reorganize folders by feature instead of by layer
  • define module boundaries and barrel exports

Example prompts for the agent

  • Help me choose an architecture pattern: 4 developers, complex domain, heavy unit testing.
  • Look at my src/ tree and show where the dependency rule breaks.
  • Show how to refactor this fat controller into hexagonal architecture with ports and adapters.

How to install code-architecture

1Skills CLI (Vercel)

npx skills add curiositech/some_claude_skills --skill code-architecture -a claude-code

2Manually: put the files in place

~/.claude/skills/code-architecture/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/code-architecture/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about code-architecture

How do I install code-architecture in Claude Code?

Run npx skills add curiositech/some_claude_skills --skill code-architecture -a claude-code. The skill lands at ~/.claude/skills/code-architecture/SKILL.md.

What does the code-architecture skill do?

It helps choose an architecture pattern, sort out folder structure, apply dependency inversion, and work through module boundaries inside a single application.

How is it different from microservices-patterns?

code-architecture works within one deployable unit. Splitting a monolith into services is covered by a separate skill, microservices-patterns; database schemas by database-design-patterns.

Source text

SKILL.md · MIT
---
name: code-architecture
description: Application architecture patterns and code organization — clean architecture, hexagonal architecture, feature-based structure, dependency inversion, module boundaries, SOLID principles at module
  scale. Activate on "clean architecture", "hexagonal architecture", "feature-based structure", "dependency inversion", "module boundaries", "architecture pattern", "folder structure", "fat controller",
  "circular dependency", "IoC container". NOT for microservice decomposition (use microservices-patterns) or database schema design (use database-design-patterns).
allowed-tools: Read,Write,Edit,Bash,Grep,Glob
metadata:
  category: Code Quality & Testing
  tags:
  - code
  - architecture
  - clean-architecture
  - hexagonal-architecture
  - feature-based-structure
  pairs-with:
  - skill: refactoring-surgeon
    reason: Refactoring implements the architectural patterns that code-architecture prescribes
  - skill: monorepo-management
    reason: Monorepo workspace boundaries enforce architectural module separation
  - skill: microservices-patterns
    reason: Service decomposition decisions depend on application architecture patterns
  - skill: typescript-advanced-patterns
    reason: TypeScript type system features enforce architectural boundaries at compile time
---

# Code Architecture

Architecture patterns and code organization that survive contact with reality. The goal is code you can still understand, test, and change 18 months after it was written. This covers the decisions made at the module and application level — not how to split services, not how to design schemas, but how to organize the code within a single deployable unit.

## When to Use

**Use for**:
- Choosing an architecture pattern for a new project (clean, hexagonal, feature-based, vertical slice)
- Diagnosing architectural problems in existing code (fat controllers, circular deps, tangled business logic)
- Applying dependency inversion to untangle tightly coupled code
- Deciding on folder structure and module organization
- Applying SOLID principles at the module scale (not just class scale)
- Setting up dependency injection containers
- Defining module boundaries and barrel exports
- Designing the test pyramid relative to architecture layers

**NOT for**:
- Splitting a monolith into microservices (use `microservices-patterns`)
- Database schema design, normalization, query optimization (use `database-design-patterns`)
- Framework-specific routing or middleware setup
- CI/CD pipeline architecture

---

## Core Decision: Which Architecture Pattern?

```mermaid
flowchart TD
    Start[New project or restructuring?] --> Team{Team size?}

    Team -->|Solo / 2 dev| Size{App complexity?}
    Team -->|3-8 dev| MedComplex{Domain complexity?}
    Team -->|8+ dev| Large[Feature-based / Vertical Slice]

    Size -->|Simple CRUD, low domain logic| Simple[Flat + MVC or Feature-Based]
    Size -->|Complex domain, long-lived| Hex[Hexagonal Architecture]

    MedComplex -->|Low: thin business layer| FeatureBased[Feature-Based Organization]
    MedComplex -->|High: rich business rules| Clean[Clean Architecture]
    MedComplex -->|Mixed: CRUD + some complex| Vertical[Vertical Slice Architecture]

    Simple --> SCheck{Will it grow?}
    SCheck -->|No, short-lived| MVC[Layer-based MVC is fine]
    SCheck -->|Yes| FeatureBased

    Large --> Testing{Testing rigor?}
    Testing -->|Low: mostly E2E| Vertical
    Testing -->|High: unit + integration| Clean

    Clean --> ClNote[Entities → Use Cases → Interface Adapters → Frameworks]
    Hex --> HexNote[Domain core ↔ Ports ↔ Adapters]
    FeatureBased --> FBNote[features/X contains all layers for X]
    Vertical --> VSNote[Each slice owns its full stack top to bottom]
```

---

## Clean Architecture Layers

The classic onion — each ring depends only inward, never outward.

```mermaid
graph TB
    subgraph Frameworks ["Frameworks & Drivers (outer)"]
        DB[(Database)]
        HTTP[HTTP Server]
        UI[UI / CLI]
        External[External APIs]
    end

    subgraph Adapters ["Interface Adapters"]
        Controllers[Controllers / Routes]
        Presenters[Presenters]
        Gateways[Repository Implementations]
        DTOs[DTOs / View Models]
    end

    subgraph UseCases ["Use Cases (Application Layer)"]
        UC1[CreateOrder]
        UC2[ProcessPayment]
        UC3[NotifyUser]
        Ports[Repository Interfaces]
    end

    subgraph Entities ["Entities (Domain)"]
        Order[Order]
        User[User]
        Payment[Payment]
        Rules[Business Rules]
    end

    HTTP --> Controllers
    Controllers --> UC1
    UC1 --> Ports
    Gateways --> Ports
    DB --> Gateways
    UC1 --> Order
```

**Dependency rule**: Source code dependencies point inward only. Entities know nothing about use cases. Use cases know nothing about controllers. Controllers know nothing about database drivers.

**What belongs where**:
| Layer | Contains | Examples |
|-------|----------|---------|
| Entities | Enterprise business rules | `Order`, `Payment`, domain events, value objects |
| Use Cases | Application-specific business logic | `CreateOrderUseCase`, `RefundPaymentUseCase` |
| Interface Adapters | Convert data between use cases and external forms | Controllers, Presenters, Repository implementations |
| Frameworks | External tools, databases, UI frameworks | Express, Postgres, React |

---

## Hexagonal Architecture (Ports and Adapters)

Simpler mental model than clean architecture for many teams: everything connects through ports (interfaces), and adapters implement them.

```mermaid
graph LR
    subgraph Domain ["Domain (Hexagon)"]
        Logic[Business Logic]
        DPorts[Driven Ports<br/>interfaces the domain calls]
    end

    subgraph Driving ["Driving Adapters<br/>(what drives the app)"]
        HTTP2[HTTP Controller]
        CLI2[CLI Command]
        Test[Test Harness]
    end

    subgraph Driven ["Driven Adapters<br/>(what the app drives)"]
        DB2[(PostgreSQL Adapter)]
        Email[SendGrid Adapter]
        Cache[Redis Adapter]
    end

    HTTP2 -->|calls| Logic
    CLI2 -->|calls| Logic
    Test -->|calls| Logic
    Logic -->|calls port| DPorts
    DPorts -.->|implemented by| DB2
    DPorts -.->|implemented by| Email
    DPorts -.->|implemented by| Cache
```

**When hexagonal beats clean**: When you need to swap infrastructure easily (test with in-memory, prod with Postgres), or when your business logic is rich enough to warrant isolation but doesn't need the full layer separation of clean architecture.

---

## Feature-Based vs Layer-Based Organization

### Layer-Based (Traditional MVC)

```
src/
  controllers/
    user.controller.ts
    order.controller.ts
    payment.controller.ts
  services/
    user.service.ts
    order.service.ts
    payment.service.ts
  repositories/
    user.repository.ts
    order.repository.ts
  models/
    user.model.ts
    order.model.ts
```

**Problem**: Adding or modifying the "orders" feature requires touching files in four directories. Understanding the orders domain requires context-switching across folders.

### Feature-Based (Recommended for Growing Apps)

```
src/
  features/
    orders/
      orders.controller.ts
      orders.service.ts
      orders.repository.ts
      orders.schema.ts
      orders.types.ts
      orders.test.ts
      index.ts           ← public API (barrel export)
    users/
      users.controller.ts
      users.service.ts
      ...
      index.ts
    payments/
      ...
  shared/
    database/
    logger/
    config/
```

**Benefits**: All order-related code is co-located. Deleting a feature is one folder deletion. Onboarding a developer to the orders domain is one directory.

**Rule**: Features import from `shared/` and from each other's public `index.ts` only. They never reach into each other's internals.

---

## Anti-Pattern: Business Logic in Controllers (Fat Controller)

**Novice**: "Controllers are where requests come in, so I'll put the logic there too. It's convenient."

```typescript
// Fat controller — don't do this
app.post('/orders', async (req, res) => {
  const { userId, items } = req.body;

  // Business logic #1: calculate total
  const total = items.reduce((sum, item) => sum + item.price * item.qty, 0);

  // Business logic #2: apply discount
  const user = await db.users.findById(userId);
  const discount = user.memberSince < oneYearAgo ? 0.1 : 0;
  const finalTotal = total * (1 - discount);

  // Business logic #3: check inventory
  for (const item of items) {
    const stock = await db.inventory.findById(item.productId);
    if (stock.quantity < item.qty) {
      return res.status(409).json({ error: 'Out of stock' });
    }
  }

  // Side effects mixed in
  const order = await db.orders.create({ userId, items, total: finalTotal });
  await emailService.send(user.email, 'order-confirmation', { order });
  await inventory.decrement(items);

  res.json(order);
});
```

**Expert**: Controllers are HTTP adapters. They translate HTTP → domain, call a use case or service, then translate domain → HTTP response. All business logic belongs in a use case or domain service that can be tested without an HTTP context.

```typescript
// Lean controller
app.post('/orders', async (req, res) => {
  try {
    const command = CreateOrderCommand.fromRequest(req.body);  // Validate + map
    const order = await createOrderUseCase.execute(command);   // All logic here
    res.status(201).json(OrderPresenter.toJSON(order));        // Map to response
  } catch (error) {
    errorHandler(res, error);
  }
});

// Use case: testable, framework-agnostic
class CreateOrderUseCase {
  constructor(
    private readonly orderRepo: OrderRepository,
    private readonly inventoryService: InventoryService,
    private readonly discountPolicy: DiscountPolicy,
    private readonly notifications: NotificationPort,
  ) {}

  async execute(command: CreateOrderCommand): Promise<Order> {
    const user = await this.orderRepo.findUser(command.userId);
    const discount = this.discountPolicy.calculate(user);
    await this.inventoryService.reserveItems(command.items);
    const order = Order.create(command.items, discount);
    await this.orderRepo.save(order);
    await this.notifications.orderCreated(order, user);
    return order;
  }
}
```

**Detection**: Controllers with more than ~20 lines of logic, controllers that import database models directly, controllers with nested if-else business conditions.

---

## Anti-Pattern: Architecture Astronaut (Abstraction for Its Own Sake)

**Novice**: "I'll add a Repository interface, a Repository implementation, a Service, a ServiceInterface, a Factory to create the Service, an EventBus, and a CQRS command handler. This is enterprise-grade."

**Expert**: Every abstraction has a cost: more files, more indirection, harder onboarding, more to maintain. Abstractions are investments that pay off when they enable testing, swappability, or code reuse. If you're adding a `UserServiceInterface` with one implementation that will never change, you've paid the abstraction cost without collecting the benefit.

Ask: "What does this abstraction enable that I couldn't do otherwise?"
- **Repository interface** → swap real DB for in-memory in tests. Pays off immediately.
- **Service interface** → if there's only ever one service, this is ceremony.
- **Factory pattern** → pays off when object creation is complex or has multiple strategies.
- **Event bus** → pays off when many components need to react to domain events without knowing about each other.

**Detection**: Files named `*Interface.ts`, `*Abstract.ts`, `*Factory.ts` that have only one implementer and one caller, and that implementer never changes.

**Timeline**: Enterprise Java (2005-2015) made abstract-everything the default. Spring Framework encouraged this. The post-2015 Node.js and Go communities pushed back with "boring technology" principles. In 2026, the right level of abstraction is contextual — neither zero nor maximum.

---

## Anti-Pattern: Circular Dependencies

**Novice**: "The Order module needs to know about Users, and the User module needs to check their orders. So I'll import each from the other."

```typescript
// orders/order.service.ts
import { UserService } from '../users/user.service';   // Order → User

// users/user.service.ts
import { OrderService } from '../orders/order.service'; // User → Order

// Node.js will silently give you `undefined` at runtime
// Jest will give you cryptic "Cannot access before initialization" errors
```

**Expert**: Circular dependencies indicate a domain modeling problem. Two modules that genuinely need each other should either be merged into one module, or share a third module that both depend on, or communicate via events/interfaces.

Resolution strategies:
1. **Merge**: If Order and User are truly inseparable, put them in `accounts/`
2. **Extract shared**: Create `order-summary/` that both can import from
3. **Invert with interface**: User module defines `OrderSummaryPort` interface; Orders implements it; User never imports from Orders
4. **Event-driven**: User reacts to `OrderCreated` event rather than calling OrderService directly

```bash
# Detect circular deps
npx madge --circular src/
npx dpdm --circular src/index.ts

# ESLint rule (add to .eslintrc)
# "import/no-cycle": "error"
```

**Detection**: Runtime errors where a module value is `undefined` at startup, ESLint `import/no-cycle` violations, madge circular output.

---

## Dependency Inversion in Practice

The D in SOLID: depend on abstractions, not concretions. Applied at module scale:

```typescript
// Bad: Use case is coupled to Postgres
class CreateOrderUseCase {
  constructor(private readonly db: PostgresConnection) {}

  async execute(cmd: CreateOrderCommand) {
    await this.db.query('INSERT INTO orders ...');
  }
}

// Good: Use case depends on an interface
interface OrderRepository {
  save(order: Order): Promise<void>;
  findById(id: OrderId): Promise<Order | null>;
}

class CreateOrderUseCase {
  constructor(private readonly orderRepo: OrderRepository) {}

  async execute(cmd: CreateOrderCommand) {
    const order = Order.create(cmd);
    await this.orderRepo.save(order);  // No SQL, no Postgres, no coupling
  }
}

// Production: Postgres implements the interface
class PostgresOrderRepository implements OrderRepository {
  async save(order: Order): Promise<void> { /* Postgres SQL */ }
  async findById(id: OrderId): Promise<Order | null> { /* Postgres SQL */ }
}

// Tests: in-memory implements the same interface
class InMemoryOrderRepository implements OrderRepository {
  private orders = new Map<string, Order>();
  async save(order: Order) { this.orders.set(order.id, order); }
  async findById(id: OrderId) { return this.orders.get(id) ?? null; }
}
```

**When DI containers are worth it**: When you have many dependencies that need wiring, and wiring manually becomes error-prone or repetitive. NestJS, InversifyJS (TypeScript), Python's dependency-injector, Spring (Java).

**When DI containers are overkill**: Simple scripts, small services with few dependencies, serverless functions, Go projects (constructor injection is idiomatic and sufficient).

---

## Module Boundaries and Barrel Exports

Each feature/module should expose a public API via `index.ts`:

```typescript
// features/orders/index.ts — public API
export { CreateOrderUseCase } from './create-order.use-case';
export { OrderRepository } from './order.repository.interface';
export type { Order, OrderStatus } from './order.entity';
// NOT exported: internal helpers, SQL queries, implementation details

// Other modules import from the public API only
import { CreateOrderUseCase } from '@/features/orders';
// NOT: import from '@/features/orders/create-order.use-case'
```

**Enforce with ESLint**:
```json
// .eslintrc
{
  "rules": {
    "import/no-internal-modules": ["error", {
      "allow": ["**/*.test.ts", "**/index.ts"]
    }]
  }
}
```

---

## Testing Architecture (Test Pyramid Placement)

Each architecture layer has a natural test type:

| Layer | Test Type | Speed | Coverage |
|-------|----------|-------|---------|
| Entities / Domain | Unit tests | Instant | 90%+ |
| Use Cases / Application | Unit tests with mocks | Fast | 80%+ |
| Interface Adapters | Integration tests | Medium | 70%+ |
| Frameworks / External | E2E / contract tests | Slow | Key paths |

**Rule**: Business logic tests should not require starting a server, connecting to a database, or making network calls. If your use case tests require a real database, your architecture has leaked infrastructure concerns into the domain.

---

## References

- `references/architecture-patterns.md` — Consult for detailed patterns: clean architecture layers, hexagonal ports and adapters, vertical slice, feature-based organization with worked examples
- `references/dependency-inversion.md` — Consult for IoC containers in TypeScript and Python, constructor injection patterns, when DI is overkill, common DI anti-patterns

© curiositech · MIT · curiositech/some_claude_skills

Similar skills

All skills for Code review and refactoring →
clean-architecture wondelai clean-architecture — a skill that keeps business rules independent of framework and database by enforcing one rule: source code dependencies point inward. CX Codex +1 8,000installs 707-technologies-hexagonal-architecture Juan Antonio Breña Moral 707-technologies-hexagonal-architecture is a Claude Code skill that reviews and improves Hexagonal architecture boundaries in Java projects without coupling to Spring Boot, Quarkus, or Micronaut. CX Codex +1 174installs architecture-patterns OrchestKit architecture-patterns enforces clean architecture, backend layer boundaries, and directory limits. Triggers when designing module boundaries or running refactoring tasks. CX Codex +1 236installs software-architecture Bbeierle12 software-architecture — a skill that walks the agent through SOLID and Clean Architecture, with a bad and a good version of the same TypeScript code for each principle. CX Codex +1 150installs design-patterns-implementation aj-geddes design-patterns-implementation — a skill for Claude Code and Codex that picks and applies design patterns to architectural problems. It kicks in during refactoring, architecture review, and when building extensible systems. CX Codex +1 601installs architecture-review decebals architecture-review — a skill that reviews a Java project at the macro level: package layout, module boundaries, dependency direction and layering. Useful once a codebase grows past the point where you can hold its structure in your head. CX Codex +1 394installs

From the same set180

The whole set →
cost-verification-auditor cost-verification-auditor is a Claude Code skill that compares estimated token costs with actual API usage. It triggers when investigating a discrepancy between a forecast and an API bill. CX Codex +1 175installs values-behavioral-interview The values-behavioral-interview skill for Claude Code helps prepare structured stories for values and behavioral interviews, including failures and follow-up questions. CX Codex +1 174installs interview-loop-strategist interview-loop-strategist builds an end-to-end interview preparation roadmap for senior ML and AI engineering roles at Anthropic and peer teams. It structures timelines, mock sessions, and project narratives. CX Codex +1 173installs interview-simulator interview-simulator — a skill for designing mock interview sessions with voice, whiteboard review, proctoring, and adaptive difficulty. Use it to plan the platform and session flow. CX Codex +1 169installs design-system-documenter design-system-documenter converts raw token files into developer documentation featuring reference tables, implementation code, and WCAG contrast checks. CX Codex +1 165installs win31-audio-design win31-audio-design — a skill that builds Windows 3.1-style UI audio: 8-bit sounds, Web Audio API code, and haptic coordination for web and mobile apps. CX Codex +1 165installs human-centered-design-fundamentals The human-centered-design-fundamentals skill helps assess how people understand actions and system state in an interface. Use it to investigate user errors and make products easier to understand. CX Codex +1 161installs llm-router llm-router picks a model and provider for each task by complexity, budget, and quality needs. Cheap work goes to Haiku, hard problems to Sonnet or Opus. CX Codex +1 160installs

Project sponsors

Companies that keep this analytics open