Clean Architecture in Next.js

Every project starts simple. A page.tsx that fetches data and renders it. A few components. One API route. Then requirements grow, the team expands, and suddenly changing the data source requires touching a dozen files.

The Problem with Naive Next.js

The default Next.js approach encourages direct data access in Server Components. fetch() calls inside page files, Prisma queries next to JSX, business logic in API routes. This works — until it doesn't.

The Four-Layer Solution

We structure every project with four layers:

1. Domain — pure TypeScript interfaces and value objects. No imports.
2. Application — use cases and port interfaces. Imports domain only.
3. Infrastructure — adapters implementing ports. Imports application.
4. Presentation — React components. Calls use cases via a DI container.

The rule is simple: dependencies point inward. The domain never changes because the UI changed.

Real Benefits

When we built the Invoice Extractor, this architecture let us swap from a third-party OCR API to a fine-tuned local model in under two hours — touching only the infrastructure adapter, with every test still passing.

That's the promise of Clean Architecture: isolated, testable, swappable.