# meharab-27/devreport architecture

> Architecture diagram of the GitHub repository meharab-27/devreport, 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/meharab-27/devreport
- Repository: https://github.com/meharab-27/devreport

## Overview

1. **Overall shape**
   - This is a backend-only, modular Express API written in TypeScript.
   - The runtime path is `src/server.ts` → `src/app.ts` → feature routes/controllers/services.
   - The build output is in `dist/`, produced for deployment on Vercel (`vercel.json` is present).

2. **Request lifecycle**
   - Incoming HTTP requests enter the Express app, pass through shared middleware, then hit a feature route.
   - Routes delegate to controllers, controllers call services, and services execute SQL against PostgreSQL.
   - Responses are standardized through a shared response helper, while failures flow into a centralized error handler.

3. **Core feature modules**
   - The codebase is split into three domain modules under `src/modules/`:
     - `auth` for registration and login
     - `user` for user-related operations
     - `issues` for issue creation, retrieval, update, delete, filtering, and sorting
   - Each module has its own controller, service, and route layer, which keeps HTTP concerns separate from business logic.

4. **Authentication subsystem**
   - Authentication is JWT-based.
   - The auth flow uses `bcrypt` for password hashing/verification and `jsonwebtoken` for token issuance and validation.
   - The login/register paths are isolated in the auth module, and protected endpoints rely on auth middleware to verify the bearer token.

5. **Authorization boundaries**
   - There is role-based access control with at least two roles: `contributor` and `maintainer`.
   - The middleware layer enforces these permissions before privileged issue operations, such as updating, deleting, or changing workflow status.
   - Public access is limited to browsing issues, while write operations are restricted to authenticated users.

6. **Data access layer**
   - PostgreSQL is the persistence layer, accessed directly through the native `pg` driver and `pool.query()`.
   - `src/db/index.ts` centralizes database connection/pool setup, so the feature services do not talk to the database ad hoc.
   - There is no ORM layer; SQL is likely embedded in the services, making the service layer the main business/data boundary.

7. **Domain data model**
   - The README describes two primary tables: `users` and `issues`.
   - `issues` is linked to `users` through `reporter_id`, which means issue ownership/reporting is part of the architecture.
   - Issue workflow fields like `type` and `status` are first-class domain concepts, not just presentation concerns.

8. **Middleware and cross-cutting concerns**
   - Shared middleware includes logging, auth verification, and a global error handler.
   - `logger.ts` captures request/activity logging, while `globalErrorHandler.ts` standardizes error responses across modules.
   - There is also a custom type augmentation file under `src/middleware/index.d.ts`, suggesting Express request typing is extended for auth/user context.

9. **Controller/service split**
   - Controllers appear to be thin HTTP adapters: they parse request data and format the response.
   - Services hold the business rules: credential checks, token generation, role checks, issue lifecycle logic, and SQL calls.
   - This separation is the main architectural boundary inside each module and is important for diagramming.

10. **Shared utilities and config**
   - `src/config` centralizes environment and runtime configuration.
   - `src/utility/sendResponse.ts` provides a common response shape, which likely keeps success payloads consistent across endpoints.
   - This shared layer reduces duplication across auth, user, and issue routes.

11. **External dependencies that materially affect the architecture**
   - PostgreSQL is the system of record.
   - `bcrypt` and `jsonwebtoken` are core security dependencies that shape the auth boundary.
   - Express is the HTTP framework, and TypeScript provides compile-time structure across modules and middleware.

12. **Deployment/build boundary**
   - `tsup.config.ts` and the `dist/` directory indicate the source is compiled/bundled before deployment.
   - The presence of `vercel.json` suggests serverless-style hosting, but the architecture remains a standard API service with one deployed backend entrypoint.

13. **What to draw in an architecture diagram**
   - Draw a single API server boundary containing middleware, modular routes, controllers, services, and shared utilities.
   - Show PostgreSQL as the external persistence system.
   - Show auth as a cross-cutting concern spanning multiple routes, and role checks gating maintainer-only operations.
   - Show the issue module as the main domain workflow, with users/auth as supporting identity/security subsystems.

