# farhanasfar/subscription-management-api architecture

> Architecture diagram of the GitHub repository farhanasfar/subscription-management-api, 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/farhanasfar/subscription-management-api
- Repository: https://github.com/farhanasfar/subscription-management-api

## Overview

1. **Overall shape**
   - This is a **Node.js/Express REST API** backed by **MongoDB via Mongoose**.
   - The repository is organized in a classic layered style: **routes → controllers → models**, with shared **middlewares**, **utils**, and **docs** around that core.

2. **Application entry and bootstrapping**
   - `index.js` and `app.js` are the top-level runtime entry points.
   - The bootstrap path likely handles environment setup, Express initialization, middleware registration, route mounting, error handling, and server startup.
   - `db/index.js` is the database connection boundary to MongoDB.

3. **Request routing layer**
   - The `routes/` folder splits the API into four bounded areas:
     - `auth.routes.js`
     - `user.routes.js`
     - `subscription.routes.js`
     - `admin.routes.js`
   - This is the first architectural boundary after HTTP ingress: requests are classified by domain and forwarded to the relevant controller.

4. **Domain controllers**
   - `controllers/` contains the application logic for each area:
     - `auth.controller.js` handles signup/signin/signout and session/token behavior.
     - `user.controller.js` handles profile/account management and password changes.
     - `subscription.controller.js` handles creating, listing, and cancelling subscriptions.
     - `admin.controller.js` supports role-based admin operations.
   - Controllers are the main orchestration layer: they validate intent, call models, shape responses, and rely on shared error utilities.

5. **Data model layer**
   - `models/` contains the MongoDB schemas/entities:
     - `user.model.js`
     - `subscription.model.js`
     - `admin.model.js`
   - These are the persistence boundary for the system. The API’s state is stored in MongoDB, and business behavior is expressed through these Mongoose models.

6. **Authentication and authorization**
   - `middlewares/auth.middleware.js` is the security gate for protected routes.
   - The README indicates **JWT-based authentication** and **role-based access control (RBAC)**, so the auth middleware is the key boundary separating public endpoints from authenticated user/admin flows.
   - Password handling uses **bcrypt**; token issuance/validation uses **JWT**.

7. **Error and async handling**
   - `middlewares/error.middleware.js` centralizes error translation and HTTP responses.
   - `utils/asyncHandler.js` suggests controllers are wrapped to avoid repetitive try/catch logic and to route async failures into the global error middleware.
   - `utils/ApiError.js` and `utils/ApiResponse.js` define the repo’s standard error/response contracts, which is important for diagramming the API’s output shape.

8. **API documentation surface**
   - `docs/openapi.js` and the `docs/paths/` files define the OpenAPI/Swagger contract.
   - Documented endpoints mirror the route domains: auth, user, and subscription.
   - Swagger is a parallel contract layer, not runtime logic, but it matters because it describes the external API boundary and expected request/response structures.

9. **Testing boundary**
   - `tests/integration/` contains end-to-end style tests using **Jest + Supertest**.
   - `tests/setup.js` likely prepares the test database/app lifecycle.
   - The tests focus on API behavior across the HTTP boundary, especially auth and user flows, which makes them useful for validating route/controller/middleware integration.

10. **Deployment and runtime packaging**
   - `Dockerfile` and `docker-compose.yml` show the service is containerized for local and production-style deployment.
   - The README says it is deployed on **Render** and the Docker image is published to **Docker Hub**.
   - CI/CD is driven by GitHub Actions:
     - `build.yml` runs dependency installation and tests.
     - `deploy.yml` builds and pushes the image on `main`.

11. **External services and config**
   - The app depends on **MongoDB** as its primary datastore.
   - Runtime configuration is environment-driven via `.env`, including `PORT`, `MONGODB_URI`, `JWT_SECRET`, and optional `CLOUDINARY_URL`.
   - Cloudinary is only mentioned as optional for user profile images, so it is an auxiliary external integration rather than a core subsystem.

12. **Primary data flows**
   - **Public auth flow:** client → auth route → auth controller → user model/MongoDB → JWT response.
   - **Authenticated user flow:** client → auth middleware → user/subscription route → controller → model/MongoDB → standardized response.
   - **Admin flow:** client → auth middleware with role checks → admin route/controller → model/MongoDB.
   - **Failure flow:** any async/controller/model error → async handler/error middleware → standardized API error response.

