How ziyadh-ali/workwave-api works
Project Type and Purpose
• This is a backend-only (Node.js/TypeScript) REST API for a company portal that manages employees, leave, payroll, messaging, etc.
• It follows a clean/hexagonal (onion) architecture:
– Adapters (controllers, repositories, services)
– Application (use cases)
– Domain (entities, DTOs, mappers, interfaces)
– Framework/Infrastructure (HTTP server, DI container, database, external services)
File Structure and Map to Architectural Layers
• src/frameworks/http/server.ts & src/frameworks/routes → API gateway layer (Express server + route definitions)
• src/adapters/controllers → HTTP “ports” (Controllers implement API endpoints)
• src/adapters/middlewares → cross-cutting concerns (auth, logging, error handling)
• src/adapters/repositories → infrastructure implementations of repository interfaces
• src/useCases → application services (orchestrate business flows)
• src/entities → domain models, DTOs, interfaces, mappers, repository & service interfaces
• src/frameworks/database → database connection (mongoConnect), schemas & ORM models
• src/adapters/service & src/shared → integrations with external systems (SMTP, Cloudinary, socket server, cron jobs)
• src/frameworks/di → dependency-injection registry and resolver
README for Additional Insight
• Confirms purpose: “company portal to manage employees.”
• Implies modules for attendance, leave, payroll, messaging, PDF generation, admin vs. employee roles.
1. HTTP Request → Routes → AuthMiddleware → Controller
2. Controller calls corresponding Use Case (injected via DI)
3. Use Case calls Repository Interface and/or Service Interface
4. Repository Implementation (Adapter) uses Mongoose Model → MongoDB
5. Data flows back up: DB → Model → Repository → Use Case → Controller → Response
6. External Service calls (e.g., Mailer, Cloudinary, Socket) branch off from Use Cases or Services
7. CronService (adapter) triggers scheduled Use Case executions
c. Architectural Patterns & Principles:
– Dependency Inversion: Controllers → Use Case Interfaces; Use Cases → Repository Interfaces
– Single Responsibility: Each layer has a distinct concern
– Separation of Concerns & Testability: Domain logic isolated in Use Cases & Entities
– Hexagonal/Clean Architecture: Adapters and Frameworks sit at the edges, core domain at center
d. Technologies & Frameworks to annotate:
– Node.js, TypeScript, Express
– Mongoose (MongoDB)
– JWT, bcrypt (security)
– Multer/Cloudinary (file uploads)
– Nodemailer (email)
– socket.io (real-time messages)
– node-cron (scheduled jobs)
– ts-yr (DI container, if applicable)
Essential Elements (Don’t Over-Complicate)
• Express Server → Controllers → Use Cases → Repositories → MongoDB
• External Adapters: Email, File Upload, Socket, Scheduler
• DI Container wiring components together
– Include error-handling and logging middleware as part of the request pipeline.