# the-pujon/express-starterx architecture

> Architecture diagram of the GitHub repository the-pujon/express-starterx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/the-pujon/express-starterx
- Repository: https://github.com/the-pujon/express-starterx

## Overview

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.

Main entry points: [`src/app/modules/Auth/application/services/registration.service.ts`](https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/Auth/application/services/registration.service.ts) (Auth Use Cases), [`src/app/modules/Auth/infrastructure/persistence/repositories/mongo-user.repository.ts`](https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/Auth/infrastructure/persistence/repositories/mongo-user.repository.ts) (Auth Infra), [`src/app.ts`](https://github.com/the-pujon/express-starterx/blob/master/src/app.ts) (Express App), [`src/app/routes/index.ts`](https://github.com/the-pujon/express-starterx/blob/master/src/app/routes/index.ts) (Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap"]
  node_server["Server<br/>bootstrap<br/>[server.ts]"]
  node_app["Express App<br/>bootstrap<br/>[app.ts]"]
  node_routes["Routes<br/>composition<br/>[index.ts]"]
end

subgraph group_auth["Auth"]
  node_auth_presentation["Auth API<br/>presentation<br/>[auth.route.ts]"]
  node_auth_application["Auth Use Cases"]
  node_auth_domain["Auth Domain<br/>[user.model.ts]"]
  node_auth_infra[("Auth Infra<br/>persistence")]
end

subgraph group_user["User"]
  node_user_presentation["User API<br/>presentation<br/>[user.route.ts]"]
  node_user_application["User Use Cases"]
  node_user_domain["User Domain"]
  node_user_infra[("User Infra<br/>persistence")]
end

subgraph group_activity["Activity Log"]
  node_activity_service["Log Service"]
  node_activity_domain["Log Domain"]
  node_activity_infra[("Log Repo<br/>persistence")]
end

subgraph group_shared["Shared"]
  node_event_bus(("Event Bus<br/>events<br/>[event-emitter.ts]"))
  node_activity_listener["Log Listener"]
  node_middleware["Middleware<br/>cross-cutting"]
  node_utils["Utilities<br/>cross-cutting<br/>[sendEmail.ts]"]
end

subgraph group_external["External"]
  node_mongo[("MongoDB<br/>external datastore")]
  node_redis[("Redis<br/>external cache")]
  node_email["Email Service<br/>external service"]
  node_google_oauth{{"Google OAuth<br/>external service"}}
end

node_server -->|"boots"| node_app
node_app -->|"mounts"| node_routes
node_app -->|"uses"| node_middleware
node_routes -->|"auth"| node_auth_presentation
node_routes -->|"user"| node_user_presentation
node_auth_presentation -->|"calls"| node_auth_application
node_auth_application -->|"depends on"| node_auth_domain
node_auth_application -->|"persists via"| node_auth_infra
node_auth_infra -->|"stores"| node_mongo
node_auth_infra -->|"sessions"| node_redis
node_auth_infra -->|"oauth"| node_google_oauth
node_auth_application -->|"emails"| node_utils
node_user_presentation -->|"calls"| node_user_application
node_user_application -->|"depends on"| node_user_domain
node_user_application -->|"persists via"| node_user_infra
node_user_infra -->|"stores"| node_mongo
node_event_bus -->|"publishes"| node_activity_listener
node_activity_listener -->|"handles"| node_activity_service
node_activity_service -->|"depends on"| node_activity_domain
node_activity_service -->|"persists via"| node_activity_infra
node_activity_infra -->|"stores"| node_mongo
node_middleware -.->|"observes"| node_event_bus
node_utils -->|"sends"| node_email

click node_server "https://github.com/the-pujon/express-starterx/blob/master/src/server.ts"
click node_app "https://github.com/the-pujon/express-starterx/blob/master/src/app.ts"
click node_routes "https://github.com/the-pujon/express-starterx/blob/master/src/app/routes/index.ts"
click node_auth_presentation "https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/Auth/presentation/routes/auth.route.ts"
click node_auth_application "https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/Auth/application/services/registration.service.ts"
click node_auth_domain "https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/Auth/domain/models/user.model.ts"
click node_auth_infra "https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/Auth/infrastructure/persistence/repositories/mongo-user.repository.ts"
click node_user_presentation "https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/User/presentation/routes/user.route.ts"
click node_user_application "https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/User/application/services/user-profile.service.ts"
click node_user_domain "https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/User/domain/models/user-profile.model.ts"
click node_user_infra "https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/User/infrastructure/repositories/mongo-user-profile.repository.ts"
click node_activity_service "https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/ActivityLog/application/services/activity-log.service.ts"
click node_activity_domain "https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/ActivityLog/domain/models/activity-log.model.ts"
click node_activity_infra "https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/ActivityLog/infrastructure/repositories/mongo-activity-log.repository.ts"
click node_event_bus "https://github.com/the-pujon/express-starterx/blob/master/src/app/shared/events/event-emitter.ts"
click node_activity_listener "https://github.com/the-pujon/express-starterx/blob/master/src/app/shared/events/activity-log.listener.ts"
click node_middleware "https://github.com/the-pujon/express-starterx/blob/master/src/app/middlewares/globalErrorhandler.ts"
click node_utils "https://github.com/the-pujon/express-starterx/blob/master/src/app/utils/sendEmail.ts"
click node_email "https://github.com/the-pujon/express-starterx/blob/master/templates/verification-email.html"
click node_google_oauth "https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/Auth/infrastructure/adapters/google-oauth.adapter.ts"

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_server,node_app,node_routes toneBlue
class node_auth_presentation,node_auth_application,node_auth_domain,node_auth_infra toneAmber
class node_user_presentation,node_user_application,node_user_domain,node_user_infra toneMint
class node_activity_service,node_activity_domain,node_activity_infra toneRose
class node_event_bus,node_activity_listener,node_middleware,node_utils toneIndigo
class node_mongo,node_redis,node_email,node_google_oauth toneTeal
```

## Components

### Bootstrap

Process entrypoint and app assembly

- [Server](https://github.com/the-pujon/express-starterx/blob/master/src/server.ts): bootstrap · Starts the HTTP listener · `src/server.ts`
- [Express App](https://github.com/the-pujon/express-starterx/blob/master/src/app.ts): bootstrap · Assembles middleware and application wiring · `src/app.ts`
- [Routes](https://github.com/the-pujon/express-starterx/blob/master/src/app/routes/index.ts): composition · Registers module route trees · `src/app/routes/index.ts`

### Auth

Authentication and account flows

- [Auth API](https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/Auth/presentation/routes/auth.route.ts): presentation · Auth routes, controllers, and request validation · `src/app/modules/Auth/presentation/routes/auth.route.ts`
- [Auth Use Cases](https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/Auth/application/services/registration.service.ts): application · Registration, login, token, verification, and reset flows · `src/app/modules/Auth/application/services/registration.service.ts`
- [Auth Domain](https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/Auth/domain/models/user.model.ts): domain · Auth entities, contracts, and rules · `src/app/modules/Auth/domain/models/user.model.ts`
- [Auth Infra](https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/Auth/infrastructure/persistence/repositories/mongo-user.repository.ts): persistence · Mongo, Redis, and OAuth adapters for auth · `src/app/modules/Auth/infrastructure/persistence/repositories/mongo-user.repository.ts`

### User

User profile and management flows

- [User API](https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/User/presentation/routes/user.route.ts): presentation · User routes and controllers · `src/app/modules/User/presentation/routes/user.route.ts`
- [User Use Cases](https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/User/application/services/user-profile.service.ts): application · Profile and user management services · `src/app/modules/User/application/services/user-profile.service.ts`
- [User Domain](https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/User/domain/models/user-profile.model.ts): domain · User profile entities and repository contracts · `src/app/modules/User/domain/models/user-profile.model.ts`
- [User Infra](https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/User/infrastructure/repositories/mongo-user-profile.repository.ts): persistence · Mongo-backed user profile repository · `src/app/modules/User/infrastructure/repositories/mongo-user-profile.repository.ts`

### Activity Log

Audit/event-driven logging

- [Log Service](https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/ActivityLog/application/services/activity-log.service.ts): application · Builds activity log records from events · `src/app/modules/ActivityLog/application/services/activity-log.service.ts`
- [Log Domain](https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/ActivityLog/domain/models/activity-log.model.ts): domain · Activity log entity and repository contract · `src/app/modules/ActivityLog/domain/models/activity-log.model.ts`
- [Log Repo](https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/ActivityLog/infrastructure/repositories/mongo-activity-log.repository.ts): persistence · Mongo repository for audit logs · `src/app/modules/ActivityLog/infrastructure/repositories/mongo-activity-log.repository.ts`

### Shared

Cross-cutting middleware, events, and utilities

- [Event Bus](https://github.com/the-pujon/express-starterx/blob/master/src/app/shared/events/event-emitter.ts): events · Shared domain/application event emitter · `src/app/shared/events/event-emitter.ts`
- [Log Listener](https://github.com/the-pujon/express-starterx/blob/master/src/app/shared/events/activity-log.listener.ts): listener · Consumes events and persists activity records · `src/app/shared/events/activity-log.listener.ts`
- [Middleware](https://github.com/the-pujon/express-starterx/blob/master/src/app/middlewares/globalErrorhandler.ts): cross-cutting · Auth, validation, and error-handling middleware · `src/app/middlewares/globalErrorhandler.ts`
- [Utilities](https://github.com/the-pujon/express-starterx/blob/master/src/app/utils/sendEmail.ts): cross-cutting · Async wrapping, email, Redis, and response helpers · `src/app/utils/sendEmail.ts`

### External

Datastores and third-party services

- **MongoDB**: external datastore · Primary document database
- **Redis**: external cache · Short-lived auth/session storage
- [Email Service](https://github.com/the-pujon/express-starterx/blob/master/templates/verification-email.html): external service · Outbound email delivery and templates · `templates/verification-email.html`
- [Google OAuth](https://github.com/the-pujon/express-starterx/blob/master/src/app/modules/Auth/infrastructure/adapters/google-oauth.adapter.ts): external service · Third-party auth integration · `src/app/modules/Auth/infrastructure/adapters/google-oauth.adapter.ts`

## Connections

- Server → Express App: boots · Starts the Express application
- Express App → Routes: mounts · Registers the route tree and middleware stack
- Express App → Middleware: uses · Applies shared request and error middleware
- Routes → Auth API: auth · Mounts the auth HTTP boundary
- Routes → User API: user · Mounts the user HTTP boundary
- Auth API → Auth Use Cases: calls · Delegates HTTP requests to use cases
- Auth Use Cases → Auth Domain: depends on · Uses domain contracts and entities
- Auth Use Cases → Auth Infra: persists via · Relies on repository implementations and adapters
- Auth Infra → MongoDB: stores · Uses MongoDB for durable auth data
- Auth Infra → Redis: sessions · Stores auth sessions and short-lived state
- Auth Infra → Google OAuth: oauth · Bridges external Google authentication
- Auth Use Cases → Utilities: emails · Uses helpers for messaging and async flow
- User API → User Use Cases: calls · Delegates user requests to use cases
- User Use Cases → User Domain: depends on · Uses user profile entities and interfaces
- User Use Cases → User Infra: persists via · Relies on user profile repository implementations
- User Infra → MongoDB: stores · Persists user profile data in MongoDB
- Event Bus → Log Listener: publishes · Emits domain events to the audit listener
- Log Listener → Log Service: handles · Transforms events into log writes
- Log Service → Log Domain: depends on · Uses activity log contracts and model
- Log Service → Log Repo: persists via · Stores logs through the repository
- Log Repo → MongoDB: stores · Persists audit records in MongoDB
- Middleware → Event Bus: observes · Supports request flows that can emit events
- Utilities → Email Service: sends · Delivers verification and reset emails