mr9asif/devpulse-assignment-2

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.