the-pujon/express-starterx

1. This repository is a TypeScript Node.js/Express REST API starter built around Clean Architecture. The entrypoint is split between src/server.ts and src/app.ts, with app.ts assembling Express middleware and server.ts starting the HTTP listener.

2. The application is organized into feature modules under src/app/modules/, primarily Auth, User, and ActivityLog. Each module is divided into presentation, application, domain, and infrastructure, so HTTP handling, business use cases, domain models, and technical persistence are kept separate.

3. The HTTP boundary lives in the presentation layer. Routes such as auth.route.ts and user.route.ts wire controllers, request validation, and middleware together. Controllers are thin and delegate to application services rather than talking directly to the database.

4. The application layer contains the use-case services that coordinate business flow. In Auth, this includes registration, authentication, token handling, email verification, and password reset services. In User, services cover profile and user management operations. These services depend on repository interfaces, not concrete storage implementations.

5. The domain layer defines the core contracts and entities. It contains model classes like user.model.ts, auth-session.model.ts, and activity-log.model.ts, plus repository interfaces and domain-specific exceptions/config. This is where business rules are meant to live without Express, Mongo, Redis, or email details leaking in.

6. The infrastructure layer contains the concrete integrations. MongoDB is used through Mongoose schemas and repositories for users, histories, user profiles, and activity logs. Redis is used for auth session storage and other short-lived state. A Google OAuth adapter is present as an external auth integration.

7. There is a clear composition-root pattern in the route files: repositories and services are instantiated there and injected into controllers. That means dependency wiring happens at the edge, while the inner layers stay framework-agnostic and testable.

8. Cross-cutting concerns are handled in shared middleware and helpers under src/app/middlewares/, src/app/errors/, and src/app/utils/. This includes authentication middleware, request validation, global error handling, not-found handling, response formatting, email sending, Redis utilities, and async error wrapping.

9. The repo includes an event-driven side channel via src/app/shared/events/. Domain and application flows can emit events, and activity-log.listener.ts consumes them to persist audit/activity records. This creates a secondary path from core business actions to logging without hard-coupling logging into every service.

10. Email is part of the auth architecture. HTML templates in templates/ support verification, reset-password, and welcome emails, while utility code handles delivery. This makes outbound email a separate external dependency from the main request/response flow.

11. Configuration is centralized in src/app/config/ and environment files. The runtime expects MongoDB, Redis, JWT secrets, and optional email/cloud services. docker-compose.yml and the Dockerfile show that local infrastructure is meant to be brought up as companion services rather than embedded in the app.

12. Testing is split into unit tests and E2E tests under src/__tests__/. There are module-level tests for Auth services and an end-to-end auth test suite, which fits the architecture’s emphasis on testing isolated services and route flows separately.

13. The repository also includes developer tooling around the architecture: createModule.js for generating new module structure, ecosystem.config.js for process management, and ARCHITECTURE.md/readme.md for documentation. These support the modular pattern rather than defining runtime behavior.

14. For an architecture diagram, the main boundaries to show are: client requests into Express, route/controller entry points, application services, domain contracts/models, infrastructure adapters/repositories, and external systems such as MongoDB, Redis, email delivery, and Google OAuth. The activity-log event listener is best shown as an asynchronous offshoot from the core auth/user flows.