# elhajjame/subledger-api architecture

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

- Interactive diagram: https://gitdiagram.com/elhajjame/subledger-api
- Repository: https://github.com/elhajjame/subledger-api

## Overview

1. **What this repo is**
   - This is a **Node.js/Express REST API** for subscription management, backed by **MongoDB via Mongoose**.
   - The architecture is a classic layered API: **HTTP routes → controllers → models → database**, with authentication/authorization enforced in middleware.

2. **Runtime entrypoints**
   - `server.js` is the likely process bootstrapper: it starts the HTTP server and connects to the configured runtime environment.
   - `app.js` is the Express application composition layer: middleware, route registration, and app-wide setup live here.

3. **Request routing boundary**
   - `routes/userRoutes.js`, `routes/subscriptionRoutes.js`, and the auth-related route wiring in the app split the API into functional areas.
   - Routes are the main API boundary: they decide which controller handles each request and where auth/validation middleware is applied.

4. **Controller layer**
   - `controllers/authController.js` handles authentication concerns such as sign-up and login.
   - `controllers/subscriptionController.js` handles CRUD for subscriptions.
   - `controllers/userController.js` covers user-related API behavior beyond auth itself.
   - Controllers appear to own request/response handling and delegate persistence to models.

5. **Data model layer**
   - `models/User.js` and `models/Subscription.js` define the persisted domain objects.
   - The data model is centered on two core entities:
     - **User**: identity, credentials, and role
     - **Subscription**: subscription metadata plus ownership through `userId`

6. **Authentication flow**
   - A user registers or logs in through auth endpoints.
   - Passwords are hashed with **bcrypt**.
   - Successful login issues a **JWT**, which becomes the access token used on protected routes.
   - This creates a clear split between **public auth routes** and **token-protected application routes**.

7. **Authorization flow**
   - `middlewares/roleMiddleware.js` enforces role-based access control.
   - The repo supports at least two roles, **User** and **Admin**.
   - Middleware sits between the route and controller layers, so authorization decisions are made before business logic runs.

8. **Subscription domain flow**
   - Authenticated users can create, read, update, and delete subscriptions.
   - Subscription records include `name`, `price`, `billingCycle`, timestamps, and a `userId` link back to the owner.
   - That `userId` boundary is important: it scopes data access per user and prevents subscriptions from being treated as global records.

9. **Validation boundary**
   - The project uses **express-validator** to enforce input rules at the API edge.
   - Validation is applied before controller logic, covering fields like email, password, subscription name, price, and billing cycle.
   - This keeps malformed requests from reaching the persistence layer.

10. **Persistence and infrastructure**
    - **MongoDB** is the primary datastore, accessed through **Mongoose** models.
    - `config.env` likely stores runtime configuration such as database connection settings, JWT secret, and server port.
    - `Dockerfile` and `compose.yaml` indicate the API is container-friendly and can be run with a containerized app/database setup.

11. **Testing structure**
    - `tests/integration/` contains end-to-end API tests for login, signup, and subscriptions.
    - `tests/setup/setup.js` provides test initialization and shared setup/teardown behavior.
    - This suggests the repo validates the full request path: routing, middleware, controllers, and persistence.

12. **Operational artifacts**
    - `coverage/` contains generated test coverage output and is not part of runtime architecture.
    - `jest.config.cjs` shows the project uses **Jest** for test execution.

13. **How to draw the architecture**
    - A good diagram should show:
      - External client → Express app
      - Express routes → auth/user/subscription controllers
      - Controllers → Mongoose models → MongoDB
      - Route middleware in front of controllers for JWT auth and role checks
      - Validation at the route boundary
      - Separate auth flow from subscription management flow

