How zihad-1883/l2-a2-devpulse- works
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: auth.service.ts Auth service · issues.service.ts Issue service · app.ts App · auth.middleware.ts Auth guard
Components 20
Runtime
Entry point and compiled execution boundary
HTTP API
Express routing, controllers, and middleware
- Auth routes · Signup and login endpoints
src/modules/auth/auth.routes.ts - Issue routes · Issue CRUD and filtering endpoints
src/modules/issues/issues.routes.ts - Auth guard · JWT verification and access control
src/middleware/auth.middleware.ts - Error handler · Centralized API error handling
src/middleware/globalErrorHandler.ts
Domain
Auth and issue business logic
- Auth controller · HTTP orchestration for authentication
src/modules/auth/auth.controller.ts - Auth service · Registration, login, and token logic
src/modules/auth/auth.service.ts - Issue controller · HTTP orchestration for issues
src/modules/issues/issues.controller.ts - Issue service · CRUD, filtering, and permission rules
src/modules/issues/issues.service.ts
Infrastructure
Database, config, and shared response/error plumbing
- Response helper · Standard success and error payloads
src/utilities/response.ts - Config · Reads ports, database, and JWT secrets
src/config/index.ts - DB pool · Central PostgreSQL connection pool
src/db/index.ts - Shared types · Common TypeScript domain and request types
src/types/index.ts - Request augment · Express request type augmentation
src/middleware/index.d.ts
Data Model
Core persisted domain tables
- Users · Identity and role records
- Issues · Reported bugs and feature requests
- PostgreSQL · Hosted relational persistence
- JWT cookies · Access and refresh token session flow
Connections 28
- 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