# mr9asif/devpulse-assignment-2 architecture

> Architecture diagram of the GitHub repository mr9asif/devpulse-assignment-2, 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/mr9asif/devpulse-assignment-2
- Repository: https://github.com/mr9asif/devpulse-assignment-2

## Overview

1. **Overall shape**
   - This is a TypeScript REST API built on **Node.js + Express** with a clear layered structure: HTTP routing, request handling, domain/service logic, and PostgreSQL persistence.
   - The repo is organized by feature module rather than by technical layer, which makes the main boundaries easy to diagram.

2. **Runtime and deployment boundary**
   - `src/server.ts` is the entry point that starts the HTTP server.
   - `src/app.ts` appears to assemble the Express app, middleware, and module routes.
   - `vercel.json` and the README’s live URL indicate the API is deployed as a **Vercel-hosted serverless Express app**.

3. **Configuration boundary**
   - `src/config/index.ts` centralizes environment/runtime config such as the port, database URL, and JWT secret.
   - This keeps secrets and environment-specific settings out of the feature code and makes the app portable across local/dev/prod.

4. **Database subsystem**
   - `src/db/db.ts` is the database access boundary, wrapping the connection to **Neon Serverless PostgreSQL**.
   - The services likely depend on this module for all persistence operations, so the DB is not accessed directly from controllers or middleware.

5. **Authentication module**
   - `src/modules/auth/` contains `auth.routes.ts`, `auth.controller.ts`, and `auth.service.ts`.
   - This module handles **signup** and **login** flows:
     - registration stores user records,
     - login verifies credentials,
     - successful login returns a **JWT**.
   - The README shows the token is passed via a custom `token` request header rather than a standard `Authorization` header.

6. **Issue management module**
   - `src/modules/issues/` contains the issue API surface and business logic.
   - The controller/router/service split suggests:
     - routes define `/api/issues` endpoints,
     - controllers translate HTTP requests/responses,
     - services implement issue CRUD and status updates against the database.
   - The README indicates create/update/delete behavior, with role-sensitive rules around who can modify or remove issues.

7. **Authorization and request guards**
   - `src/modules/middleware/verifyJWT.ts` likely authenticates requests by validating the JWT and attaching identity to the request.
   - `src/modules/middleware/role.middleware.ts` and `isMaintainer.ts` enforce role-based access control.
   - `src/modules/middleware/auth.middleware.ts` likely acts as a general protection layer for authenticated routes.
   - This means authorization is enforced before controllers run, which is an important diagram boundary.

8. **User and role model**
   - `src/types/type.ts` and `src/types/express.d.ts` define shared TypeScript contracts for users, roles, and Express request augmentation.
   - These types support the auth/issue pipeline by allowing middleware to attach authenticated user data to the request object safely.

9. **Utility layer**
   - `src/util/jwt.ts` is the token helper boundary, likely responsible for signing and verifying JWTs.
   - `src/util/util.ts` likely contains shared helpers used across modules, such as response formatting or validation helpers.
   - Keeping token logic in utilities prevents duplication across auth and middleware code.

10. **Request flow from client to database**
   - Public requests hit the Express app, pass through global middleware, then enter the module router.
   - For protected endpoints, JWT verification and role checks run first.
   - Controllers then call services, and services use the DB module to read/write PostgreSQL.
   - Responses are returned in a consistent success/error shape, as shown in the README.

11. **Access-control boundaries**
   - The system separates:
     - **public auth routes** for signup/login,
     - **authenticated issue routes** for issue creation and viewing,
     - **role-gated routes** for update/delete.
   - The README’s contributor vs maintainer rules map directly to middleware-based enforcement in the issues module.

12. **Architectural diagram takeaway**
   - The cleanest diagram is: **client → Express app → module router → middleware guard → controller → service → PostgreSQL**.
   - Authentication forms a side flow that issues JWTs and later feeds authorization middleware for protected issue operations.