Main entry points: [`app.js`](https://github.com/elhajjame/subledger-api/blob/main/app.js) (Express App), [`routes/subscriptionRoutes.js`](https://github.com/elhajjame/subledger-api/blob/main/routes/subscriptionRoutes.js) (Subscription Routes), [`server.js`](https://github.com/elhajjame/subledger-api/blob/main/server.js) (Server), [`models/User.js`](https://github.com/elhajjame/subledger-api/blob/main/models/User.js) (User Model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["Runtime/API"]
  node_node_client(("API Client<br/>external client"))
  node_node_server["Server<br/>bootstrap<br/>[server.js]"]
  node_node_app["Express App<br/>app composition<br/>[app.js]"]
  node_node_auth_routes["Auth Routes<br/>route module<br/>[userRoutes.js]"]
  node_node_user_routes["User Routes<br/>route module<br/>[userRoutes.js]"]
  node_node_subscription_routes["Subscription Routes<br/>route module"]
  node_node_auth_controller["Auth Controller<br/>[authController.js]"]
  node_node_user_controller["User Controller<br/>[userController.js]"]
  node_node_subscription_controller["Subscription Controller"]
  node_node_role_mw{{"Role Middleware<br/>authorization middleware<br/>[roleMiddleware.js]"}}
end

subgraph group_group_domain["Domain/Data"]
  node_node_user_model[("User Model<br/>mongoose model<br/>[User.js]")]
  node_node_subscription_model[("Subscription Model<br/>mongoose model<br/>[Subscription.js]")]
  node_node_mongo[("MongoDB<br/>datastore")]
end

subgraph group_group_tests["Tests"]
  node_node_tests["Integration Tests<br/>jest integration"]
  node_node_setup["Test Setup<br/>test harness<br/>[setup.js]"]
end

subgraph group_group_ops["Ops"]
  node_node_compose["Compose<br/>container orchestration<br/>[compose.yaml]"]
  node_node_dockerfile["Dockerfile<br/>container build"]
end

node_node_client -->|"HTTP requests"| node_node_app
node_node_server -->|"starts"| node_node_app
node_node_app -->|"mounts"| node_node_auth_routes
node_node_app -->|"mounts"| node_node_user_routes
node_node_app -->|"mounts"| node_node_subscription_routes
node_node_auth_routes -->|"dispatches to"| node_node_auth_controller
node_node_user_routes -->|"dispatches to"| node_node_user_controller
node_node_subscription_routes -->|"protects with"| node_node_role_mw
node_node_subscription_routes -->|"dispatches to"| node_node_subscription_controller
node_node_auth_controller -->|"uses"| node_node_user_model
node_node_user_controller -->|"uses"| node_node_user_model
node_node_subscription_controller -->|"uses"| node_node_subscription_model
node_node_user_model -->|"persists to"| node_node_mongo
node_node_subscription_model -->|"persists to"| node_node_mongo
node_node_setup -->|"prepares"| node_node_tests
node_node_tests -->|"exercises"| node_node_app
node_node_compose -.->|"runs"| node_node_server
node_node_compose -.->|"provisions"| node_node_mongo
node_node_dockerfile -.->|"packages"| node_node_server

click node_node_server "https://github.com/elhajjame/subledger-api/blob/main/server.js"
click node_node_app "https://github.com/elhajjame/subledger-api/blob/main/app.js"
click node_node_auth_routes "https://github.com/elhajjame/subledger-api/blob/main/routes/userRoutes.js"
click node_node_user_routes "https://github.com/elhajjame/subledger-api/blob/main/routes/userRoutes.js"
click node_node_subscription_routes "https://github.com/elhajjame/subledger-api/blob/main/routes/subscriptionRoutes.js"
click node_node_auth_controller "https://github.com/elhajjame/subledger-api/blob/main/controllers/authController.js"
click node_node_user_controller "https://github.com/elhajjame/subledger-api/blob/main/controllers/userController.js"
click node_node_subscription_controller "https://github.com/elhajjame/subledger-api/blob/main/controllers/subscriptionController.js"
click node_node_role_mw "https://github.com/elhajjame/subledger-api/blob/main/middlewares/roleMiddleware.js"
click node_node_user_model "https://github.com/elhajjame/subledger-api/blob/main/models/User.js"
click node_node_subscription_model "https://github.com/elhajjame/subledger-api/blob/main/models/Subscription.js"
click node_node_tests "https://github.com/elhajjame/subledger-api/tree/main/tests/integration"
click node_node_setup "https://github.com/elhajjame/subledger-api/blob/main/tests/setup/setup.js"
click node_node_compose "https://github.com/elhajjame/subledger-api/blob/main/compose.yaml"
click node_node_dockerfile "https://github.com/elhajjame/subledger-api/tree/main/Dockerfile"

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_node_client,node_node_server,node_node_app,node_node_auth_routes,node_node_user_routes,node_node_subscription_routes,node_node_auth_controller,node_node_user_controller,node_node_subscription_controller,node_node_role_mw toneBlue
class node_node_user_model,node_node_subscription_model,node_node_mongo toneAmber
class node_node_tests,node_node_setup toneMint
class node_node_compose,node_node_dockerfile toneRose
```

## Components

### Runtime/API

HTTP application bootstrap, routing, controllers, and request middleware.

- **API Client**: external client · Any HTTP consumer of the REST API.
- [Server](https://github.com/elhajjame/subledger-api/blob/main/server.js): bootstrap · Process entrypoint that starts the app. · `server.js`
- [Express App](https://github.com/elhajjame/subledger-api/blob/main/app.js): app composition · Express middleware and route wiring. · `app.js`
- [Auth Routes](https://github.com/elhajjame/subledger-api/blob/main/routes/userRoutes.js): route module · Authentication-related request boundary. · `routes/userRoutes.js`
- [User Routes](https://github.com/elhajjame/subledger-api/blob/main/routes/userRoutes.js): route module · User-focused API boundary. · `routes/userRoutes.js`
- [Subscription Routes](https://github.com/elhajjame/subledger-api/blob/main/routes/subscriptionRoutes.js): route module · Subscription CRUD request boundary. · `routes/subscriptionRoutes.js`
- [Auth Controller](https://github.com/elhajjame/subledger-api/blob/main/controllers/authController.js): controller · Handles signup, login, and token issuance. · `controllers/authController.js`
- [User Controller](https://github.com/elhajjame/subledger-api/blob/main/controllers/userController.js): controller · Handles user API behavior. · `controllers/userController.js`
- [Subscription Controller](https://github.com/elhajjame/subledger-api/blob/main/controllers/subscriptionController.js): controller · Handles subscription CRUD operations. · `controllers/subscriptionController.js`
- [Role Middleware](https://github.com/elhajjame/subledger-api/blob/main/middlewares/roleMiddleware.js): authorization middleware · Enforces role-based access control. · `middlewares/roleMiddleware.js`

### Domain/Data

Core persistence models and datastore boundary.

- [User Model](https://github.com/elhajjame/subledger-api/blob/main/models/User.js): mongoose model · User identity, credentials, and role schema. · `models/User.js`
- [Subscription Model](https://github.com/elhajjame/subledger-api/blob/main/models/Subscription.js): mongoose model · Subscription schema with owner linkage. · `models/Subscription.js`
- **MongoDB**: datastore · Persistent document database.

### Tests

Integration test harness and end-to-end API coverage.

- [Integration Tests](https://github.com/elhajjame/subledger-api/tree/main/tests/integration): jest integration · End-to-end API tests for auth and subscriptions. · `tests/integration`
- [Test Setup](https://github.com/elhajjame/subledger-api/blob/main/tests/setup/setup.js): test harness · Shared test initialization and teardown. · `tests/setup/setup.js`

### Ops

Container and runtime configuration artifacts.

- [Compose](https://github.com/elhajjame/subledger-api/blob/main/compose.yaml): container orchestration · Containerized app/database runtime definition. · `compose.yaml`
- [Dockerfile](https://github.com/elhajjame/subledger-api/tree/main/Dockerfile): container build · Container image build definition. · `Dockerfile`

## Connections

- API Client → Express App: HTTP requests · Clients call the Express application.
- Server → Express App: starts · Server bootstraps the Express app.
- Express App → Auth Routes: mounts · Registers auth-related routes.
- Express App → User Routes: mounts · Registers user routes.
- Express App → Subscription Routes: mounts · Registers subscription routes.
- Auth Routes → Auth Controller: dispatches to · Auth routes delegate to controller handlers.
- User Routes → User Controller: dispatches to · User routes delegate to controller handlers.
- Subscription Routes → Role Middleware: protects with · Role checks are applied before protected handlers.
- Subscription Routes → Subscription Controller: dispatches to · Subscription routes delegate to controller handlers.
- Auth Controller → User Model: uses · Auth flow reads and creates users.
- User Controller → User Model: uses · User API operates on user records.
- Subscription Controller → Subscription Model: uses · Subscription API operates on subscription records.
- User Model → MongoDB: persists to · User documents are stored in MongoDB.
- Subscription Model → MongoDB: persists to · Subscription documents are stored in MongoDB.
- Test Setup → Integration Tests: prepares · Shared setup supports integration tests.
- Integration Tests → Express App: exercises · Integration tests drive the HTTP application path.
- Compose → Server: runs · Compose can start the API container.
- Compose → MongoDB: provisions · Compose defines the database runtime.
- Dockerfile → Server: packages · Docker image contains the API process.