# panagiop/node.js-clean-architecture architecture

> Architecture diagram of the GitHub repository panagiop/node.js-clean-architecture, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/panagiop/node.js-clean-architecture
- Repository: https://github.com/panagiop/node.js-clean-architecture

## Overview

#### Purpose and startup
A Node.js REST API demonstrating Clean Architecture for users, authentication, and CRUD posts. The composition/startup path is `app.js`, through the Express/server framework in `frameworks/webserver/express.js` and `frameworks/webserver/server.js`. It is runnable directly with Node or as Docker services via `Dockerfile` and `docker-compose.yml`.

#### Dependency structure
The repository follows inward dependencies: framework implementations feed adapters, adapters invoke application use cases, and use cases operate on framework-independent entities. Core domain models are `src/entities/post.js` and `src/entities/user.js`; they should not depend on Express, MongoDB, Redis, or authentication libraries.

#### HTTP boundary and controllers
Express routes expose auth, user, and post resources through `frameworks/webserver/routes/index.js`, `frameworks/webserver/routes/post.js`, and `frameworks/webserver/routes/auth.js`. Controllers translate HTTP request/response data into application calls and responses: `adapters/controllers/postController.js`, `adapters/controllers/userController.js`, and `adapters/controllers/authController.js`.

#### Application workflows
Use cases own application operations rather than route handlers. Post workflows are separated into commands and queries under `application/use_cases/post/add.js`, `application/use_cases/post/updateById.js`, and `application/use_cases/post/findAll.js`; user lookup/creation is under `application/use_cases/user/add.js` and `application/use_cases/user/findByProperty.js`. Authentication orchestration resides in `application/use_cases/auth/login.js`.

#### Repository ports and persistence adapters
Application-facing repository modules define the data-access boundary: `application/repositories/postDbRepository.js`, `application/repositories/postRedisRepository.js`, and `application/repositories/userDbRepository.js`. MongoDB implementations and Mongoose-style models are isolated in `frameworks/database/mongoDB/repositories/postRepositoryMongoDB.js`, `frameworks/database/mongoDB/models/post.js`, and `frameworks/database/mongoDB/connection.js`. This permits persistence replacement without changing entities or use cases.

#### Caching, auth, and error flow
Redis is an outer infrastructure cache, connected by `frameworks/database/redis/connection.js` and implemented for posts in `frameworks/database/redis/postRepositoryRedis.js`. Request flow can pass through `frameworks/webserver/middlewares/redisCachingMiddleware.js`; post mutations/read workflows are expected to coordinate DB and cache through the repository boundary. Protected routes use `frameworks/webserver/middlewares/authMiddleware.js`; centralized failures are emitted through `frameworks/webserver/middlewares/errorHandlingMiddleware.js`. Auth use cases depend on the application-facing service abstraction in `application/services/authService.js`, backed by `frameworks/services/authService.js`.

#### Runtime and infrastructure
The runtime is Express on Node.js, with MongoDB as durable storage and Redis as cache. Environment/configuration wiring is centralized in `config/config.js`. Container deployment is supported by `Dockerfile` and `docker-compose.yml`, which are material to running the API alongside its database services.

