Skip to content

NestJS ports and adapters example

Open-source sketch of hexagonal architecture in NestJS: users and roles behind ports, use cases and adapters

An unfinished reference project for how I wanted to layer NestJS services: an Auth context for users and roles with commands and queries as incoming ports, repositories as outgoing ports, one use case per operation, and MikroORM behind mappers.

The problem

NestJS services tend to mix persistence, business rules and HTTP concerns in the same class, which makes them hard to test and to change.

What I built

Domain entities with no framework imports, incoming ports for commands and queries, outgoing repository ports, use case classes that depend only on ports, and MikroORM persistence entities with mappers on the adapter side. Shared building blocks such as an aggregate root and a base repository live in a shared-kernel library.

Results

  • The separation of domain, application, infrastructure and presentation layers carried into the MediOne, Dube, church and booking backends.

Features

  • Users, roles and role assignment as one bounded context
  • Commands and queries with @nestjs/cqrs
  • Repository ports with MikroORM adapters and mappers
  • Shared-kernel library with aggregate root and base repository
  • Typed configuration library
  • Swagger UI for the E.D.G.E School Management API with its description and the first endpoint groups
    Web apps2025

    E.D.G.E school management system

    Genesis AI Labs

    School platform covering registration, attendance, marks, fees and timetables, with a DDD backend and a React admin

    Led the buildNestJSMikroORMPostgreSQL+13
  • MediOne catalogue screen in French with a medicine search box, category chips and a grid of products showing stock status and prices in Djibouti francs
    Mobile apps2026

    MediOne

    MediOne, Djibouti

    Online pharmacy and delivery for Djibouti, with a NestJS API and an Expo app that tracks orders on a map

    Solo buildNestJSMikroORMPostgreSQL+13
  • Dube home screen showing ETB 3,125.50 total outstanding and a list of customers with their balances and call buttons
    Mobile apps2026

    Dube

    Offline-first debt book for shopkeepers: an Android app, a sync API and an admin panel

    Solo buildExpoReact Nativeexpo-sqlite+15