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"}]}
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)
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.
Simpler mental model than clean architecture for many teams: everything connects through ports (interfaces), and adapters implement them.
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.
Problem: Adding or modifying the "orders" feature requires touching files in four directories. Understanding the orders domain requires context-switching across folders.
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."
// Fat controller — don't do this
app.post('/orders', async (req, res) => {
const { userId, items } = req.body;
// Business logic #1: calculate totalconst total = items.reduce((sum, item) => sum + item.price * item.qty, 0);
// Business logic #2: apply discountconst user = await db.users.findById(userId);
const discount = user.memberSince < oneYearAgo ? 0.1 : 0;
const finalTotal = total * (1 - discount);
// Business logic #3: check inventoryfor (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 inconst 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.
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."
// orders/order.service.tsimport { UserService } from'../users/user.service'; // Order → User// users/user.service.tsimport { 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:
Merge: If Order and User are truly inseparable, put them in accounts/
Extract shared: Create order-summary/ that both can import from
Invert with interface: User module defines OrderSummaryPort interface; Orders implements it; User never imports from Orders
Event-driven: User reacts to OrderCreated event rather than calling OrderService directly
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:
// Bad: Use case is coupled to PostgresclassCreateOrderUseCase {
constructor(privatereadonlydb: PostgresConnection) {}
asyncexecute(cmd: CreateOrderCommand) {
awaitthis.db.query('INSERT INTO orders ...');
}
}
// Good: Use case depends on an interfaceinterfaceOrderRepository {
save(order: Order): Promise<void>;
findById(id: OrderId): Promise<Order | null>;
}
classCreateOrderUseCase {
constructor(privatereadonlyorderRepo: OrderRepository) {}
asyncexecute(cmd: CreateOrderCommand) {
const order = Order.create(cmd);
awaitthis.orderRepo.save(order); // No SQL, no Postgres, no coupling
}
}
// Production: Postgres implements the interfaceclassPostgresOrderRepositoryimplementsOrderRepository {
asyncsave(order: Order): Promise<void> { /* Postgres SQL */ }
asyncfindById(id: OrderId): Promise<Order | null> { /* Postgres SQL */ }
}
// Tests: in-memory implements the same interfaceclassInMemoryOrderRepositoryimplementsOrderRepository {
private orders = newMap<string, Order>();
asyncsave(order: Order) { this.orders.set(order.id, order); }
asyncfindById(id: OrderId) { returnthis.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:
// features/orders/index.ts — public APIexport { CreateOrderUseCase } from'./create-order.use-case';
export { OrderRepository } from'./order.repository.interface';
exporttype { Order, OrderStatus } from'./order.entity';
// NOT exported: internal helpers, SQL queries, implementation details// Other modules import from the public API onlyimport { CreateOrderUseCase } from'@/features/orders';
// NOT: import from '@/features/orders/create-order.use-case'
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
