How emerson-feral/hexagonal-architecture works
Project type and purpose
• This is a Node.js/TypeScript backend service organized according to the Hexagonal (Ports & Adapters) architecture.
• Its purpose is to handle user-related use cases (CRUD, business rules) via a clean separation between core domain logic and external adapters (HTTP, persistence).
File structure
• Top-level manifests: package.json, tsconfig.json, server entry point (infrastructure/server.ts).
• src/domain: domain entities (User.ts) encapsulating business data and invariants.
• src/application
• ports: interfaces (UserRepository) that abstract persistence behind a stable API
• services: business use‐case implementations (UserService) orchestrating domain logic and ports
• src/infrastructure
• controllers: HTTP adapters (UserController) translating incoming requests into calls on the application layer
• repositories: concrete adapters (InMemoryUserRepository) implementing the ports to store/fetch Users
• server.ts: bootstraps the HTTP server, wires controllers and repository implementations into the application services
README for additional insights
• Confirms Hexagonal architecture: separate domain, application (use cases), and infrastructure (adapters) folders.
• Emphasizes clean dependencies inward: infrastructure → application → domain.
a. Main components:
• Domain Core: User entity
• Application Services Layer: UserService
• Ports: UserRepository interface
• Adapters (Infrastructure):
• HTTP Controller (UserController)
• Persistence Adapter (InMemoryUserRepository)
• Entry Point: Server (infrastructure/server.ts)
• External actors: API clients (e.g., Postman, frontend) and Persistence Store (in this case in-memory, but could be DB)
b. Relationships and interactions:
• Clients → HTTP Controller → Application Service → Domain Entity & Port → Persistence Adapter → (back)
• The Server wires the concrete repository into the service via the port interface.
c. Architectural pattern:
• Hexagonal: concentric layers, stable interfaces (ports) at the core boundary, adapters on the outside.
d. Technologies/frameworks:
• Node.js + Express/Koa (or HTTP library) for server.ts
• TypeScript for static typing
• In-memory repository (to be swapped with a real database adapter later)
Detailed capture of architectural elements
• Don’t just lump “backend” together—split into Domain, Use Cases, Ports, Controllers, Repositories, Server.
• Explicitly show the inversion of control: Application services depend on the UserRepository interface (not the concrete repository).
• That swapping out InMemoryUserRepository for a SQL or NoSQL adapter is as easy as wiring a different adapter in server.ts.