architect-pro

• Level: Senior / Lead Engineer / Software Architect
• Prerequisites:

- Deep understanding of TypeScript 5.5+ (Generics, Discriminated Unions, Template Literal Types).

- Familiarity with Next.js App Router and Server Components.

- Basic knowledge of SQL (PostgreSQL) and NoSQL (Redis/MongoDB) databases.

- Experience with automated testing (Jest, Vitest, Playwright).

- Interest in Domain-Driven Design (DDD).

---

1. [Core Philosophy](#core-philosophy)
2. [Why Clean Architecture in 2026?](#why-clean-architecture-in-2026)
3. [Architecture for AI Agents](#architecture-for-ai-agents)
4. [Quick Start: The 2026 Stack](#quick-start-the-2026-stack)
5. [Modern Data Flow: React 19 + Next.js 16](#modern-data-flow-react-19--next-js-16)
6. [Standard Pattern: Clean Architecture + Server Actions](#standard-pattern-clean-architecture--server-actions)
7. [Tactical DDD: Entities, Value Objects, and Aggregates](#tactical-ddd-entities-value-objects-and-aggregates)
8. [Domain Services vs Application Services](#domain-services-vs-application-services)
9. [Advanced Pattern: Event-Driven DDD](#advanced-pattern-event-driven-ddd)
10. [Event Storming & Domain Modeling](#event-storming--domain-modeling)
11. [Architecture Decision Records (ADR)](#architecture-decision-records-adr)
12. [Context Mapping & Strategic DDD](#context-mapping--strategic-ddd)
13. [Testing Strategy for Architects](#testing-strategy-for-architects)
14. [Architectural Enforcement & Guardrails](#architectural-enforcement--guardrails)
15. [Performance & Scalability at the Architectural Level](#performance--scalability-at-the-architectural-level)
16. [Glossary of Architectural Terms](#glossary-of-architectural-terms)
17. [The Do Not List (Anti-Patterns)](#the-do-not-list-anti-patterns)
18. [Deep-Dive References](#deep-dive-references)
19. [Repository Analysis with Repomix](#repository-analysis-with-repomix)

---

In 2026, software is increasingly built and refactored by AI Coding Agents. For an agent to be effective, the codebase must have predictable boundaries and explicit contracts.

• Decoupling: Business logic (Domain) must not depend on the database, UI, or frameworks.
• Testability: You should be able to test your core logic without spinning up a database or mocking complex framework internals.
• Independence: The system should be agnostic of its delivery mechanisms (Web, CLI, Mobile, AI Agents).
• Predictability: Files and folders should follow a strict convention so that both humans and AI can locate logic instantly.

---

The "Move Fast and Break Things" era has evolved into the "Move Fast with AI and Maintain Sanity" era. Without a solid architecture:

1. AI Agents Hallucinate: When business logic is mixed with Prisma queries and React hooks, AI often loses context and introduces subtle bugs.
2. Framework Churn: Next.js and React versions move fast. A clean domain layer protects you from the next breaking change in the app router or server actions.
3. Complexity Debt: What starts as a simple "CRUD" app often grows into a complex domain. Clean Architecture allows for "Gradual Complexity" where you can add layers only when needed.

---

In 2026, we design for two audiences: Humans and Agents.

• Deterministic File Paths: Using a strict Clean Architecture folder structure helps AI find the "Source of Truth" (Domain) instantly.
• Strong Typing (TS 5.5+): Explicit return types in Use Cases act as "API Documentation" for AI agents.
• Small Context Windows: Decoupled layers allow AI to work on a single file (like a Use Case) without needing to understand the entire database schema.
• Repomix Context Packing: We use tools to pack high-density context for AI agents, and a clean architecture makes this packing 10x more efficient.

---

The most common production stack in 2026 uses Next.js 16.2 with Server Functions, TypeScript 5.x, and Bun/pnpm monorepos.

Recommended Folder Structure

```bash

src/

├── domain/ # Core Logic (The "Truth")

│ ├── entities/ # Identifiable objects with identity and lifecycle

│ ├── value-objects/# Data wrappers with validation (Email, Money)

│ ├── services/ # Pure logic involving multiple entities

│ ├── events/ # Domain Events (OrderPlaced, UserDeactivated)

│ └── exceptions/ # Custom domain exceptions

├── application/ # Orchestration (The "User's Intent")

│ ├── use-cases/ # Specific business actions (Commands)

│ ├── ports/ # Interfaces (contracts for Infrastructure)

│ ├── dtos/ # Data Transfer Objects

│ └── queries/ # Read-only operations (if using CQRS)

├── infrastructure/ # Tools (The "Implementation")

│ ├── adapters/ # Implementations of Ports (Prisma, Stripe, AWS)

│ ├── persistence/ # DB Schemas, Migrations, Seeders

│ └── external/ # Third-party API clients

├── presentation/ # UI (The "View")

│ ├── components/ # React 19 Server/Client components

│ ├── actions/ # Next.js Server Actions (Primary Adapters)

│ └── pages/ # Route Handlers and Page definitions

└── shared/ # Cross-cutting concerns (Constants, Utils)

```

---

The interaction model has changed. We no longer just "fetch from API". We "Invoke a Service".

1. View (React 19)

Uses the new useActionState and useOptimistic for a seamless UX.

```typescript

// presentation/components/ProjectForm.tsx

'use client'

import { useActionState } from 'react';

import { createProjectAction } from '../actions/project-actions';

export function ProjectForm() {

const [state, formAction, isPending] = useActionState(createProjectAction, null);

return (

);

}

```

2. Action (Next.js 16.2)

Acts as the Primary Adapter. It handles the transition from HTTP (FormData) to Application logic.

```typescript

// presentation/actions/project-actions.ts

'use server'

import { CreateProjectUseCase } from '@/application/use-cases/CreateProject';

import { PrismaProjectRepository } from '@/infrastructure/adapters/PrismaProjectRepository';

export async function createProjectAction(prevState: any, formData: FormData) {

const name = formData.get('projectName') as string;

// Dependency Injection: In 2026, we prefer explicit composition over complex DI containers

const repo = new PrismaProjectRepository();

const useCase = new CreateProjectUseCase(repo);

try {

const project = await useCase.execute({ name });

return { success: true, data: project };

} catch (e) {

// Audit log or Error tracking integration

console.error("[Action Error]", e);

return { success: false, error: e.message };

}

}

```

---

1. The Domain Entity

Entities represent business concepts with identity.

```typescript

// src/domain/entities/User.ts

import { Email } from '../value-objects/Email';

export class User {

constructor(

public readonly id: string,

public readonly email: Email,

private _isActive: boolean = true

) {}

public deactivate() {

this._isActive = false;

}

get isActive() { return this._isActive; }

}

```

2. The Use Case (Application Layer)

Use Cases orchestrate the domain objects to perform a specific task.

```typescript

// src/application/use-cases/DeactivateUser.ts

import { IUserRepository } from '../ports/IUserRepository';

export class DeactivateUserUseCase {

constructor(private userRepo: IUserRepository) {}

async execute(userId: string): Promise {

// 1. Fetch from repository (Port)

const user = await this.userRepo.findById(userId);

if (!user) throw new Error("User not found");

// 2. Perform domain logic (Entity)

user.deactivate();

// 3. Persist changes (Port)

await this.userRepo.save(user);

}

}

```

3. The Repository Implementation (Infrastructure)

The "Adapter" that talks to the database.

```typescript

// src/infrastructure/adapters/PrismaUserRepository.ts

import { IUserRepository } from '@/application/ports/IUserRepository';

import { User } from '@/domain/entities/User';

import { Email } from '@/domain/value-objects/Email';

import { prisma } from '../prisma';

export class PrismaUserRepository implements IUserRepository {

async findById(id: string): Promise {

const data = await prisma.user.findUnique({ where: { id } });

if (!data) return null;

return new User(

data.id,

Email.create(data.email),

data.isActive

);

}

async save(user: User): Promise {

await prisma.user.upsert({

where: { id: user.id },

update: { isActive: user.isActive },

create: {

id: user.id,

email: user.email.value,

isActive: user.isActive

}

});

}

}

```

---

Value Objects (The Power of Types)

Don't use string for everything. Use Value Objects for validation and business logic.

```typescript

// domain/value-objects/Money.ts

export class Money {

private constructor(public readonly amount: number, public readonly currency: string) {}

static create(amount: number, currency: string = 'USD'): Money {

if (amount < 0) throw new Error("Amount cannot be negative");

return new Money(amount, currency);

}

add(other: Money): Money {

if (this.currency !== other.currency) throw new Error("Currency mismatch");

return new Money(this.amount + other.amount, this.currency);

}

}

```

Aggregates (The Consistency Boundary)

An Aggregate ensures that business rules are always met across multiple related objects.

```typescript

// domain/entities/Order.ts

export class Order {

private items: OrderItem[] = [];

addItem(product: Product, quantity: number) {

const totalItems = this.items.reduce((sum, item) => sum + item.quantity, 0);

if (totalItems + quantity > 50) {

throw new Error("An order cannot have more than 50 items");

}

this.items.push(new OrderItem(product.id, quantity));

}

}

```

---

One of the most common points of confusion in DDD.

• Domain Service: Contains business logic that belongs to the domain but doesn't fit in a single entity (e.g., TransferService between two bank accounts). It works with entities and value objects.
• Application Service (Use Case): Contains NO business logic. It only orchestrates. It calls repositories, triggers domain services, and sends emails.

---

Capture intent and decouple side-effects.

Domain Service Example

```typescript

// domain/services/TransferService.ts

export class TransferService {

async execute(from: Account, to: Account, amount: Money) {

from.withdraw(amount);

to.deposit(amount);

// Domain Events are captured here

return new FundsTransferredEvent(from.id, to.id, amount);

}

}

```

---

In 2026, we don't start with "Tables". We start with "Events".

1. Domain Events: What happens in the business? (e.g., OrderPlaced, InventoryReduced).
2. Commands: What triggers these events? (e.g., PlaceOrder).
3. Aggregates: What objects are involved in making sure the rules are followed?
4. Read Models: How do we want to display this information to the user?

---

In 2026, we record why we made a choice, not just what we chose.

```markdown

# ADR 005: Use Clean Architecture for AI Core

Accepted

We need a way for AI agents to refactor code safely without breaking business rules. The previous "Spaghetti Monolith" resulted in AI hallucinating database queries in React components.

We will use Clean Architecture with strict separation between Domain and Infrastructure.

• Pros: Predictable file structure, high testability, zero framework leakage in domain.
• Cons: More boilerplate for simple CRUD operations, higher learning curve for junior devs.

```

---

How different parts of the system talk to each other.

• Customer/Supplier: One team depends on another.
• Shared Kernel: Two teams share a common model (rarely recommended).
• Anticorruption Layer (ACL): A layer that translates between a legacy system and your clean new system.
• Separate Ways: No relationship between contexts.

---

In a Clean Architecture, you have different "Testing Grooves":

1. Domain Unit Tests: Test entities and value objects. ZERO mocks needed. 100% code coverage expected here.
2. Use Case Tests: Test orchestration. Use In-Memory Adapters (Mocks/Fakes) for the database.
3. Integration Tests: Test the real adapters (e.g., Prisma repository against a real Test Container).
4. E2E Tests: Test the full Next.js flow using Playwright.

Example: Use Case Test (No DB)

```typescript

// tests/use-cases/DeactivateUser.test.ts

import { DeactivateUserUseCase } from '@/application/use-cases/DeactivateUser';

import { InMemoryUserRepository } from '../mocks/InMemoryUserRepository';

test('should deactivate user', async () => {

const repo = new InMemoryUserRepository();

await repo.save({ id: '1', email: 'test@test.com', isActive: true });

const useCase = new DeactivateUserUseCase(repo);

await useCase.execute('1');

const user = await repo.findById('1');

expect(user.isActive).toBe(false);

});

```

---

Use tools to ensure the "Dependency Rule" is never broken.

`dependency-cruiser` config (2026 best practice)

```json

{

"forbidden": [

{

"name": "domain-not-import-infra",

"from": { "path": "src/domain" },

"to": { "path": "src/infrastructure" }

},

{

"name": "usecase-not-import-infra",

"from": { "path": "src/application" },

"to": { "path": "src/infrastructure" }

},

{

"name": "presentation-not-import-infra",

"from": { "path": "src/presentation" },

"to": { "path": "src/infrastructure" }

}

]

}

```

---

• Read-Write Segregation (CQRS): Use a fast NoSQL database for reads and a robust SQL database for writes.
• Caching as a First-Class Citizen: Don't put cache logic in your Use Case. Use a Caching Adapter or the Next.js use cache directive in the presentation layer.
• Job Queues: Offload heavy work (Email, AI Processing) to background jobs via Domain Events.

---

• Bounded Context: A specific boundary (usually a module or service) where a domain model is consistent.
• Port: An interface defined by the application layer that infrastructure must implement.
• Adapter: An implementation of a port (e.g., a SQL database implementation of an IUserRepository).
• Inversion of Control (IoC): The principle where the domain defines its needs (Ports), and the high-level layers provide the implementations (Adapters).
• Aggregate Root: The main entity in an aggregate that controls all access and enforces business rules.
• Ubiquitous Language: A common language used by all team members to describe the domain.

---

1. **Framework Leakage**

BAD: Using @prisma/client types as return types in your Domain or Application layers.

GOOD: Map database rows to Domain Entities in the Infrastructure layer.

2. **Anemic Domain Model**

BAD: Putting all your logic in UserService and having User as just a type.

GOOD: Move business rules (e.g., user.canJoinProject()) into the User class.

3. **The "Shared" Dumpster**

BAD: Putting everything in shared/ because you are too lazy to decide where it belongs.

GOOD: Keep shared/ minimal. If it's business-related, it's domain/. If it's tool-related, it's infrastructure/.

4. **Premature Microservices**

BAD: Splitting into 10 repos before you understand the domain boundaries.

GOOD: Build a Modular Monolith using Clean Architecture first. Boundaries are easy to cut later if they are clean.

5. **Lazy Naming**

BAD: data, info, manager, process.

GOOD: PaymentRecord, UserAuthenticationDetails, OrderOrchestrator.

---

Explore our specialized documentation for deeper technical insights:

• [Clean Architecture Guide](./references/clean-architecture.md)
• [Hexagonal Architecture (Ports & Adapters)](./references/hexagonal-architecture.md)
• [DDD Patterns & Tactical Design](./references/ddd-patterns.md)
• [Performance & Scalability 2026](./references/performance-scalability.md)
• [Migration & Refactoring Strategies](./references/migration-refactoring.md)
• [Repository Analysis Guide](./references/repository-analysis.md)

---

Before refactoring, always analyze the existing codebase structure.

```bash

# Optimized command for architecture discovery

npx repomix@latest --include "src/*/.ts" --compress --output /tmp/arch-discovery.xml

```

Using Repomix allows you to "pack" your architecture into a single file that can be fed into an AI for a full audit.

---

• [ ] Is my Domain Layer free of external dependencies?
• [ ] Are my Use Cases doing only orchestration?
• [ ] Do I have interfaces (Ports) for all external services (DB, Auth, Mail, Stripe)?
• [ ] Am I using Value Objects for things like Email, Money, and Address?
• [ ] Is my code testable without a real database?
• [ ] Have I mapped my infrastructure errors to domain exceptions?
• [ ] Have I used ADRs to document major architectural decisions?
• [ ] Is my ubiquitous language reflected in the code?

---

Updated: January 22, 2026 - 15:18