Main entry points: [`adapters/controllers/postController.js`](https://github.com/panagiop/node.js-clean-architecture/blob/master/adapters/controllers/postController.js) (HTTP controllers), [`app.js`](https://github.com/panagiop/node.js-clean-architecture/blob/master/app.js) (Application bootstrap), [`frameworks/webserver/routes/index.js`](https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/webserver/routes/index.js) (Resource routes), [`application/repositories/postDbRepository.js`](https://github.com/panagiop/node.js-clean-architecture/blob/master/application/repositories/postDbRepository.js) (Repository ports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_compose{{"Docker deployment<br/>container deployment<br/>[docker-compose.yml]"}}
  node_dockerfile["API image<br/>Docker build"]
  node_app["Application bootstrap<br/>Node entrypoint<br/>[app.js]"]
  node_config["Runtime configuration<br/>configuration wiring<br/>[config.js]"]
end

subgraph group_http["HTTP boundary"]
  node_express["Express setup<br/>web framework adapter<br/>[express.js]"]
  node_server["HTTP server<br/>server runtime<br/>[server.js]"]
  node_routes["Resource routes<br/>Express routes<br/>[index.js]"]
  node_controllers["HTTP controllers<br/>controller adapters<br/>[postController.js]"]
  node_auth_middleware["Auth middleware<br/>route middleware<br/>[authMiddleware.js]"]
  node_cache_middleware["Redis cache middleware<br/>route middleware"]
  node_error_middleware["Error handler<br/>error middleware"]
end

subgraph group_application["Application core"]
  node_post_usecases["Post commands and queries<br/>post use cases<br/>[add.js]"]
  node_user_usecases["User workflows<br/>user use cases<br/>[add.js]"]
  node_login["Login workflow<br/>auth use case<br/>[login.js]"]
  node_entities["Domain entities<br/>core models<br/>[post.js]"]
  node_repository_ports["Repository ports<br/>application repositories"]
  node_auth_port["Auth service port<br/>application service<br/>[authService.js]"]
end

subgraph group_infrastructure["Infrastructure"]
  node_mongo_repository["Mongo repositories<br/>persistence adapter"]
  node_mongo_models["Mongo models<br/>Mongoose models<br/>[post.js]"]
  node_mongodb[("MongoDB connection<br/>durable database<br/>[connection.js]")]
  node_redis_repository["Redis post cache<br/>cache adapter"]
  node_redis[("Redis connection<br/>cache datastore<br/>[connection.js]")]
  node_auth_service["Auth service implementation<br/>auth infrastructure adapter<br/>[authService.js]"]
end

node_compose -->|"builds"| node_dockerfile
node_dockerfile -->|"runs"| node_app
node_app -->|"composes"| node_express
node_app -->|"starts"| node_server
node_app -->|"loads"| node_config
node_express -->|"mounts"| node_routes
node_routes -->|"protects routes"| node_auth_middleware
node_routes -->|"caches post requests"| node_cache_middleware
node_routes -->|"dispatches"| node_controllers
node_controllers -->|"invokes post operations"| node_post_usecases
node_controllers -->|"invokes user operations"| node_user_usecases
node_controllers -->|"invokes"| node_login
node_controllers -->|"forwards failures"| node_error_middleware
node_post_usecases -->|"operates on"| node_entities
node_user_usecases -->|"operates on"| node_entities
node_post_usecases -->|"uses"| node_repository_ports
node_user_usecases -->|"uses"| node_repository_ports
node_login -->|"uses"| node_auth_port
node_repository_ports -.->|"implemented by"| node_mongo_repository
node_repository_ports -.->|"implemented by"| node_redis_repository
node_mongo_repository -->|"persists with"| node_mongo_models
node_mongo_models -->|"uses"| node_mongodb
node_redis_repository -->|"uses"| node_redis
node_cache_middleware -->|"reads cache"| node_redis_repository
node_auth_port -.->|"implemented by"| node_auth_service

click node_compose "https://github.com/panagiop/node.js-clean-architecture/blob/master/docker-compose.yml"
click node_dockerfile "https://github.com/panagiop/node.js-clean-architecture/blob/master/Dockerfile"
click node_app "https://github.com/panagiop/node.js-clean-architecture/blob/master/app.js"
click node_express "https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/webserver/express.js"
click node_server "https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/webserver/server.js"
click node_routes "https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/webserver/routes/index.js"
click node_controllers "https://github.com/panagiop/node.js-clean-architecture/blob/master/adapters/controllers/postController.js"
click node_auth_middleware "https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/webserver/middlewares/authMiddleware.js"
click node_cache_middleware "https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/webserver/middlewares/redisCachingMiddleware.js"
click node_error_middleware "https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/webserver/middlewares/errorHandlingMiddleware.js"
click node_post_usecases "https://github.com/panagiop/node.js-clean-architecture/blob/master/application/use_cases/post/add.js"
click node_user_usecases "https://github.com/panagiop/node.js-clean-architecture/blob/master/application/use_cases/user/add.js"
click node_login "https://github.com/panagiop/node.js-clean-architecture/blob/master/application/use_cases/auth/login.js"
click node_entities "https://github.com/panagiop/node.js-clean-architecture/blob/master/src/entities/post.js"
click node_repository_ports "https://github.com/panagiop/node.js-clean-architecture/blob/master/application/repositories/postDbRepository.js"
click node_auth_port "https://github.com/panagiop/node.js-clean-architecture/blob/master/application/services/authService.js"
click node_mongo_repository "https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/database/mongoDB/repositories/postRepositoryMongoDB.js"
click node_mongo_models "https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/database/mongoDB/models/post.js"
click node_mongodb "https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/database/mongoDB/connection.js"
click node_redis_repository "https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/database/redis/postRepositoryRedis.js"
click node_redis "https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/database/redis/connection.js"
click node_auth_service "https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/services/authService.js"
click node_config "https://github.com/panagiop/node.js-clean-architecture/blob/master/config/config.js"

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_compose,node_dockerfile,node_app,node_config toneBlue
class node_express,node_server,node_routes,node_controllers,node_auth_middleware,node_cache_middleware,node_error_middleware toneAmber
class node_post_usecases,node_user_usecases,node_login,node_entities,node_repository_ports,node_auth_port toneMint
class node_mongo_repository,node_mongo_models,node_mongodb,node_redis_repository,node_redis,node_auth_service toneRose
```

## Components

### Runtime

- [Docker deployment](https://github.com/panagiop/node.js-clean-architecture/blob/master/docker-compose.yml): container deployment · Runs the API with database services. · `docker-compose.yml`
- [API image](https://github.com/panagiop/node.js-clean-architecture/blob/master/Dockerfile): Docker build · `Dockerfile`
- [Application bootstrap](https://github.com/panagiop/node.js-clean-architecture/blob/master/app.js): Node entrypoint · `app.js`
- [Runtime configuration](https://github.com/panagiop/node.js-clean-architecture/blob/master/config/config.js): configuration wiring · `config/config.js`

### HTTP boundary

- [Express setup](https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/webserver/express.js): web framework adapter · `frameworks/webserver/express.js`
- [HTTP server](https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/webserver/server.js): server runtime · `frameworks/webserver/server.js`
- [Resource routes](https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/webserver/routes/index.js): Express routes · Auth, user, and post route modules. · `frameworks/webserver/routes/index.js`
- [HTTP controllers](https://github.com/panagiop/node.js-clean-architecture/blob/master/adapters/controllers/postController.js): controller adapters · Post, user, and auth controllers translate HTTP requests. · `adapters/controllers/postController.js`
- [Auth middleware](https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/webserver/middlewares/authMiddleware.js): route middleware · `frameworks/webserver/middlewares/authMiddleware.js`
- [Redis cache middleware](https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/webserver/middlewares/redisCachingMiddleware.js): route middleware · `frameworks/webserver/middlewares/redisCachingMiddleware.js`
- [Error handler](https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/webserver/middlewares/errorHandlingMiddleware.js): error middleware · `frameworks/webserver/middlewares/errorHandlingMiddleware.js`

### Application core

- [Post commands and queries](https://github.com/panagiop/node.js-clean-architecture/blob/master/application/use_cases/post/add.js): post use cases · Add, update-by-id, and find-all operations. · `application/use_cases/post/add.js`
- [User workflows](https://github.com/panagiop/node.js-clean-architecture/blob/master/application/use_cases/user/add.js): user use cases · User creation and property lookup. · `application/use_cases/user/add.js`
- [Login workflow](https://github.com/panagiop/node.js-clean-architecture/blob/master/application/use_cases/auth/login.js): auth use case · `application/use_cases/auth/login.js`
- [Domain entities](https://github.com/panagiop/node.js-clean-architecture/blob/master/src/entities/post.js): core models · Framework-independent User and Post models. · `src/entities/post.js`
- [Repository ports](https://github.com/panagiop/node.js-clean-architecture/blob/master/application/repositories/postDbRepository.js): application repositories · Post DB, post cache, and user DB boundaries. · `application/repositories/postDbRepository.js`
- [Auth service port](https://github.com/panagiop/node.js-clean-architecture/blob/master/application/services/authService.js): application service · `application/services/authService.js`

### Infrastructure

- [Mongo repositories](https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/database/mongoDB/repositories/postRepositoryMongoDB.js): persistence adapter · Post persistence implementation. · `frameworks/database/mongoDB/repositories/postRepositoryMongoDB.js`
- [Mongo models](https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/database/mongoDB/models/post.js): Mongoose models · `frameworks/database/mongoDB/models/post.js`
- [MongoDB connection](https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/database/mongoDB/connection.js): durable database · `frameworks/database/mongoDB/connection.js`
- [Redis post cache](https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/database/redis/postRepositoryRedis.js): cache adapter · `frameworks/database/redis/postRepositoryRedis.js`
- [Redis connection](https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/database/redis/connection.js): cache datastore · `frameworks/database/redis/connection.js`
- [Auth service implementation](https://github.com/panagiop/node.js-clean-architecture/blob/master/frameworks/services/authService.js): auth infrastructure adapter · `frameworks/services/authService.js`

## Connections

- Docker deployment → API image: builds
- API image → Application bootstrap: runs
- Application bootstrap → Express setup: composes
- Application bootstrap → HTTP server: starts
- Application bootstrap → Runtime configuration: loads
- Express setup → Resource routes: mounts
- Resource routes → Auth middleware: protects routes
- Resource routes → Redis cache middleware: caches post requests
- Resource routes → HTTP controllers: dispatches
- HTTP controllers → Post commands and queries: invokes post operations
- HTTP controllers → User workflows: invokes user operations
- HTTP controllers → Login workflow: invokes
- HTTP controllers → Error handler: forwards failures
- Post commands and queries → Domain entities: operates on
- User workflows → Domain entities: operates on
- Post commands and queries → Repository ports: uses
- User workflows → Repository ports: uses
- Login workflow → Auth service port: uses
- Repository ports → Mongo repositories: implemented by
- Repository ports → Redis post cache: implemented by
- Mongo repositories → Mongo models: persists with
- Mongo models → MongoDB connection: uses
- Redis post cache → Redis connection: uses
- Redis cache middleware → Redis post cache: reads cache
- Auth service port → Auth service implementation: implemented by