# neckerfree/employee-directory-demo architecture

> Architecture diagram of the GitHub repository neckerfree/employee-directory-demo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/neckerfree/employee-directory-demo
- Repository: https://github.com/neckerfree/employee-directory-demo

## Overview

This is a Clean Architecture employee-directory CRUD application: users manage departments and employees, with employee search/listing and department assignment, through a React SPA and ASP.NET API backed by PostgreSQL. The main runtime flow crosses the UI, API controllers, application use cases, repository/unit-of-work ports, and EF Core persistence; domain entities enforce core invariants. The README documents the broader stack, while the shown source provides stronger relationship evidence for the CRUD and persistence layers than for every UI-to-API detail.

Main entry points: [`src/EmployeeDirectory.Application/Employees`](https://github.com/neckerfree/employee-directory-demo/tree/main/src/EmployeeDirectory.Application/Employees) (Employee use cases), [`src/EmployeeDirectory.Infrastructure/Persistence/AppDbContext.cs`](https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Infrastructure/Persistence/AppDbContext.cs) (EF Core context), [`src/EmployeeDirectory.Application/Departments`](https://github.com/neckerfree/employee-directory-demo/tree/main/src/EmployeeDirectory.Application/Departments) (Department use cases), [`src/web/src/api/apiSlice.ts`](https://github.com/neckerfree/employee-directory-demo/blob/main/src/web/src/api/apiSlice.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["React directory UI"]
  node_webapp["SPA routes<br/>[App.tsx]"]
  node_webemployees["Employee pages"]
  node_webdepartments["Department page"]
  node_webapi["API client<br/>[apiSlice.ts]"]
end

subgraph group_api["HTTP API"]
  node_employeecontroller["Employee endpoints"]
  node_departmentcontroller["Department endpoints"]
  node_middleware["Request middleware"]
  node_program["API composition<br/>[Program.cs]"]
end

subgraph group_application["Application use cases"]
  node_employeeusecases["Employee use cases<br/>[Employees]"]
  node_departmentusecases["Department use cases<br/>[Departments]"]
  node_employeerepoport["Employee repository port"]
  node_departmentrepoport["Department repository port"]
  node_unitofwork["Commit port<br/>[IUnitOfWork.cs]"]
end

subgraph group_domain["Domain model"]
  node_employeeentity["Employee aggregate<br/>[Employee.cs]"]
  node_departmententity["Department entity<br/>[Department.cs]"]
end

subgraph group_infrastructure["EF persistence"]
  node_employeerepo["Employee repository"]
  node_departmentrepo["Department repository"]
  node_dbcontext["EF Core context<br/>[AppDbContext.cs]"]
  node_uowimpl["Unit of work<br/>[UnitOfWork.cs]"]
  node_healthcheck["Database health"]
end

node_user(("Directory user"))
node_postgres[("PostgreSQL")]

node_user -.->|"uses"| node_webapp
node_webapp -->|"routes to"| node_webemployees
node_webapp -->|"routes to"| node_webdepartments
node_webemployees -.->|"requests data"| node_webapi
node_webdepartments -.->|"requests data"| node_webapi
node_webapi -.->|"calls API"| node_employeecontroller
node_webapi -.->|"calls API"| node_departmentcontroller
node_employeecontroller -->|"dispatches"| node_employeeusecases
node_departmentcontroller -->|"dispatches"| node_departmentusecases
node_program -->|"configures"| node_middleware
node_employeeusecases -->|"queries and mutates"| node_employeerepoport
node_employeeusecases -->|"checks department"| node_departmentrepoport
node_employeeusecases -->|"commits changes"| node_unitofwork
node_employeeusecases -->|"creates and updates"| node_employeeentity
node_employeeusecases -->|"checks membership"| node_departmententity
node_departmentusecases -->|"queries and mutates"| node_departmentrepoport
node_departmentusecases -->|"checks assignments"| node_employeerepoport
node_departmentusecases -->|"commits changes"| node_unitofwork
node_employeerepo -->|"uses EF context"| node_dbcontext
node_departmentrepo -->|"uses EF context"| node_dbcontext
node_uowimpl -.->|"commits through"| node_dbcontext
node_healthcheck -->|"checks database"| node_dbcontext
node_dbcontext -.->|"persists data"| node_postgres

click node_webapp "https://github.com/neckerfree/employee-directory-demo/blob/main/src/web/src/App.tsx"
click node_webemployees "https://github.com/neckerfree/employee-directory-demo/blob/main/src/web/src/pages/EmployeeDirectoryPage.tsx"
click node_webdepartments "https://github.com/neckerfree/employee-directory-demo/blob/main/src/web/src/pages/DepartmentsPage.tsx"
click node_webapi "https://github.com/neckerfree/employee-directory-demo/blob/main/src/web/src/api/apiSlice.ts"
click node_employeecontroller "https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Api/Controllers/EmployeesController.cs"
click node_departmentcontroller "https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Api/Controllers/DepartmentsController.cs"
click node_middleware "https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Api/Middleware/CorrelationIdMiddleware.cs"
click node_program "https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Api/Program.cs"
click node_employeeusecases "https://github.com/neckerfree/employee-directory-demo/tree/main/src/EmployeeDirectory.Application/Employees"
click node_departmentusecases "https://github.com/neckerfree/employee-directory-demo/tree/main/src/EmployeeDirectory.Application/Departments"
click node_employeerepoport "https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Application/Employees/IEmployeeRepository.cs"
click node_departmentrepoport "https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Application/Departments/IDepartmentRepository.cs"
click node_unitofwork "https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Application/Common/IUnitOfWork.cs"
click node_employeeentity "https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Domain/Entities/Employee.cs"
click node_departmententity "https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Domain/Entities/Department.cs"
click node_employeerepo "https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Infrastructure/Repositories/EmployeeRepository.cs"
click node_departmentrepo "https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Infrastructure/Repositories/DepartmentRepository.cs"
click node_dbcontext "https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Infrastructure/Persistence/AppDbContext.cs"
click node_uowimpl "https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Infrastructure/Persistence/UnitOfWork.cs"
click node_healthcheck "https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Infrastructure/Persistence/DatabaseHealthCheck.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_webemployees,node_webdepartments,node_webapi,node_user toneBlue
class node_employeecontroller,node_departmentcontroller,node_middleware,node_program,node_postgres toneAmber
class node_employeeusecases,node_departmentusecases,node_employeerepoport,node_departmentrepoport,node_unitofwork toneMint
class node_employeeentity,node_departmententity toneRose
class node_employeerepo,node_departmentrepo,node_dbcontext,node_uowimpl,node_healthcheck toneIndigo
```

## Components

### React directory UI

- [SPA routes](https://github.com/neckerfree/employee-directory-demo/blob/main/src/web/src/App.tsx): `src/web/src/App.tsx`
- [Employee pages](https://github.com/neckerfree/employee-directory-demo/blob/main/src/web/src/pages/EmployeeDirectoryPage.tsx): `src/web/src/pages/EmployeeDirectoryPage.tsx`
- [Department page](https://github.com/neckerfree/employee-directory-demo/blob/main/src/web/src/pages/DepartmentsPage.tsx): `src/web/src/pages/DepartmentsPage.tsx`
- [API client](https://github.com/neckerfree/employee-directory-demo/blob/main/src/web/src/api/apiSlice.ts): `src/web/src/api/apiSlice.ts`

### HTTP API

- [Employee endpoints](https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Api/Controllers/EmployeesController.cs): `src/EmployeeDirectory.Api/Controllers/EmployeesController.cs`
- [Department endpoints](https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Api/Controllers/DepartmentsController.cs): `src/EmployeeDirectory.Api/Controllers/DepartmentsController.cs`
- [Request middleware](https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Api/Middleware/CorrelationIdMiddleware.cs): `src/EmployeeDirectory.Api/Middleware/CorrelationIdMiddleware.cs`
- [API composition](https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Api/Program.cs): `src/EmployeeDirectory.Api/Program.cs`

### Application use cases

- [Employee use cases](https://github.com/neckerfree/employee-directory-demo/tree/main/src/EmployeeDirectory.Application/Employees): `src/EmployeeDirectory.Application/Employees`
- [Department use cases](https://github.com/neckerfree/employee-directory-demo/tree/main/src/EmployeeDirectory.Application/Departments): `src/EmployeeDirectory.Application/Departments`
- [Employee repository port](https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Application/Employees/IEmployeeRepository.cs): `src/EmployeeDirectory.Application/Employees/IEmployeeRepository.cs`
- [Department repository port](https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Application/Departments/IDepartmentRepository.cs): `src/EmployeeDirectory.Application/Departments/IDepartmentRepository.cs`
- [Commit port](https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Application/Common/IUnitOfWork.cs): `src/EmployeeDirectory.Application/Common/IUnitOfWork.cs`

### Domain model

- [Employee aggregate](https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Domain/Entities/Employee.cs): `src/EmployeeDirectory.Domain/Entities/Employee.cs`
- [Department entity](https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Domain/Entities/Department.cs): `src/EmployeeDirectory.Domain/Entities/Department.cs`

### EF persistence

- [Employee repository](https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Infrastructure/Repositories/EmployeeRepository.cs): `src/EmployeeDirectory.Infrastructure/Repositories/EmployeeRepository.cs`
- [Department repository](https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Infrastructure/Repositories/DepartmentRepository.cs): `src/EmployeeDirectory.Infrastructure/Repositories/DepartmentRepository.cs`
- [EF Core context](https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Infrastructure/Persistence/AppDbContext.cs): `src/EmployeeDirectory.Infrastructure/Persistence/AppDbContext.cs`
- [Unit of work](https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Infrastructure/Persistence/UnitOfWork.cs): `src/EmployeeDirectory.Infrastructure/Persistence/UnitOfWork.cs`
- [Database health](https://github.com/neckerfree/employee-directory-demo/blob/main/src/EmployeeDirectory.Infrastructure/Persistence/DatabaseHealthCheck.cs): `src/EmployeeDirectory.Infrastructure/Persistence/DatabaseHealthCheck.cs`

### Other components

- **Directory user**
- **PostgreSQL**

## Connections

- Directory user → SPA routes: uses
- SPA routes → Employee pages: routes to (evidence: `src/web/src/App.tsx`)
- SPA routes → Department page: routes to (evidence: `src/web/src/App.tsx`)
- Employee pages → API client: requests data
- Department page → API client: requests data
- API client → Employee endpoints: calls API (evidence: `README.md`)
- API client → Department endpoints: calls API (evidence: `README.md`)
- Employee endpoints → Employee use cases: dispatches (evidence: `src/EmployeeDirectory.Api/Controllers/EmployeesController.cs`)
- Department endpoints → Department use cases: dispatches (evidence: `src/EmployeeDirectory.Api/Controllers/DepartmentsController.cs`)
- API composition → Request middleware: configures (evidence: `src/EmployeeDirectory.Api/Program.cs`)
- Employee use cases → Employee repository port: queries and mutates (evidence: `src/EmployeeDirectory.Application/Employees/CreateEmployeeHandler.cs`)
- Employee use cases → Department repository port: checks department (evidence: `src/EmployeeDirectory.Application/Employees/CreateEmployeeHandler.cs`)
- Employee use cases → Commit port: commits changes (evidence: `src/EmployeeDirectory.Application/Employees/CreateEmployeeHandler.cs`)
- Employee use cases → Employee aggregate: creates and updates (evidence: `src/EmployeeDirectory.Application/Employees/CreateEmployeeHandler.cs`)
- Employee use cases → Department entity: checks membership (evidence: `src/EmployeeDirectory.Application/Employees/CreateEmployeeHandler.cs`)
- Department use cases → Department repository port: queries and mutates (evidence: `src/EmployeeDirectory.Application/Departments/DeleteDepartmentHandler.cs`)
- Department use cases → Employee repository port: checks assignments (evidence: `src/EmployeeDirectory.Application/Departments/DeleteDepartmentHandler.cs`)
- Department use cases → Commit port: commits changes (evidence: `src/EmployeeDirectory.Application/Departments/DeleteDepartmentHandler.cs`)
- Employee repository → EF Core context: uses EF context (evidence: `src/EmployeeDirectory.Infrastructure/Repositories/EmployeeRepository.cs`)
- Department repository → EF Core context: uses EF context (evidence: `src/EmployeeDirectory.Infrastructure/Repositories/DepartmentRepository.cs`)
- Unit of work → EF Core context: commits through
- Database health → EF Core context: checks database (evidence: `src/EmployeeDirectory.Infrastructure/Persistence/DatabaseHealthCheck.cs`)
- EF Core context → PostgreSQL: persists data (evidence: `README.md`)