Main entry points: [`src/app.ts`](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/app.ts) (Express App), [`src/modules/issues/issues.router.ts`](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/issues/issues.router.ts) (Issue Routes), [`src/modules/auth/auth.service.ts`](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/auth/auth.service.ts) (Auth Service), [`src/modules/auth/auth.controller.ts`](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/auth/auth.controller.ts) (Auth Controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_server(("Server<br/>entrypoint<br/>[server.ts]"))
  node_app["Express App<br/>app assembly<br/>[app.ts]"]
end

subgraph group_auth["Auth"]
  node_authroutes["Auth Routes<br/>router<br/>[auth.routes.ts]"]
  node_authcontroller["Auth Controller<br/>http handler<br/>[auth.controller.ts]"]
  node_authservice["Auth Service<br/>auth logic<br/>[auth.service.ts]"]
end

subgraph group_issues["Issues"]
  node_issueroutes["Issue Routes<br/>router<br/>[issues.router.ts]"]
  node_issuecontroller["Issue Controller<br/>http handler"]
  node_issueservice["Issue Service<br/>issue logic<br/>[issues.service.ts]"]
end

subgraph group_shared["Shared"]
  node_config["Config<br/>[index.ts]"]
  node_db[("Database<br/>postgres client<br/>[db.ts]")]
  node_jwt["JWT Utils<br/>token helpers<br/>[jwt.ts]"]
  node_util["Shared Utils<br/>helpers<br/>[util.ts]"]
  node_types["App Types<br/>shared contracts<br/>[type.ts]"]
  node_expressd["Express Augment<br/>declarations<br/>[express.d.ts]"]
  node_verifyjwt(("Verify JWT<br/>auth middleware<br/>[verifyJWT.ts]"))
  node_authmw(("Auth Guard<br/>middleware<br/>[auth.middleware.ts]"))
  node_rolemw(("Role Guard<br/>rbac middleware<br/>[role.middleware.ts]"))
  node_maintainer(("Maintainer Check<br/>rbac middleware<br/>[isMaintainer.ts]"))
end

node_server -->|"boot"| node_app
node_app -->|"reads"| node_config
node_app -->|"mounts"| node_authroutes
node_app -->|"mounts"| node_issueroutes
node_authroutes -->|"calls"| node_authcontroller
node_authcontroller -->|"uses"| node_authservice
node_authservice -->|"persists"| node_db
node_authservice -->|"issues token"| node_jwt
node_issueroutes -->|"protects"| node_authmw
node_issueroutes -->|"verifies"| node_verifyjwt
node_issueroutes -->|"gates"| node_rolemw
node_rolemw -->|"delegates"| node_maintainer
node_issueroutes -->|"calls"| node_issuecontroller
node_issuecontroller -->|"uses"| node_issueservice
node_issueservice -->|"persists"| node_db
node_verifyjwt -->|"validates"| node_jwt
node_verifyjwt -->|"attaches identity"| node_types
node_authcontroller -->|"uses"| node_types
node_issuecontroller -->|"uses"| node_types
node_app -->|"extends"| node_expressd
node_authservice -->|"uses"| node_util
node_issueservice -->|"uses"| node_util

click node_server "https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/server.ts"
click node_app "https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/app.ts"
click node_config "https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/config/index.ts"
click node_db "https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/db/db.ts"
click node_jwt "https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/util/jwt.ts"
click node_util "https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/util/util.ts"
click node_types "https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/types/type.ts"
click node_expressd "https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/types/express.d.ts"
click node_authroutes "https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/auth/auth.routes.ts"
click node_authcontroller "https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/auth/auth.controller.ts"
click node_authservice "https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/auth/auth.service.ts"
click node_issueroutes "https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/issues/issues.router.ts"
click node_issuecontroller "https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/issues/issues.controller.ts"
click node_issueservice "https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/issues/issues.service.ts"
click node_verifyjwt "https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/middleware/verifyJWT.ts"
click node_authmw "https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/middleware/auth.middleware.ts"
click node_rolemw "https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/middleware/role.middleware.ts"
click node_maintainer "https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/middleware/isMaintainer.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 toneBlue
class node_authroutes,node_authcontroller,node_authservice toneAmber
class node_issueroutes,node_issuecontroller,node_issueservice toneMint
class node_config,node_db,node_jwt,node_util,node_types,node_expressd,node_verifyjwt,node_authmw,node_rolemw,node_maintainer toneRose
```

## Components

### Runtime

Entry and app assembly

- [Server](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/server.ts): entrypoint · Starts HTTP server · `src/server.ts`
- [Express App](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/app.ts): app assembly · Builds middleware and routes · `src/app.ts`

### Auth

Signup and login flow

- [Auth Routes](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/auth/auth.routes.ts): router · Signup and login endpoints · `src/modules/auth/auth.routes.ts`
- [Auth Controller](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/auth/auth.controller.ts): http handler · Handles auth requests · `src/modules/auth/auth.controller.ts`
- [Auth Service](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/auth/auth.service.ts): auth logic · Registers users and verifies login · `src/modules/auth/auth.service.ts`

### Issues

Issue management flow

- [Issue Routes](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/issues/issues.router.ts): router · Issue API endpoints · `src/modules/issues/issues.router.ts`
- [Issue Controller](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/issues/issues.controller.ts): http handler · Handles issue requests · `src/modules/issues/issues.controller.ts`
- [Issue Service](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/issues/issues.service.ts): issue logic · CRUD and status updates · `src/modules/issues/issues.service.ts`

### Shared

Cross-cutting config, db, middleware, and types

- [Config](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/config/index.ts): runtime config · Env and runtime settings · `src/config/index.ts`
- [Database](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/db/db.ts): postgres client · Neon PostgreSQL access · `src/db/db.ts`
- [JWT Utils](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/util/jwt.ts): token helpers · Signs and verifies tokens · `src/util/jwt.ts`
- [Shared Utils](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/util/util.ts): helpers · Common helper functions · `src/util/util.ts`
- [App Types](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/types/type.ts): shared contracts · Domain and Express typings · `src/types/type.ts`
- [Express Augment](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/types/express.d.ts): declarations · Extends request typings · `src/types/express.d.ts`
- [Verify JWT](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/middleware/verifyJWT.ts): auth middleware · Authenticates requests · `src/modules/middleware/verifyJWT.ts`
- [Auth Guard](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/middleware/auth.middleware.ts): middleware · Protects authenticated routes · `src/modules/middleware/auth.middleware.ts`
- [Role Guard](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/middleware/role.middleware.ts): rbac middleware · Enforces role rules · `src/modules/middleware/role.middleware.ts`
- [Maintainer Check](https://github.com/mr9asif/devpulse-assignment-2/blob/main/src/modules/middleware/isMaintainer.ts): rbac middleware · Checks maintainer access · `src/modules/middleware/isMaintainer.ts`

## Connections

- Server → Express App: boot · Server starts the Express app
- Express App → Config: reads · App uses runtime config
- Express App → Auth Routes: mounts · Registers auth routes
- Express App → Issue Routes: mounts · Registers issue routes
- Auth Routes → Auth Controller: calls · Routes delegate to controller
- Auth Controller → Auth Service: uses · Controller invokes auth logic
- Auth Service → Database: persists · Writes and reads users
- Auth Service → JWT Utils: issues token · Creates login JWTs
- Issue Routes → Auth Guard: protects · Authenticated issue routes
- Issue Routes → Verify JWT: verifies · Validates bearer token
- Issue Routes → Role Guard: gates · Applies role checks
- Role Guard → Maintainer Check: delegates · Uses maintainer-specific guard
- Issue Routes → Issue Controller: calls · Routes delegate to controller
- Issue Controller → Issue Service: uses · Controller invokes issue logic
- Issue Service → Database: persists · Reads and writes issues
- Verify JWT → JWT Utils: validates · Verifies signed token
- Verify JWT → App Types: attaches identity · Uses request/user contracts
- Auth Controller → App Types: uses · Typed auth request and response shapes
- Issue Controller → App Types: uses · Typed issue request and response shapes
- Express App → Express Augment: extends · Loads request augmentation
- Auth Service → Shared Utils: uses · Shared helper functions
- Issue Service → Shared Utils: uses · Shared helper functions