Hexagonal architecture (ports & adapters)

                 ┌──────────────────────── outside: adapters ──────────────────────────┐
                 │  presentation (driving)                 infrastructure (driven)     │
  user ────────▶ │  TasksPage, TaskItem                    HttpTaskRepository, TaskDto │ ──▶ server
                 │        │   ┌──────────── application ─────────────┐   ▲             │
                 │        └──▶│ TaskBoard / AddTask ──▶ TaskRepository│───┘ implements   │
                 │            │        │      ┌──── domain ────┐     │                  │
                 │            │        └─────▶│ Task, createTask│    │                  │
                 │            │               └─────────────────┘     │                  │
                 │            └───────────────────────────────────────┘                  │
                 └──────────────────────────────────────────────────────────────────────┘
  Rule: import arrows point ONLY inward. The domain imports nothing from outside.
  app.config.ts (composition root) is the only place that binds TaskRepository to an adapter.

// tasks/domain/task.ts — pure TypeScript: no import from Angular, RxJS or the browser
export type TaskId = string & { readonly __brand: 'TaskId' };

export interface Task {
  readonly id: TaskId;
  readonly title: string;
  readonly done: boolean;
  readonly createdAt: Date;
}

export class DomainError extends Error {
  override readonly name = 'DomainError';
}

export function normalizeTitle(raw: string): string {
  return raw.trim().replace(/\s+/g, ' ');
}

// `now` and `id` come in as parameters: the domain neither reads the clock nor generates ids on its own
export function createTask(raw: string, existing: readonly Task[], now: Date, id: TaskId): Task {
  const title = normalizeTitle(raw);
  if (title.length < 3) throw new DomainError('The title needs at least 3 characters.');
  if (existing.some((t) => !t.done && t.title.toLowerCase() === title.toLowerCase())) {
    throw new DomainError('There is already an open task with this title.');
  }
  return { id, title, done: false, createdAt: now };
}

export function toggleTask(task: Task): Task {
  return { ...task, done: !task.done };
}

// tasks/application/task-repository.ts — the PORT
import { Task, TaskId } from '../domain/task';

// Abstract class, not an interface: it exists at runtime, so it is a DI token as-is.
// It has no @Injectable and knows of no implementation.
export abstract class TaskRepository {
  abstract list(): Promise<readonly Task[]>;
  abstract save(task: Task): Promise<void>; // upsert
  abstract remove(id: TaskId): Promise<void>;
}

// Part of the contract: adapters translate their technical errors into this.
export class RepositoryUnavailableError extends Error {
  override readonly name = 'RepositoryUnavailableError';
}

// tasks/application/add-task.ts — one use case = a class with a single public method
import { Injectable, inject } from '@angular/core';
import { Task, TaskId, createTask } from '../domain/task';
import { TaskRepository } from './task-repository';

@Injectable({ providedIn: 'root' })
export class AddTask {
  private readonly repo = inject(TaskRepository); // the port — does not know which adapter answers

  async execute(title: string): Promise<Task> {
    const existing = await this.repo.list();
    const task = createTask(title, existing, new Date(), crypto.randomUUID() as TaskId); // the rule: in the domain
    await this.repo.save(task); // I/O: through the port
    return task;
  }
}

// tasks/infrastructure/http-task-repository.ts — the HTTP ADAPTER
import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { Injectable, inject } from '@angular/core';
import { Observable, firstValueFrom } from 'rxjs';
import { Task, TaskId } from '../domain/task';
import { RepositoryUnavailableError, TaskRepository } from '../application/task-repository';
import { TaskDto, taskFromDto, taskToDto } from './task-dto';

@Injectable()
export class HttpTaskRepository extends TaskRepository {
  private readonly http = inject(HttpClient);
  private readonly url = '/api/tasks';

  async list(): Promise<readonly Task[]> {
    const dtos = await this.call(this.http.get<TaskDto[]>(this.url));
    return dtos.map(taskFromDto); // DTO → domain, here and nowhere else
  }

  async save(task: Task): Promise<void> {
    await this.call(this.http.put<TaskDto>(`${this.url}/${task.id}`, taskToDto(task)));
  }

  async remove(id: TaskId): Promise<void> {
    await this.call(this.http.delete<void>(`${this.url}/${id}`));
  }

