# zihad-1883/l2-a2-devpulse- architecture

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

- Interactive diagram: https://gitdiagram.com/zihad-1883/l2-a2-devpulse-
- Repository: https://github.com/zihad-1883/l2-a2-devpulse-

## Overview

1. **What this repo is**
   - DevPulse is a backend-only REST API for tracking bugs and feature requests.
   - The architecture is a classic layered Express service: route handlers, controllers, services, middleware, and a PostgreSQL data layer.

2. **Runtime and build boundary**
   - Source lives in `src/` as TypeScript and is compiled into `dist/` for deployment/execution.
   - `src/server.ts` is the process entry point, while `src/app.ts` builds the Express application.
   - `tsup` is the bundling/build tool, and `vercel.json` indicates the API is deployed in a serverless-friendly environment.

3. **HTTP surface**
   - The API is split into two main route groups:
     - `/api/auth` for signup/login
     - `/api/issues` for issue CRUD and filtering
   - The public/private boundary is enforced per route using middleware, not by separate services.

4. **Authentication subsystem**
   - `modules/auth` handles user registration and login.
   - Passwords are hashed with `bcrypt`.
   - Authentication uses JWTs with separate access and refresh secrets from environment config.
   - The README indicates refresh tokens are returned via an HTTP-only cookie, which makes the auth flow stateful at the browser edge but still JWT-based.

5. **Authorization and access control**
   - `middleware/auth.middleware.ts` is the security gate for protected endpoints.
   - It likely verifies the JWT, attaches the authenticated user to the request, and checks role permissions.
   - Roles are central to the design: `contributor` vs `maintainer`.
   - The permission model is important to diagram: contributors can create and update their own open issues; maintainers can update or delete any issue.

6. **Issue management subsystem**
   - `modules/issues` implements create/read/update/delete for issues.
   - GET `/api/issues` supports query-based filtering and sorting:
     - `type`: bug or feature_request
     - `status`: open, in_progress, resolved
     - `sort`: newest or oldest
   - Issue responses include reporter details, so the service layer likely joins issue rows to user rows before returning data.

7. **Data layer**
   - `src/db/index.ts` centralizes the PostgreSQL connection pool using `pg`.
   - The app uses raw SQL rather than an ORM, so persistence logic is likely concentrated in service methods.
   - Two core tables drive the domain model:
     - `users` for identity and roles
     - `issues` for reported work items, with `reporter_id` linking issues back to users

8. **Request processing flow**
   - Typical request path is: route → middleware → controller → service → database → response helper.
   - Controllers appear to be thin orchestration layers.
   - Services own the business rules, including validation, role checks, and SQL execution.
   - This separation is the main architectural boundary to capture in a diagram.

9. **Error handling and response shaping**
   - `middleware/globalErrorHandler.ts` provides centralized error handling for the whole API.
   - `utilities/response.ts` standardizes success/error payloads, so response formatting is not duplicated across modules.
   - This suggests a uniform API contract regardless of which module produced the response.

10. **Configuration and shared types**
   - `src/config/index.ts` reads environment variables such as `PORT`, `DATABASE_URL`, and JWT secrets.
   - `src/types/` and `src/middleware/index.d.ts` provide shared TypeScript types and request augmentation.
   - These shared files are infrastructure glue: they do not implement business features, but they keep auth, DB, and controllers type-safe.

11. **External dependencies that shape the architecture**
   - PostgreSQL is the primary persistence service, with NeonDB used as the hosted database in deployment.
   - JWT and HTTP-only cookies define the auth/session boundary.
   - Vercel affects the deployment model, so the server entrypoint and compiled output are important operationally.

12. **Useful diagram summary**
   - The cleanest diagram would show:
     - Client → Express routes
     - Routes → auth/issues middleware
     - Controllers → service layer
     - Services → PostgreSQL pool
     - PostgreSQL → users/issues tables
     - Global error handler and response helper as cross-cutting concerns
     - Environment config feeding DB/auth setup

Main entry points: [`src/modules/auth/auth.service.ts`](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/modules/auth/auth.service.ts) (Auth service), [`src/modules/issues/issues.service.ts`](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/modules/issues/issues.service.ts) (Issue service), [`src/app.ts`](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/app.ts) (App), [`src/middleware/auth.middleware.ts`](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/middleware/auth.middleware.ts) (Auth guard)

