How apuy717/template-api works
Project Type and Purpose
• This is a Node.js TypeScript–based REST API template (“template-api”) that accelerates API development.
• It uses Express under the hood (via decorators), TypeORM for data access, JWT for auth, and supports RBAC, clustering, request validation, and OpenAPI docs.
Main Architectural Components
a. Entry & HTTP Layer
• server.ts: Starts an HTTP server, sets up clustering.
• app.ts: Initializes Express app, registers middleware, routes, error handlers.
b. Routing & Controllers
• src/controllers/*.controller.ts: Define decorated route handlers (AuthController, UserController, RoleController).
c. Middleware
• src/middlewares/auth.middleware.ts: JWT verification & RBAC enforcement.
• Decorator layer in src/utils/decorators for mapping controllers/middlewares.
d. Business Logic Layer
• src/services/*.service.ts: Encapsulate core operations (auth, user, role, permission).
e. Data Access Layer
• src/database/datasource.ts: TypeORM DataSource config.
• src/models/*.entity.ts: Entity definitions for User, Role, Permission.
• src/database/migrations: Schema migrations.
f. DTOs & Validation
• src/validators & helper.validator.ts: Input validation logic.
g. API Documentation
• openapi.yaml + docs/: Auto-generated Swagger/OpenAPI definitions.
h. Testing
• tests/app.e2e.test.ts: End-to-end test suite via Mocha.
i. Utilities & Config
• .env.example, package.json, tsconfig.json, mocha.config.json.
Component Interactions & Data Flow
1. Client HTTP Request → Express cluster (server.ts spawns workers).
2. Worker Express App (app.ts) → Global Middleware (logging, JSON parsing).
3. Authentication Middleware → Verifies JWT, loads roles/permissions.
4. Routing Decorator Layer → Dispatch to correct Controller method.
5. Controller → Input is validated against DTOs.
6. Controller → Calls corresponding Service.
7. Service → Uses TypeORM Repositories (DataSource) to interact with Database.
8. Service → Business logic (create user, assign roles, generate JWT).
9. Service → Returns result to Controller.
10. Controller → Sends HTTP response.
11. Swagger UI via /api-docs reads openapi.yaml.
Architectural Patterns & Principles
• Layered MVC-style architecture: Controllers → Services → Repositories (TypeORM).
• Decorator-driven routing and middleware (separation of concerns, declarative).
• RBAC enforced at middleware layer.
• Clustering to leverage multi-core CPUs.
• Migration-based schema evolution.
Practical Steps
2. Inside each Worker: stack three horizontal layers:
• Layer 1: “Express App” → “Global Middleware” → “Auth & RBAC Middleware”.
• Layer 2: “Decorator Router” → “Controllers [Auth, User, Role]”.
• Layer 3: “Services [AuthService, UserService, RoleService, PermissionService]”.