How robbecl/boilerplate-express-typescript-sequelize works
Project type and purpose
• This is a boilerplate full-stack back-end service built with Node.js, Express, TypeScript, and Sequelize.
• Its purpose is to serve as a production-ready REST API (and minimal server-rendered pages via Pug), with built-in authentication, role management, session/refresh-token support, email templating, logging, Swagger docs, Docker deployment, migrations, and seeding.
File structure
• Top-level configs: Dockerfile, docker-compose.yml, .env.example, tsconfig.json, Babel, ESLint, Prettier, Husky, Commitlint.
• src/
• config/: database, Redis, email, logger, HTTP client, base URLs
• controllers/ → routers/controllers per resource (Auth, User, Role, Session, RefreshToken, UserRole)
• services are alongside controllers (service.ts)
• middlewares/: authorization, transaction handler, error handlers
• models/, migrations/, seeders/ → Sequelize ORM layer
• helpers/, modules/, utils/ → shared libraries (file uploads, Excel, email sender, token helpers, response builders, query helpers)
• routes/: public vs index (mount point)
• views/: Pug templates for error pages and index
• public/: static CSS, email HTML templates
• docs/swagger/: OpenAPI route definitions
• jobs/: scheduled tasks (RoleJob)
• Other directories: logs/, storage (via Docker volume), scripts/ for generating JWT env vars.
README
• Confirms technical stack: Node 10+, TS 4.x, Sequelize 6.x, Nodemailer, Handlebars, Yup, Swagger, Winston, Docker.
• Usage patterns: dev vs production, migrations, seeding, Docker compose with three services (app, db, redis), external SMTP or Mailgun/Gmail, cron jobs.
a. Main components
• Clients:
• API Consumers (Postman, browser apps)
• Swagger UI for docs
• Cron scheduler triggering jobs internally
• Load Balancer / Reverse Proxy (optional, e.g., Nginx)
• Express Application container
• HTTP Server (src/bin/server.ts)
• Route Dispatcher → middleware chain → controllers → services
• Business Services (Auth, User, Role, Session, RefreshToken, UserRole)
• Helper/Module Layer (email sender, query helper, token utils, response builder)
• Scheduled Jobs (RoleJob, index.ts in jobs/)
• Static public folder & Pug view renderer
• Data Stores
• MySQL/MariaDB (Sequelize ORM layer: models, migrations, seeders)
• Redis (session cache, token blacklist, rate-limit store)
• External Services
• SMTP/mail service (Mailgun or Google OAuth2)
• Redis cluster if scaled
• Optional S3 or file storage for uploads
• DevOps / Infrastructure
• Docker Compose network with three services: express_app, express_db, express_redis
• CI/CD (Husky, Commitlint, release scripts)
• Logging to filesystem via Winston
b. Relationships and interactions
• Client → HTTP request → Express /routes/ → middlewares → controllers
• Controller invokes service layer → modules/helpers → Sequelize → MySQL
• Service may read/write Redis via config/Rediss.ts
• Service may dispatch email via Nodemailer + Handlebars templates
• Scheduled Jobs run inside the same container, using service layer to operate on DB
• Swagger UI served by express at /docs
• Migrations/seeders executed via npm scripts before startup
• Docker Compose orchestrates network communication
c. Architectural patterns & principles
• Layered architecture: Presentation (routes/controllers), Business (services), Data Access (models, Sequelize)
• Dependency Injection via config modules
• Transaction management via middleware (ExpressAutoHandleTransaction)
• OpenAPI-first docs generation
• CQRS-ish separation: controllers handle HTTP, services handle logic, modules/utilities handle cross-cutting concerns
• Error-first flow: custom error classes and centralized error handler
d. Key technologies
• Node.js + Express + TypeScript
• Sequelize ORM + MariaDB
• Redis for cache/session management
• Nodemailer + Handlebars for email templating
• Winston for logging
• Yup for request validation
• Swagger for API docs
• Docker + Docker Compose for environment isolation