Clean Architecture Explained With a Tiny Example App

Quickstart

If you want the benefit of Clean Architecture quickly, don’t start by drawing circles. Start by moving IO (web, DB, queue, filesystem) to the edges and keeping use cases in the middle. These steps work even if you never create more than 3–4 folders.

Minimal folder map (copy/paste)

This is a tiny structure that still captures the key idea: core code is independent; adapters do the messy IO. You can rename folders to match your stack—what matters is the dependency direction.

# tiny-clean-arch/
#   Core: domain + use cases (no framework imports)
#   Edges: adapters (db/web) + composition root (wiring)
.
├─ src/
│  ├─ core/
│  │  ├─ domain/              # entities + value objects
│  │  └─ usecases/            # application business rules
│  ├─ ports/                  # interfaces owned by the core
│  ├─ adapters/
│  │  ├─ http/                # controllers + request/response mapping
│  │  └─ persistence/         # db/orm implementations of ports
│  └─ main.ts                 # composition root (wires dependencies)
└─ test/
   └─ core/                   # unit tests (no db, no http)

Overview

“Clean Architecture” (popularized by Robert C. Martin) is often taught with concentric circles: entities at the center, then use cases, then adapters, then frameworks. That diagram is helpful, but it can also lead to overengineering if you treat it like a mandatory folder structure.

Why it matters: most codebases don’t rot because the framework is “bad”. They rot because the framework becomes the only place where decisions live. When business rules are scattered across controllers, ORMs, cron jobs, and background workers, changes get slow, tests become fragile, and “simple features” turn into risky refactors.

Core concepts

1) The dependency rule (the whole game)

The rule is simple: source code dependencies must point inward. Your business rules should not import your database library, web framework, or third-party SDKs. Instead, the business rules define what they need (interfaces/ports), and the outer layers implement those needs.

2) The four circles (as responsibilities, not folders)

You’ll see variations (Hexagonal/Ports & Adapters, Onion Architecture, etc.), but the responsibilities usually map like this:

3) Ports & adapters (how the core talks to the world)

A port is an interface owned by the core. It describes a capability the core needs. An adapter is an implementation owned by the outside. It uses real libraries to satisfy the port.

Step-by-step

Let’s design a tiny example app: Tasks. Requirements (intentionally small):

• Create a task with a title
• Mark a task as completed
• List tasks (with completed state)

Step 1 — Define the core model (entity + invariants)

Start with the rule-bearing object. Keep it boring and enforce the rules that must always hold. For tasks, a title cannot be empty; completing sets a timestamp.

Step 2 — Write a use case that depends on ports, not implementations

The use case is the “application brain”: it orchestrates the workflow. It should read like a story: validate input → load/save via repository → return a result. Notice how it doesn’t know anything about HTTP or databases.

export type TaskId = string;

export class Task {
  constructor(
    public readonly id: TaskId,
    public readonly title: string,
    public readonly createdAt: Date,
    public readonly completedAt: Date | null
  ) {
    if (title.trim().length === 0) throw new Error("Title must not be empty");
  }

  complete(at: Date): Task {
    if (this.completedAt) return this; // idempotent
    return new Task(this.id, this.title, this.createdAt, at);
  }
}

export interface TaskRepository {
  getById(id: TaskId): Promise<Task | null>;
  save(task: Task): Promise<void>;
}

export interface Clock {
  now(): Date;
}

export interface IdGenerator {
  nextId(): TaskId;
}

export type CreateTaskInput = { title: string };
export type CreateTaskOutput = { id: TaskId; title: string; createdAt: string };

export class CreateTask {
  constructor(
    private readonly repo: TaskRepository,
    private readonly ids: IdGenerator,
    private readonly clock: Clock
  ) {}

  async execute(input: CreateTaskInput): Promise<CreateTaskOutput> {
    const title = input.title?.trim() ?? "";
    if (title.length === 0) throw new Error("Title is required");

    const task = new Task(this.ids.nextId(), title, this.clock.now(), null);
    await this.repo.save(task);

    return {
      id: task.id,
      title: task.title,
      createdAt: task.createdAt.toISOString()
    };
  }
}

Step 3 — Build adapters (HTTP + persistence) that map in/out

Adapters translate between the messy world and your clean core. This is where frameworks belong: JSON parsing, status codes, ORM calls, retries, logging, headers, auth middleware, and so on.