13. **What to emphasize in an architecture diagram**
   - Show the API as a single Express service with four domain route groups.
   - Put MongoDB as the main persistence store behind Mongoose models.
   - Highlight auth middleware as the central guard for protected endpoints.
   - Show Swagger/OpenAPI as a documentation plane alongside the service.
   - Show Docker/GitHub Actions/Render as the delivery pipeline around the application, not inside the request path.

Main entry points: [`app.js`](https://github.com/farhanasfar/subscription-management-api/blob/main/app.js) (App setup), [`controllers/subscription.controller.js`](https://github.com/farhanasfar/subscription-management-api/blob/main/controllers/subscription.controller.js) (Sub controller), [`utils/asyncHandler.js`](https://github.com/farhanasfar/subscription-management-api/blob/main/utils/asyncHandler.js) (Async handler), [`controllers/auth.controller.js`](https://github.com/farhanasfar/subscription-management-api/blob/main/controllers/auth.controller.js) (Auth controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["API runtime"]
  node_index_js["Server entry<br/>bootstrap<br/>[index.js]"]
  node_app_js["App setup<br/>express app<br/>[app.js]"]
  node_db_index_js[("DB connect<br/>mongo connector<br/>[index.js]")]
end

subgraph group_domain["Domain layer"]
  node_auth_routes["Auth routes<br/>route module<br/>[auth.routes.js]"]
  node_user_routes["User routes<br/>route module<br/>[user.routes.js]"]
  node_subscription_routes["Sub routes<br/>route module"]
  node_admin_routes["Admin routes<br/>route module<br/>[admin.routes.js]"]
  node_auth_controller["Auth controller<br/>[auth.controller.js]"]
  node_user_controller["User controller<br/>[user.controller.js]"]
  node_subscription_controller["Sub controller"]
  node_admin_controller["Admin controller"]
  node_user_model[("User model<br/>mongoose model<br/>[user.model.js]")]
  node_subscription_model[("Subscription model<br/>mongoose model")]
  node_admin_model[("Admin model<br/>mongoose model<br/>[admin.model.js]")]
end

subgraph group_support["Support"]
  node_auth_middleware{{"Auth guard<br/>middleware<br/>[auth.middleware.js]"}}
  node_error_middleware{{"Error handler<br/>middleware"}}
  node_async_handler["Async handler<br/>[asyncHandler.js]"]
  node_api_error["API error<br/>contract<br/>[ApiError.js]"]
  node_api_response["API response<br/>contract<br/>[ApiResponse.js]"]
  node_openapi["OpenAPI<br/>docs entry<br/>[openapi.js]"]
end

subgraph group_delivery["Delivery"]
  node_tests_setup["Test setup<br/>test harness<br/>[setup.js]"]
  node_integration_tests["API tests<br/>integration tests<br/>[auth.test.js]"]
  node_dockerfile["Dockerfile<br/>container spec"]
  node_compose["Compose<br/>runtime spec<br/>[docker-compose.yml]"]
  node_build_workflow["Build CI<br/>workflow<br/>[build.yml]"]
  node_deploy_workflow["Deploy CI<br/>workflow<br/>[deploy.yml]"]
end

node_index_js -->|"starts"| node_app_js
node_app_js -->|"connects"| node_db_index_js
node_app_js -->|"mounts"| node_auth_routes
node_app_js -->|"mounts"| node_user_routes
node_app_js -->|"mounts"| node_subscription_routes
node_app_js -->|"mounts"| node_admin_routes
node_auth_routes -->|"protects"| node_auth_middleware
node_user_routes -->|"protects"| node_auth_middleware
node_subscription_routes -->|"protects"| node_auth_middleware
node_admin_routes -->|"protects"| node_auth_middleware
node_auth_routes -->|"delegates"| node_auth_controller
node_user_routes -->|"delegates"| node_user_controller
node_subscription_routes -->|"delegates"| node_subscription_controller
node_admin_routes -->|"delegates"| node_admin_controller
node_auth_controller -->|"reads/writes"| node_user_model
node_user_controller -->|"reads/writes"| node_user_model
node_subscription_controller -->|"reads/writes"| node_subscription_model
node_admin_controller -->|"reads/writes"| node_admin_model
node_subscription_controller -->|"reads/writes"| node_user_model
node_auth_controller -->|"wraps"| node_async_handler
node_user_controller -->|"wraps"| node_async_handler
node_subscription_controller -->|"wraps"| node_async_handler
node_admin_controller -->|"wraps"| node_async_handler
node_async_handler -->|"forwards"| node_error_middleware
node_error_middleware -->|"formats"| node_api_error
node_auth_controller -->|"formats"| node_api_response
node_user_controller -->|"formats"| node_api_response
node_subscription_controller -->|"formats"| node_api_response
node_admin_controller -->|"formats"| node_api_response
node_openapi -->|"documents"| node_auth_routes
node_openapi -->|"documents"| node_user_routes
node_openapi -->|"documents"| node_subscription_routes
node_tests_setup -->|"supports"| node_integration_tests
node_integration_tests -->|"exercises"| node_app_js
node_build_workflow -->|"runs"| node_integration_tests
node_deploy_workflow -->|"builds"| node_dockerfile
node_deploy_workflow -->|"orchestrates"| node_compose

click node_index_js "https://github.com/farhanasfar/subscription-management-api/blob/main/index.js"
click node_app_js "https://github.com/farhanasfar/subscription-management-api/blob/main/app.js"
click node_db_index_js "https://github.com/farhanasfar/subscription-management-api/blob/main/db/index.js"
click node_auth_routes "https://github.com/farhanasfar/subscription-management-api/blob/main/routes/auth.routes.js"
click node_user_routes "https://github.com/farhanasfar/subscription-management-api/blob/main/routes/user.routes.js"
click node_subscription_routes "https://github.com/farhanasfar/subscription-management-api/blob/main/routes/subscription.routes.js"
click node_admin_routes "https://github.com/farhanasfar/subscription-management-api/blob/main/routes/admin.routes.js"
click node_auth_controller "https://github.com/farhanasfar/subscription-management-api/blob/main/controllers/auth.controller.js"
click node_user_controller "https://github.com/farhanasfar/subscription-management-api/blob/main/controllers/user.controller.js"
click node_subscription_controller "https://github.com/farhanasfar/subscription-management-api/blob/main/controllers/subscription.controller.js"
click node_admin_controller "https://github.com/farhanasfar/subscription-management-api/blob/main/controllers/admin.controller.js"
click node_user_model "https://github.com/farhanasfar/subscription-management-api/blob/main/models/user.model.js"
click node_subscription_model "https://github.com/farhanasfar/subscription-management-api/blob/main/models/subscription.model.js"
click node_admin_model "https://github.com/farhanasfar/subscription-management-api/blob/main/models/admin.model.js"
click node_auth_middleware "https://github.com/farhanasfar/subscription-management-api/blob/main/middlewares/auth.middleware.js"
click node_error_middleware "https://github.com/farhanasfar/subscription-management-api/blob/main/middlewares/error.middleware.js"
click node_async_handler "https://github.com/farhanasfar/subscription-management-api/blob/main/utils/asyncHandler.js"
click node_api_error "https://github.com/farhanasfar/subscription-management-api/blob/main/utils/ApiError.js"
click node_api_response "https://github.com/farhanasfar/subscription-management-api/blob/main/utils/ApiResponse.js"
click node_openapi "https://github.com/farhanasfar/subscription-management-api/blob/main/docs/openapi.js"
click node_tests_setup "https://github.com/farhanasfar/subscription-management-api/blob/main/tests/setup.js"
click node_integration_tests "https://github.com/farhanasfar/subscription-management-api/blob/main/tests/integration/auth.test.js"
click node_dockerfile "https://github.com/farhanasfar/subscription-management-api/tree/main/Dockerfile"
click node_compose "https://github.com/farhanasfar/subscription-management-api/blob/main/docker-compose.yml"
click node_build_workflow "https://github.com/farhanasfar/subscription-management-api/blob/main/.github/workflows/build.yml"
click node_deploy_workflow "https://github.com/farhanasfar/subscription-management-api/blob/main/.github/workflows/deploy.yml"

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_index_js,node_app_js,node_db_index_js toneBlue
class node_auth_routes,node_user_routes,node_subscription_routes,node_admin_routes,node_auth_controller,node_user_controller,node_subscription_controller,node_admin_controller,node_user_model,node_subscription_model,node_admin_model toneAmber
class node_auth_middleware,node_error_middleware,node_async_handler,node_api_error,node_api_response,node_openapi toneMint
class node_tests_setup,node_integration_tests,node_dockerfile,node_compose,node_build_workflow,node_deploy_workflow toneRose
```

## Components

### API runtime

Express service bootstrap, request handling, and persistence

- [Server entry](https://github.com/farhanasfar/subscription-management-api/blob/main/index.js): bootstrap · Process entrypoint that starts the application · `index.js`
- [App setup](https://github.com/farhanasfar/subscription-management-api/blob/main/app.js): express app · Express application wiring, middleware, and route mounting · `app.js`
- [DB connect](https://github.com/farhanasfar/subscription-management-api/blob/main/db/index.js): mongo connector · MongoDB connection boundary · `db/index.js`

### Domain layer

Routes, controllers, and models for core API behaviors

- [Auth routes](https://github.com/farhanasfar/subscription-management-api/blob/main/routes/auth.routes.js): route module · HTTP routes for signup, signin, and signout · `routes/auth.routes.js`
- [User routes](https://github.com/farhanasfar/subscription-management-api/blob/main/routes/user.routes.js): route module · HTTP routes for profile and account actions · `routes/user.routes.js`
- [Sub routes](https://github.com/farhanasfar/subscription-management-api/blob/main/routes/subscription.routes.js): route module · HTTP routes for subscription lifecycle actions · `routes/subscription.routes.js`
- [Admin routes](https://github.com/farhanasfar/subscription-management-api/blob/main/routes/admin.routes.js): route module · HTTP routes for role-based admin operations · `routes/admin.routes.js`
- [Auth controller](https://github.com/farhanasfar/subscription-management-api/blob/main/controllers/auth.controller.js): controller · Authentication orchestration and token/session handling · `controllers/auth.controller.js`
- [User controller](https://github.com/farhanasfar/subscription-management-api/blob/main/controllers/user.controller.js): controller · Profile and account management logic · `controllers/user.controller.js`
- [Sub controller](https://github.com/farhanasfar/subscription-management-api/blob/main/controllers/subscription.controller.js): controller · Subscription creation, listing, and cancellation · `controllers/subscription.controller.js`
- [Admin controller](https://github.com/farhanasfar/subscription-management-api/blob/main/controllers/admin.controller.js): controller · Administrative operations and privileged workflows · `controllers/admin.controller.js`
- [User model](https://github.com/farhanasfar/subscription-management-api/blob/main/models/user.model.js): mongoose model · User schema and persistence behavior · `models/user.model.js`
- [Subscription model](https://github.com/farhanasfar/subscription-management-api/blob/main/models/subscription.model.js): mongoose model · Subscription schema and persistence behavior · `models/subscription.model.js`
- [Admin model](https://github.com/farhanasfar/subscription-management-api/blob/main/models/admin.model.js): mongoose model · Admin schema and persistence behavior · `models/admin.model.js`

### Support

Security, error handling, utilities, and docs

- [Auth guard](https://github.com/farhanasfar/subscription-management-api/blob/main/middlewares/auth.middleware.js): middleware · JWT authentication and role-based access control · `middlewares/auth.middleware.js`
- [Error handler](https://github.com/farhanasfar/subscription-management-api/blob/main/middlewares/error.middleware.js): middleware · Global HTTP error translation and response handling · `middlewares/error.middleware.js`
- [Async handler](https://github.com/farhanasfar/subscription-management-api/blob/main/utils/asyncHandler.js): utility · Wraps async controller logic and forwards failures · `utils/asyncHandler.js`
- [API error](https://github.com/farhanasfar/subscription-management-api/blob/main/utils/ApiError.js): contract · Standard application error shape · `utils/ApiError.js`
- [API response](https://github.com/farhanasfar/subscription-management-api/blob/main/utils/ApiResponse.js): contract · Standard success response shape · `utils/ApiResponse.js`
- [OpenAPI](https://github.com/farhanasfar/subscription-management-api/blob/main/docs/openapi.js): docs entry · Swagger/OpenAPI root contract · `docs/openapi.js`

### Delivery

Testing, containerization, and CI/CD

- [Test setup](https://github.com/farhanasfar/subscription-management-api/blob/main/tests/setup.js): test harness · Integration test lifecycle and environment setup · `tests/setup.js`
- [API tests](https://github.com/farhanasfar/subscription-management-api/blob/main/tests/integration/auth.test.js): integration tests · End-to-end HTTP tests for auth and user flows · `tests/integration/auth.test.js`
- [Dockerfile](https://github.com/farhanasfar/subscription-management-api/tree/main/Dockerfile): container spec · Image build definition · `Dockerfile`
- [Compose](https://github.com/farhanasfar/subscription-management-api/blob/main/docker-compose.yml): runtime spec · Local multi-service orchestration · `docker-compose.yml`
- [Build CI](https://github.com/farhanasfar/subscription-management-api/blob/main/.github/workflows/build.yml): workflow · GitHub Actions workflow for install and test · `.github/workflows/build.yml`
- [Deploy CI](https://github.com/farhanasfar/subscription-management-api/blob/main/.github/workflows/deploy.yml): workflow · GitHub Actions workflow for build and image publish · `.github/workflows/deploy.yml`

## Connections

- Server entry → App setup: starts · Server entry boots the Express app
- App setup → DB connect: connects · App initialization depends on MongoDB connection
- App setup → Auth routes: mounts · Express mounts the auth route group
- App setup → User routes: mounts · Express mounts the user route group
- App setup → Sub routes: mounts · Express mounts the subscription route group
- App setup → Admin routes: mounts · Express mounts the admin route group
- Auth routes → Auth guard: protects · Protected auth endpoints pass through security middleware
- User routes → Auth guard: protects · Protected user endpoints require JWT and roles
- Sub routes → Auth guard: protects · Subscription endpoints are gated by auth middleware
- Admin routes → Auth guard: protects · Admin endpoints are restricted by role checks
- Auth routes → Auth controller: delegates · Auth routes delegate request handling to controller logic
- User routes → User controller: delegates · User routes delegate request handling to controller logic
- Sub routes → Sub controller: delegates · Subscription routes delegate request handling to controller logic
- Admin routes → Admin controller: delegates · Admin routes delegate request handling to controller logic
- Auth controller → User model: reads/writes · Auth flow persists and looks up user records
- User controller → User model: reads/writes · User flow operates on user records
- Sub controller → Subscription model: reads/writes · Subscription flow operates on subscription records
- Admin controller → Admin model: reads/writes · Admin flow operates on admin records
- Sub controller → User model: reads/writes · Subscriptions are associated with users
- Auth controller → Async handler: wraps · Async controller actions are funneled through the helper
- User controller → Async handler: wraps · Async controller actions are funneled through the helper
- Sub controller → Async handler: wraps · Async controller actions are funneled through the helper
- Admin controller → Async handler: wraps · Async controller actions are funneled through the helper
- Async handler → Error handler: forwards · Unhandled async failures reach the global error middleware
- Error handler → API error: formats · Errors are normalized into the standard error contract
- Auth controller → API response: formats · Successful auth responses use the standard response contract
- User controller → API response: formats · Successful user responses use the standard response contract
- Sub controller → API response: formats · Successful subscription responses use the standard response contract
- Admin controller → API response: formats · Successful admin responses use the standard response contract
- OpenAPI → Auth routes: documents · OpenAPI documents the auth API surface
- OpenAPI → User routes: documents · OpenAPI documents the user API surface
- OpenAPI → Sub routes: documents · OpenAPI documents the subscription API surface
- Test setup → API tests: supports · Shared setup prepares integration test execution
- API tests → App setup: exercises · Integration tests drive the HTTP app boundary
- Build CI → API tests: runs · CI workflow installs dependencies and executes tests
- Deploy CI → Dockerfile: builds · Deploy workflow builds the container image
- Deploy CI → Compose: orchestrates · Deployment packaging is defined for containerized runtime