## Diagram (Mermaid)

```mermaid
flowchart TD

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

subgraph group_http["HTTP API"]
  node_auth_routes["Auth routes<br/>route set<br/>[auth.routes.ts]"]
  node_issues_routes["Issue routes<br/>route set<br/>[issues.routes.ts]"]
  node_auth_mw{{"Auth guard<br/>middleware<br/>[auth.middleware.ts]"}}
  node_error_mw{{"Error handler<br/>middleware"}}
end

subgraph group_domain["Domain"]
  node_auth_ctrl["Auth controller<br/>[auth.controller.ts]"]
  node_auth_svc["Auth service<br/>[auth.service.ts]"]
  node_issues_ctrl["Issue controller"]
  node_issues_svc["Issue service<br/>[issues.service.ts]"]
end

subgraph group_infra["Infrastructure"]
  node_response["Response helper<br/>formatter<br/>[response.ts]"]
  node_config["Config<br/>[index.ts]"]
  node_db[("DB pool<br/>postgres client<br/>[index.ts]")]
  node_types["Shared types<br/>[index.ts]"]
  node_req_types["Request augment<br/>declaration<br/>[index.d.ts]"]
end

subgraph group_data["Data Model"]
  node_users_table[("Users<br/>table")]
  node_issues_table[("Issues<br/>table")]
  node_postgres[("PostgreSQL<br/>external db")]
  node_jwt(("JWT cookies<br/>auth boundary"))
end

node_client -->|"HTTP requests"| node_app
node_server -->|"bootstraps"| node_app
node_app -->|"mounts"| node_auth_routes
node_app -->|"mounts"| node_issues_routes
node_app -->|"uses"| node_error_mw
node_auth_routes -->|"dispatches"| node_auth_ctrl
node_issues_routes -->|"protects"| node_auth_mw
node_issues_routes -->|"dispatches"| node_issues_ctrl
node_auth_ctrl -->|"delegates"| node_auth_svc
node_issues_ctrl -->|"delegates"| node_issues_svc
node_auth_svc -->|"queries"| node_db
node_issues_svc -->|"queries"| node_db
node_db -->|"connects to"| node_postgres
node_auth_svc -->|"reads/writes"| node_users_table
node_issues_svc -->|"reads/writes"| node_issues_table
node_issues_svc -->|"joins"| node_users_table
node_auth_svc -->|"issues tokens"| node_jwt
node_auth_mw -->|"verifies"| node_jwt
node_auth_svc -->|"formats"| node_response
node_issues_svc -->|"formats"| node_response
node_config -->|"configures"| node_db
node_config -->|"configures"| node_auth_svc
node_config -->|"configures"| node_server
node_types -->|"supports"| node_auth_ctrl
node_types -->|"supports"| node_issues_ctrl
node_req_types -->|"augments"| node_auth_mw
node_auth_mw -->|"authorizes"| node_issues_svc
node_error_mw -->|"emits"| node_response

click node_server "https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/server.ts"
click node_app "https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/app.ts"
click node_auth_routes "https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/modules/auth/auth.routes.ts"
click node_issues_routes "https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/modules/issues/issues.routes.ts"
click node_auth_mw "https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/middleware/auth.middleware.ts"
click node_error_mw "https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/middleware/globalErrorHandler.ts"
click node_auth_ctrl "https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/modules/auth/auth.controller.ts"
click node_auth_svc "https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/modules/auth/auth.service.ts"
click node_issues_ctrl "https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/modules/issues/issues.controller.ts"
click node_issues_svc "https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/modules/issues/issues.service.ts"
click node_response "https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/utilities/response.ts"
click node_config "https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/config/index.ts"
click node_db "https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/db/index.ts"
click node_types "https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/types/index.ts"
click node_req_types "https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/middleware/index.d.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_client,node_server,node_app toneBlue
class node_auth_routes,node_issues_routes,node_auth_mw,node_error_mw toneAmber
class node_auth_ctrl,node_auth_svc,node_issues_ctrl,node_issues_svc toneMint
class node_response,node_config,node_db,node_types,node_req_types toneRose
class node_users_table,node_issues_table,node_postgres,node_jwt toneIndigo
```

## Components

### Runtime

Entry point and compiled execution boundary