Step 4 — Wire dependencies in a composition root

Clean Architecture doesn’t mean “dependency injection framework.” It means: build concrete implementations once, then pass them into use cases. Keep this wiring in one file so it’s easy to see how the app is assembled.

Step 5 — Prove the architecture with a unit test

This is where the approach pays off: you can test business rules with a fake repository and fake time. No Docker. No test DB. No HTTP server. Just code.

import { CreateTask, TaskRepository, Clock, IdGenerator, Task } from "../src/core/usecases/CreateTask";

class InMemoryTaskRepo implements TaskRepository {
  public saved: Task[] = [];
  async getById(): Promise<Task | null> { return null; }
  async save(task: Task): Promise<void> { this.saved.push(task); }
}

class FixedClock implements Clock {
  constructor(private readonly d: Date) {}
  now(): Date { return this.d; }
}

class FixedIds implements IdGenerator {
  constructor(private readonly id: string) {}
  nextId(): string { return this.id; }
}

test("CreateTask saves a task and returns DTO", async () => {
  const repo = new InMemoryTaskRepo();
  const ids = new FixedIds("t_123");
  const clock = new FixedClock(new Date("2026-01-01T00:00:00.000Z"));

  const uc = new CreateTask(repo, ids, clock);
  const out = await uc.execute({ title: "  buy milk  " });

  expect(out.id).toBe("t_123");
  expect(out.title).toBe("buy milk");
  expect(out.createdAt).toBe("2026-01-01T00:00:00.000Z");
  expect(repo.saved).toHaveLength(1);
});

Common mistakes

Clean Architecture fails in two ways: too little boundary (everything is glued to frameworks) or too much ceremony (interfaces for every method, dozens of layers, no speed). Here are the most common traps and the fixes that keep things practical.

FAQ

Is Clean Architecture the same as Hexagonal (Ports & Adapters) or Onion Architecture?

They’re closely related. The vocabulary differs, but the core idea is the same: keep business rules independent and push IO concerns to the edges via ports/adapters. If your dependencies point inward and you can swap adapters, you’re effectively doing all of them.

Do I need Clean Architecture for a small project?

Not the full ceremony. The high-value move for small apps is just: extract use cases into framework-free functions/classes and keep controllers thin. That gives you testability and reuse without multiplying layers.

Where should input validation live?

Split it. Do transport validation at the edge (JSON shape, required fields, type parsing), and do business validation in the core (rules like “title must not be empty”, “cannot complete twice”, “limit tasks per user”, etc.). That way the rules apply no matter how the use case is called.

Where do DTOs and mapping belong?

Mapping belongs in adapters. The core can define input/output DTOs for use cases, but the act of converting HTTP requests or DB rows into those DTOs should happen at the edge. The core should not know about headers, cookies, query params, or table schemas.

How do I handle database transactions with Clean Architecture?

Decide an explicit strategy. A common approach is: the use case calls a repository method that is transaction-aware, or you introduce a “UnitOfWork” port that wraps multiple repository actions. What matters is that transaction mechanics stay out of the domain model and don’t leak database types into the core.

What if my framework pushes me toward annotations/decorators in the core?

Treat annotations as an adapter concern when possible. If you can’t avoid them entirely, minimize the footprint: keep framework-specific classes in the outer layer and call the core from there. It’s better to have one “dirty boundary file” than to spread framework imports throughout the core.

What’s the easiest way to know if I did it right?

Run the “swap test” and the “unit test test”: you should be able to unit test use cases with fakes, and you should be able to swap persistence (in-memory ↔ DB) without rewriting business rules. If both are true, your architecture is doing its job.

Cheatsheet

Scan this when you’re refactoring or starting a new feature.

Wrap-up

Clean Architecture is a way to keep the meaning of your system (business rules) stable while the outside world changes. The tiny “Tasks” example shows the practical core: use cases that depend on ports, plus adapters that do the IO.

Keep the goal in mind: not “perfect architecture”, but cheaper change. If a new feature becomes easier to build and safer to test, the architecture is paying rent.

Related posts

• Domain-Driven Design Lite: The Useful 20%
• Event-Driven Architecture: When Events Actually Help
• API Design Rules: Consistency Beats Cleverness
• Caching Patterns: Read-Through, Write-Through, and Busting
• Design for Observability: Logs, Metrics, Traces as Requirements
• Dependency Hell Prevention: Modular Boundaries and APIs