  // HttpErrorResponse does not leave the adapter: the core receives the port's error
  private async call<T>(request: Observable<T>): Promise<T> {
    try {
      return await firstValueFrom(request);
    } catch (e) {
      if (e instanceof HttpErrorResponse) throw new RepositoryUnavailableError(`HTTP ${e.status}`);
      throw e;
    }
  }
}

// app.config.ts — COMPOSITION ROOT: the only file that knows which adapter we use
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(withInterceptors([authInterceptor])),
    { provide: TaskRepository, useClass: HttpTaskRepository },
  ],
};

// Use-case test: the in-memory adapter instead of HTTP
import { TestBed } from '@angular/core/testing';

describe('AddTask', () => {
  let addTask: AddTask;
  let repo: InMemoryTaskRepository;

  beforeEach(() => {
    TestBed.configureTestingModule({
      providers: [{ provide: TaskRepository, useClass: InMemoryTaskRepository }],
    });
    addTask = TestBed.inject(AddTask);
    repo = TestBed.inject(TaskRepository) as InMemoryTaskRepository;
  });

  it('saves through the port', async () => {
    await addTask.execute('Write tests');
    expect((await repo.list()).map((t) => t.title)).toEqual(['Write tests']);
  });

  it('saves nothing if a domain rule is broken', async () => {
    await expect(addTask.execute('ab')).rejects.toThrow(DomainError);
    expect(await repo.list()).toEqual([]);
  });
});

// The dependency rule, checked on every commit (ESLint no-restricted-imports with regex)
export default [
  {
    files: ['src/app/features/*/domain/**/*.ts'],
    rules: {
      'no-restricted-imports': ['error', { patterns: [
        { regex: '^(@angular/|rxjs)', message: 'The domain is pure TypeScript: no Angular, no RxJS.' },
        { regex: '/(application|infrastructure|ui)/', message: 'The domain does not depend on the outer layers.' },
      ] }],
    },
  },
  {
    files: ['src/app/features/*/application/**/*.ts'],
    rules: {
      'no-restricted-imports': ['error', { patterns: [
        { regex: '/(infrastructure|ui)/', message: 'Application depends on ports, not on adapters or UI.' },
        { regex: '^@angular/common/http', message: 'HTTP only in infrastructure.' },
      ] }],
    },
  },
  {
    files: ['src/app/features/*/ui/**/*.ts'],
    rules: {
      'no-restricted-imports': ['error', { patterns: [
        { regex: '/infrastructure/', message: 'The UI injects the port or the use case, not the adapter.' },
      ] }],
    },
  },
];
// In an Nx monorepo: domain/application/infrastructure as separate libraries, with tags
// and @nx/enforce-module-boundaries (see the Monorepo page).

// ✗ "Default implementation" placed on the port
@Injectable({ providedIn: 'root', useClass: HttpTaskRepository }) // the port imports the adapter!
export abstract class TaskRepository { /* ... */ }
// Application → infrastructure: the dependency rule is broken, and HttpClient
// ends up in the bundle even for the app that only uses localStorage.

// ✓ The port stays empty; the choice lives in the composition root
export abstract class TaskRepository { /* ... */ }
providers: [{ provide: TaskRepository, useClass: HttpTaskRepository }]

LAYERS (imports point only inward)
  domain          Task, createTask()         pure TypeScript — no Angular, RxJS, browser
  application     TaskRepository (port)      abstract class = type + DI token
                  AddTask / TaskBoard        inject(TaskRepository), signals for the UI
  infrastructure  HttpTaskRepository         extends TaskRepository, DTO ↔ domain, errors translated
  presentation    TasksPage, TaskItem        injects application, never infrastructure
  composition     app.config / route.providers  { provide: TaskRepository, useClass: Http… }

RECIPES
  swap the adapter         another useClass in the composition root (or provideTasks('local'))
  use-case test            providers: [{ provide: TaskRepository, useClass: InMemoryTaskRepository }]
  adapter test             shared contract + HttpTestingController for the HTTP mapping
  DTO                      only in infrastructure; the port speaks in entities
  errors                   the adapter throws RepositoryUnavailableError, not HttpErrorResponse

WHEN NOT
  CRUD without rules, small app, prototype → httpResource in the component + mapping in parse