How santiq/bulletproof-nodejs works
Project type and purpose
• This is a backend API service written in Node.js + TypeScript following the “Bulletproof Node.js” layered architecture.
• Its role is to expose a user CRUD API with authentication, validation, email sequences and job scheduling.
File structure
• Top-level:
• config files (.env, CircleCI, Gitpod, ESLint, Prettier, Optic, Procfile)
• src/ – the entire server codebase
• tests/ – unit/integration tests
• src/
• api/ – Express routes and middlewares
• loaders/ – bootstrap modules (Express server, Mongoose, DI container, Agenda jobs, event system, logger)
• services/ – business logic (auth, mailer, etc.)
• models/ – Mongoose user schema
• jobs/ – Agenda job definitions (e.g., emailSequence)
• subscribers/ – event handlers subscribing to domain events
• decorators/ – custom decorators (e.g., eventDispatcher)
• config/, interfaces/, types/ – type definitions and app configuration
README for additional insights
• Mentions Celebrate+Joi for request validation
• Uses Optic for API documentation
• Emphasizes a layered, dependency-injected, event-driven design
1. Client (e.g., Postman / Frontend)
2. Express API Gateway
3. Validation Layer (celebrate/Joi)
4. Authentication & Authorization middleware
5. Router → Controllers
6. Dependency Injection Container (wires services, repositories, eventDispatcher)
7. Services Layer (authService, mailerService, userService, etc.)
8. Data Layer (Mongoose + MongoDB)
9. Event Bus (in-process EventEmitter)
10. Subscribers (userCreated, emailSent handlers)
11. Job Scheduler (Agenda, jobs like emailSequence)
12. External Services (SMTP/email provider, Optic CLI, third-party services if any)
13. CI/CD (CircleCI) and Deployment (Heroku/Elastic Beanstalk via Procfile)
b. Relationships & interactions:
• Requests flow: Client → API Gateway → Validation → Auth Middleware → Router → Controller
• Controller → calls Services → Services → DAO (Mongoose) → MongoDB
• Services dispatch domain events → Event Bus → Subscribers
• Subscribers may schedule jobs in Agenda → Agenda Worker → execute job definitions (e.g. emailSequence → mailerService → SMTP)
• Optic CLI captures requests for API spec (separate side-channel)
• CircleCI pipeline runs tests & lint on push
c. Architectural patterns / principles:
• Layered (Presentation → API → Services → Data)
• Dependency Injection to decouple modules
• Event-Driven for cross-cutting concerns (logging, emails, audits)
• Job Scheduling for background tasks (Agenda)
• Validation at the edge (Celebrate+)
• Separation of concerns: loaders initialize each layer
d. Key technologies / libraries:
• Node.js + TypeScript
• Express.js
• Celebrate + Joi
• Mongoose + MongoDB
• Agenda (job scheduling)
• EventEmitter pattern via custom decorator
• Dependency Injector (tsyringe/inversify or custom)
• Optic (API docs)
• CircleCI (CI)
• dotenv / config