Main entry points: [`src/app.ts`](https://github.com/meharab-27/devreport/blob/main/src/app.ts) (App), [`src/modules/auth/auth.service.ts`](https://github.com/meharab-27/devreport/blob/main/src/modules/auth/auth.service.ts) (Auth svc), [`src/db/index.ts`](https://github.com/meharab-27/devreport/blob/main/src/db/index.ts) (DB pool), [`src/middleware/auth.ts`](https://github.com/meharab-27/devreport/blob/main/src/middleware/auth.ts) (Auth mw)

## Diagram (Mermaid)

```mermaid
flowchart TD

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

subgraph group_shared["Shared"]
  node_config["Config<br/>[index.ts]"]
  node_db[("DB pool<br/>postgres pool<br/>[index.ts]")]
  node_authmw["Auth mw<br/>middleware<br/>[auth.ts]"]
  node_logger["Logger<br/>middleware<br/>[logger.ts]"]
  node_errors["Errors<br/>error handler"]
  node_response["Responses<br/>helper<br/>[sendResponse.ts]"]
end

subgraph group_modules["Modules"]
  node_authroute["Auth routes<br/>route layer<br/>[auth.route.ts]"]
  node_authctl["Auth ctrl<br/>controller<br/>[auth.controller.ts]"]
  node_authsvc["Auth svc<br/>[auth.service.ts]"]
  node_userroute["User routes<br/>route layer<br/>[user.route.ts]"]
  node_userctl["User ctrl<br/>controller<br/>[user.controller.ts]"]
  node_usersvc["User svc<br/>[user.service.ts]"]
  node_issueroute["Issue routes<br/>route layer<br/>[issue.route.ts]"]
  node_issuectl["Issue ctrl<br/>controller"]
  node_issuesvc["Issue svc<br/>[issue.service.ts]"]
end

subgraph group_external["External"]
  node_postgres[("PostgreSQL<br/>database")]
  node_security{{"bcrypt/jwt<br/>security deps"}}
  node_vercel["Vercel<br/>deployment<br/>[vercel.json]"]
end

node_server -->|"boots"| node_app
node_app -->|"uses"| node_logger
node_app -->|"uses"| node_authmw
node_app -->|"uses"| node_errors
node_app -->|"mounts"| node_authroute
node_app -->|"mounts"| node_userroute
node_app -->|"mounts"| node_issueroute
node_authroute -->|"delegates"| node_authctl
node_authctl -->|"calls"| node_authsvc
node_authsvc -->|"uses"| node_security
node_authsvc -->|"queries"| node_db
node_userroute -->|"delegates"| node_userctl
node_userctl -->|"calls"| node_usersvc
node_usersvc -->|"queries"| node_db
node_issueroute -->|"delegates"| node_issuectl
node_issuectl -->|"calls"| node_issuesvc
node_issuesvc -->|"queries"| node_db
node_authroute -.->|"protects"| node_authmw
node_userroute -.->|"protects"| node_authmw
node_issueroute -.->|"protects"| node_authmw
node_issuesvc -->|"formats"| node_response
node_authsvc -->|"formats"| node_response
node_usersvc -->|"formats"| node_response
node_app -->|"reads"| node_config
node_vercel -.->|"deploys"| node_server
node_db -->|"connects"| node_postgres

click node_server "https://github.com/meharab-27/devreport/blob/main/src/server.ts"
click node_app "https://github.com/meharab-27/devreport/blob/main/src/app.ts"
click node_config "https://github.com/meharab-27/devreport/blob/main/src/config/index.ts"
click node_db "https://github.com/meharab-27/devreport/blob/main/src/db/index.ts"
click node_authmw "https://github.com/meharab-27/devreport/blob/main/src/middleware/auth.ts"
click node_logger "https://github.com/meharab-27/devreport/blob/main/src/middleware/logger.ts"
click node_errors "https://github.com/meharab-27/devreport/blob/main/src/middleware/globalErrorHandler.ts"
click node_response "https://github.com/meharab-27/devreport/blob/main/src/utility/sendResponse.ts"
click node_authroute "https://github.com/meharab-27/devreport/blob/main/src/modules/auth/auth.route.ts"
click node_authctl "https://github.com/meharab-27/devreport/blob/main/src/modules/auth/auth.controller.ts"
click node_authsvc "https://github.com/meharab-27/devreport/blob/main/src/modules/auth/auth.service.ts"
click node_userroute "https://github.com/meharab-27/devreport/blob/main/src/modules/user/user.route.ts"
click node_userctl "https://github.com/meharab-27/devreport/blob/main/src/modules/user/user.controller.ts"
click node_usersvc "https://github.com/meharab-27/devreport/blob/main/src/modules/user/user.service.ts"
click node_issueroute "https://github.com/meharab-27/devreport/blob/main/src/modules/issues/issue.route.ts"
click node_issuectl "https://github.com/meharab-27/devreport/blob/main/src/modules/issues/issue.controller.ts"
click node_issuesvc "https://github.com/meharab-27/devreport/blob/main/src/modules/issues/issue.service.ts"
click node_vercel "https://github.com/meharab-27/devreport/blob/main/vercel.json"

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_config,node_db,node_authmw,node_logger,node_errors,node_response toneAmber
class node_authroute,node_authctl,node_authsvc,node_userroute,node_userctl,node_usersvc,node_issueroute,node_issuectl,node_issuesvc toneMint
class node_postgres,node_security,node_vercel toneRose
```

## Components

### Runtime

Boot and deployed server entrypoints

- [Server](https://github.com/meharab-27/devreport/blob/main/src/server.ts): entrypoint · Starts the API process · `src/server.ts`
- [App](https://github.com/meharab-27/devreport/blob/main/src/app.ts): express app · Wires middleware and routes · `src/app.ts`

### Shared

Cross-cutting app infrastructure and utilities

- [Config](https://github.com/meharab-27/devreport/blob/main/src/config/index.ts): runtime config · Environment and app settings · `src/config/index.ts`
- [DB pool](https://github.com/meharab-27/devreport/blob/main/src/db/index.ts): postgres pool · Central PostgreSQL connection access · `src/db/index.ts`
- [Auth mw](https://github.com/meharab-27/devreport/blob/main/src/middleware/auth.ts): middleware · Verifies bearer tokens and user context · `src/middleware/auth.ts`
- [Logger](https://github.com/meharab-27/devreport/blob/main/src/middleware/logger.ts): middleware · Request and activity logging · `src/middleware/logger.ts`
- [Errors](https://github.com/meharab-27/devreport/blob/main/src/middleware/globalErrorHandler.ts): error handler · Global error response handling · `src/middleware/globalErrorHandler.ts`
- [Responses](https://github.com/meharab-27/devreport/blob/main/src/utility/sendResponse.ts): helper · Shared success response formatting · `src/utility/sendResponse.ts`

### Modules

Domain feature boundaries

- [Auth routes](https://github.com/meharab-27/devreport/blob/main/src/modules/auth/auth.route.ts): route layer · Login and registration endpoints · `src/modules/auth/auth.route.ts`
- [Auth ctrl](https://github.com/meharab-27/devreport/blob/main/src/modules/auth/auth.controller.ts): controller · HTTP adapter for auth flows · `src/modules/auth/auth.controller.ts`
- [Auth svc](https://github.com/meharab-27/devreport/blob/main/src/modules/auth/auth.service.ts): service · Credentials, hashing, and token logic · `src/modules/auth/auth.service.ts`
- [User routes](https://github.com/meharab-27/devreport/blob/main/src/modules/user/user.route.ts): route layer · User-related endpoints · `src/modules/user/user.route.ts`
- [User ctrl](https://github.com/meharab-27/devreport/blob/main/src/modules/user/user.controller.ts): controller · HTTP adapter for user operations · `src/modules/user/user.controller.ts`
- [User svc](https://github.com/meharab-27/devreport/blob/main/src/modules/user/user.service.ts): service · User business and data access · `src/modules/user/user.service.ts`
- [Issue routes](https://github.com/meharab-27/devreport/blob/main/src/modules/issues/issue.route.ts): route layer · Issue CRUD and workflow endpoints · `src/modules/issues/issue.route.ts`
- [Issue ctrl](https://github.com/meharab-27/devreport/blob/main/src/modules/issues/issue.controller.ts): controller · HTTP adapter for issue operations · `src/modules/issues/issue.controller.ts`
- [Issue svc](https://github.com/meharab-27/devreport/blob/main/src/modules/issues/issue.service.ts): service · Issue lifecycle, filtering, and SQL · `src/modules/issues/issue.service.ts`

### External

Outside systems and runtime dependencies

- **PostgreSQL**: database · System of record for users and issues
- **bcrypt/jwt**: security deps · Password hashing and token issuance
- [Vercel](https://github.com/meharab-27/devreport/blob/main/vercel.json): deployment · Deployment target for built server bundle · `vercel.json`

## Connections

- Server → App: boots · Process startup hands off to the Express app
- App → Logger: uses · Shared request logging middleware
- App → Auth mw: uses · Auth verification middleware in the request pipeline
- App → Errors: uses · Centralized failure handling
- App → Auth routes: mounts · Auth endpoint set
- App → User routes: mounts · User endpoint set
- App → Issue routes: mounts · Issue endpoint set
- Auth routes → Auth ctrl: delegates · Routes forward to controllers
- Auth ctrl → Auth svc: calls · Auth controller delegates business logic
- Auth svc → bcrypt/jwt: uses · Password hashing and JWT handling
- Auth svc → DB pool: queries · Auth service reads and writes via the pool
- User routes → User ctrl: delegates · Routes forward to controllers
- User ctrl → User svc: calls · User controller delegates business logic
- User svc → DB pool: queries · User service uses pooled SQL access
- Issue routes → Issue ctrl: delegates · Routes forward to controllers
- Issue ctrl → Issue svc: calls · Issue controller delegates business logic
- Issue svc → DB pool: queries · Issue service uses pooled SQL access
- Auth routes → Auth mw: protects · Protected auth-dependent endpoints use token verification
- User routes → Auth mw: protects · Authenticated user access
- Issue routes → Auth mw: protects · Bearer token verification for write and privileged operations
- Issue svc → Responses: formats · Shared response shape for successful results
- Auth svc → Responses: formats · Shared response shape for successful results
- User svc → Responses: formats · Shared response shape for successful results
- App → Config: reads · Runtime configuration is applied at startup
- Vercel → Server: deploys · Built server bundle is deployed through Vercel
- DB pool → PostgreSQL: connects · Central database pool targets PostgreSQL