How panagiop/node.js-clean-architecture works
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: postController.js HTTP controllers · app.js Application bootstrap · index.js Resource routes · postDbRepository.js Repository ports
Components 23
Runtime
- Docker deployment · Runs the API with database services.
docker-compose.yml - API image
Dockerfile - Application bootstrap
app.js - Runtime configuration
config/config.js
HTTP boundary
- Express setup
frameworks/webserver/express.js - HTTP server
frameworks/webserver/server.js - Resource routes · Auth, user, and post route modules.
frameworks/webserver/routes/index.js - HTTP controllers · Post, user, and auth controllers translate HTTP requests.
adapters/controllers/postController.js - Auth middleware
frameworks/webserver/middlewares/authMiddleware.js - Redis cache middleware
frameworks/webserver/middlewares/redisCachingMiddleware.js - Error handler
frameworks/webserver/middlewares/errorHandlingMiddleware.js
Application core
- Post commands and queries · Add, update-by-id, and find-all operations.
application/use_cases/post/add.js - User workflows · User creation and property lookup.
application/use_cases/user/add.js - Login workflow
application/use_cases/auth/login.js - Domain entities · Framework-independent User and Post models.
src/entities/post.js - Repository ports · Post DB, post cache, and user DB boundaries.
application/repositories/postDbRepository.js - Auth service port
application/services/authService.js
Infrastructure
- Mongo repositories · Post persistence implementation.
frameworks/database/mongoDB/repositories/postRepositoryMongoDB.js - Mongo models
frameworks/database/mongoDB/models/post.js - MongoDB connection
frameworks/database/mongoDB/connection.js - Redis post cache
frameworks/database/redis/postRepositoryRedis.js - Redis connection
frameworks/database/redis/connection.js - Auth service implementation
frameworks/services/authService.js
Connections 25
- 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