- **Client**: consumer · API callers
- [Server](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/server.ts): entrypoint · Process bootstrap · `src/server.ts`
- [App](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/app.ts): express app · Builds the Express application · `src/app.ts`

### HTTP API

Express routing, controllers, and middleware

- [Auth routes](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/modules/auth/auth.routes.ts): route set · Signup and login endpoints · `src/modules/auth/auth.routes.ts`
- [Issue routes](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/modules/issues/issues.routes.ts): route set · Issue CRUD and filtering endpoints · `src/modules/issues/issues.routes.ts`
- [Auth guard](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/middleware/auth.middleware.ts): middleware · JWT verification and access control · `src/middleware/auth.middleware.ts`
- [Error handler](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/middleware/globalErrorHandler.ts): middleware · Centralized API error handling · `src/middleware/globalErrorHandler.ts`

### Domain

Auth and issue business logic

- [Auth controller](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/modules/auth/auth.controller.ts): controller · HTTP orchestration for authentication · `src/modules/auth/auth.controller.ts`
- [Auth service](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/modules/auth/auth.service.ts): service · Registration, login, and token logic · `src/modules/auth/auth.service.ts`
- [Issue controller](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/modules/issues/issues.controller.ts): controller · HTTP orchestration for issues · `src/modules/issues/issues.controller.ts`
- [Issue service](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/modules/issues/issues.service.ts): service · CRUD, filtering, and permission rules · `src/modules/issues/issues.service.ts`

### Infrastructure

Database, config, and shared response/error plumbing

- [Response helper](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/utilities/response.ts): formatter · Standard success and error payloads · `src/utilities/response.ts`
- [Config](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/config/index.ts): env config · Reads ports, database, and JWT secrets · `src/config/index.ts`
- [DB pool](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/db/index.ts): postgres client · Central PostgreSQL connection pool · `src/db/index.ts`
- [Shared types](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/types/index.ts): types · Common TypeScript domain and request types · `src/types/index.ts`
- [Request augment](https://github.com/zihad-1883/l2-a2-devpulse-/blob/main/src/middleware/index.d.ts): declaration · Express request type augmentation · `src/middleware/index.d.ts`

### Data Model

Core persisted domain tables

- **Users**: table · Identity and role records
- **Issues**: table · Reported bugs and feature requests
- **PostgreSQL**: external db · Hosted relational persistence
- **JWT cookies**: auth boundary · Access and refresh token session flow

## Connections

- Client → App: HTTP requests · Incoming API traffic
- Server → App: bootstraps · Creates and starts the Express app
- App → Auth routes: mounts · Registers auth endpoints
- App → Issue routes: mounts · Registers issue endpoints
- App → Error handler: uses · Applies global error handling
- Auth routes → Auth controller: dispatches · Routes call auth controller handlers
- Issue routes → Auth guard: protects · Secures private issue endpoints
- Issue routes → Issue controller: dispatches · Routes call issue controller handlers
- Auth controller → Auth service: delegates · Controller keeps orchestration thin
- Issue controller → Issue service: delegates · Controller keeps orchestration thin
- Auth service → DB pool: queries · Persists and reads user records
- Issue service → DB pool: queries · Executes raw SQL for issue operations
- DB pool → PostgreSQL: connects to · Uses the PostgreSQL pool
- Auth service → Users: reads/writes · User registration and login lookup
- Issue service → Issues: reads/writes · Issue CRUD and filtering
- Issue service → Users: joins · Enriches issues with reporter details
- Auth service → JWT cookies: issues tokens · Creates access and refresh JWTs
- Auth guard → JWT cookies: verifies · Checks protected requests for valid tokens
- Auth service → Response helper: formats · Returns consistent auth responses
- Issue service → Response helper: formats · Returns consistent issue responses
- Config → DB pool: configures · Supplies database connection settings
- Config → Auth service: configures · Supplies JWT secrets and auth settings
- Config → Server: configures · Supplies runtime port and deployment settings
- Shared types → Auth controller: supports · Shared auth domain types
- Shared types → Issue controller: supports · Shared issue domain types
- Request augment → Auth guard: augments · Extends Express request objects
- Auth guard → Issue service: authorizes · Enforces role and ownership checks
- Error handler → Response helper: emits · Standardizes error payloads