How jawherkl/node-api-postgres works
Project Type and Purpose
• This is a standalone backend service: a modern RESTful API built with Node.js/Express that manages user data and metrics in a PostgreSQL database.
• It offers authentication (JWT), role-based access control, soft-deletion, password-reset via email (SendGrid), metrics instrumentation (Prometheus), Swagger docs, and unit tests.
File Structure and Architectural Layers
• Entry Point: index.js – initializes Express app, loads middleware, routes, Swagger, metrics.
• Configuration Layer (config/): DB connection (config/db.js), Swagger setup (config/swagger.js + swagger.json), environment.
• Routing Layer (routes/): loginRoutes, userRoutes, metricsRoutes – define API endpoints and attach controllers.
• Controller Layer (controllers/): Implements request handlers (authController, userController, metricsController).
• Business Logic & Services (middleware/, utils/):
• middleware/auth.js & authorize.js – JWT validation, RBAC.
• middleware/upload.js – file upload handling.
• middleware/errorHandler.js – centralized error formatting.
• utils/mailer.js – email service (SendGrid).
• utils/logger.js – logging.
• Data Access Layer (models/): ORM/DB-client models for Users and Metrics.
• External Integrations:
• PostgreSQL database (configurable via docker-compose or .env).
• SendGrid (mailer utility).
• Prometheus (prometheus.yml) exposing /metrics endpoint.
• Supporting Files:
• Swagger UI served at /api-docs.
• Static HTML (public/reset-password.html).
• File storage directory (uploads/).
• Docker artifacts (Dockerfile, docker-compose.yml).
Architectural Patterns & Design Principles
• Layered / MVC-style separation: Routes → Controllers → Models.
• Middleware pipeline for cross-cutting concerns (auth, error handling, file uploads).
• Modularization: config, routes, controllers, models, utils all decoupled.
• Infrastructure as Code: Docker + docker-compose for reproducible environment.
• Observability: logs (utils/logger) + metrics (Prometheus).
• Documentation: self-documenting API via Swagger.
Essential Elements
• Clear component names: API Gateway (Express), Auth Service (JWT/Middleware), User Service (Controllers + Models), Metrics Service.