How meharab-27/devreport works
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: app.ts App · auth.service.ts Auth svc · index.ts DB pool · auth.ts Auth mw
Components 20
Runtime
Boot and deployed server entrypoints
Shared
Cross-cutting app infrastructure and utilities
- Config · Environment and app settings
src/config/index.ts - DB pool · Central PostgreSQL connection access
src/db/index.ts - Auth mw · Verifies bearer tokens and user context
src/middleware/auth.ts - Logger · Request and activity logging
src/middleware/logger.ts - Errors · Global error response handling
src/middleware/globalErrorHandler.ts - Responses · Shared success response formatting
src/utility/sendResponse.ts
Modules
Domain feature boundaries
- Auth routes · Login and registration endpoints
src/modules/auth/auth.route.ts - Auth ctrl · HTTP adapter for auth flows
src/modules/auth/auth.controller.ts - Auth svc · Credentials, hashing, and token logic
src/modules/auth/auth.service.ts - User routes · User-related endpoints
src/modules/user/user.route.ts - User ctrl · HTTP adapter for user operations
src/modules/user/user.controller.ts - User svc · User business and data access
src/modules/user/user.service.ts - Issue routes · Issue CRUD and workflow endpoints
src/modules/issues/issue.route.ts - Issue ctrl · HTTP adapter for issue operations
src/modules/issues/issue.controller.ts - Issue svc · Issue lifecycle, filtering, and SQL
src/modules/issues/issue.service.ts
External
Outside systems and runtime dependencies
- PostgreSQL · System of record for users and issues
- bcrypt/jwt · Password hashing and token issuance
- Vercel · Deployment target for built server bundle
vercel.json
Connections 26
- 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