How arpan-dey-web/octopi-task-backend works
1. What this repository is
- A TypeScript REST API for a multi-tenant booking system.
- The central boundary is the organization tenant: users, resources, and bookings are always scoped to an organizationId.
2. Runtime and startup shape
- src/server.ts is the process entrypoint: it likely starts the HTTP listener and handles graceful shutdown.
- src/app.ts is the Express application assembly: middleware, route mounting, and global error handling.
- src/config/env.ts validates environment variables at startup, so the app refuses to boot with missing or invalid config.
3. HTTP/API layer
- The API is organized by domain routes under src/routes/*.
- Each route module maps endpoints to a controller, and the controller delegates to a service.
- Main route groups are: auth, organizations, users, resources, bookings, and availability.
4. Controller/service split
- Controllers in src/controllers/* are the thin HTTP adapter layer: request parsing, response shaping, and status codes.
- Services in src/services/* contain the actual business rules and cross-model orchestration.
- This separation is especially important for bookings, availability generation, and auth flows, which involve multiple models and invariants.
5. Persistence layer
- Data is stored in MongoDB via Mongoose models in src/models/*.
- The domain entities are Organization, User, Resource, and Booking.
- src/models/index.ts likely centralizes model exports and schema wiring.
- The repository uses soft deletes for users/resources and booking cancellation, rather than hard deletion.
6. Tenant isolation and access control
- Authentication middleware in src/middleware/auth.ts enforces JWT-based access.
- Authorization is role-based, with ORG_ADMIN and EMPLOYEE.
- Every protected operation must also respect organizationId, so users can only see or mutate data in their own tenant.
- Admin-only operations include organization updates and most user/resource management.
7. Booking workflow and conflict boundary
- BookingService is the most domain-critical component.
- It must validate:
- resource belongs to the caller’s organization,
- booking duration falls within policy,
- booking lies inside working hours,
- advance booking constraints are met,
- no overlap/conflict exists with existing bookings.
- Conflict detection uses booking windows plus buffer time, not just raw start/end times.
- A booking cancellation is modeled as a status change to CANCELLED, not deletion.
8. Availability engine
- AvailabilityService computes free time slots from organization working hours, existing bookings, buffer rules, and requested duration.
- Time calculations use Luxon and normalize to UTC internally, while still honoring each organization’s IANA timezone.
- This is a separate read-model style concern: it derives slot availability from booking data rather than storing slots directly.
9. Auth and identity flows
- AuthService handles registration, login, token refresh, and profile lookup.
- Registration creates both an organization and the first admin user in one flow.
- JWT access and refresh tokens are part of the boundary; password storage uses bcrypt hashing.
- The auth subsystem is the only path that creates the initial tenant and administrator.
10. Validation boundary
- src/validation/* contains Zod schemas for request bodies, params, and queries.
- src/middleware/validate.ts sits between routes and controllers to enforce those schemas.
- This means malformed payloads are rejected before they reach service logic, keeping business code focused on domain rules.
11. Error handling and response contract
- src/utils/errors.ts defines domain-specific errors such as validation, authentication, authorization, conflict, and not-found cases.
- src/middleware/errorHandler.ts converts those errors into consistent HTTP responses.
- src/utils/http.ts likely standardizes response helpers or status handling.
- In production, internal stack traces are suppressed per the README.
12. Time and timezone handling
- src/utils/timezone.ts exists because time is a first-class concern in this domain.
- Organization-local working hours are interpreted in the organization’s timezone, while stored booking timestamps are normalized to UTC.
- This boundary is important for both booking validation and availability generation.
13. API surface by domain
- authRoutes covers registration/login/token refresh/profile.
- organizationRoutes exposes tenant settings.
- userRoutes and resourceRoutes manage tenant-scoped entities with admin restrictions.
- bookingRoutes covers create/list/get/update/cancel.
- availabilityRoutes is a read-only computed endpoint.
14. Operational and infrastructure boundaries
- The app depends on a live MongoDB instance via src/config/database.ts.
- Swagger setup in src/config/swagger.ts suggests API documentation is generated or served from the app.
- Tooling is Node.js + TypeScript + Express 5, with nodemon/ts-node for development and compiled output for production.
- Graceful shutdown behavior indicates explicit lifecycle management of the HTTP server and database connection.
Main entry points: app.ts App · AuthService.ts Auth Service · index.ts Models · BookingService.ts Booking Service
Components 34
Runtime
Process entrypoint and bootstrapping
- Server · Starts the HTTP process and handles shutdown
src/server.ts
HTTP API
Express app, routes, controllers, and middleware
- App · Assembles middleware, routes, and error handling
src/app.ts - Auth MW · JWT authentication and tenant access enforcement
src/middleware/auth.ts - Validate MW · Applies request validation before controllers
src/middleware/validate.ts - Errors · Maps domain errors to HTTP responses
src/middleware/errorHandler.ts - Auth Routes · Registration, login, refresh, profile
src/routes/authRoutes.ts - Booking Routes · Booking create, read, update, cancel endpoints
src/routes/bookingRoutes.ts - Availability Routes · Computed availability endpoint
src/routes/availabilityRoutes.ts - Org Routes · Organization settings endpoints
src/routes/organizationRoutes.ts - Resource Routes · Tenant resource management endpoints
src/routes/resourceRoutes.ts - User Routes · Tenant user management endpoints
src/routes/userRoutes.ts - Auth Ctrl · HTTP adapter for auth flows
src/controllers/authController.ts - Booking Ctrl · HTTP adapter for booking operations
src/controllers/bookingController.ts - Avail Ctrl · HTTP adapter for availability queries
src/controllers/availabilityController.ts - Org Ctrl · HTTP adapter for organization operations
src/controllers/organizationController.ts - Resource Ctrl · HTTP adapter for resource operations
src/controllers/resourceController.ts - User Ctrl · HTTP adapter for user operations
src/controllers/userController.ts
Domain
Core business services
- Auth Service · Registration, login, refresh, and profile flows
src/services/AuthService.ts - Booking Service · Booking rules, conflict checks, and cancellation
src/services/BookingService.ts - Availability Service · Derives free slots from bookings and working hours
src/services/AvailabilityService.ts - Org Service · Organization settings and tenant management
src/services/OrganizationService.ts - Resource Service · Resource lifecycle within an organization
src/services/ResourceService.ts - User Service · Tenant user lifecycle and role management
src/services/UserService.ts
Data
MongoDB models and persistence boundary
- Models · Central export of Organization, User, Resource, and Booking models
src/models/index.ts - Booking · Booking persistence and status lifecycle
src/models/Booking.ts - Organization · Tenant and working-hours data
src/models/Organization.ts - Resource · Organization-scoped resource data
src/models/Resource.ts - User · Organization-scoped user data
src/models/User.ts
Support
Config, validation, and shared utilities
- Env · Validates required environment variables
src/config/env.ts - Database · MongoDB connection setup and lifecycle
src/config/database.ts - Swagger · Swagger/OpenAPI configuration
src/config/swagger.ts - Errors · Shared validation, auth, conflict, and not-found errors
src/utils/errors.ts - Timezone · UTC normalization and organization timezone handling
src/utils/timezone.ts - HTTP Utils · Common response and status helpers
src/utils/http.ts
Connections 41
- Server → App: boot · Starts the Express application
- Server → Database: connect · Opens and closes MongoDB connection
- Server → Env: load config · Reads validated runtime configuration
- App → Auth MW: use · Protects tenant-scoped routes
- App → Validate MW: use · Validates requests before controllers
- App → Errors: use · Converts domain errors to responses
- App → Swagger: expose · Serves API documentation
- App → Auth Routes: mount · Mounts auth endpoints
- App → Booking Routes: mount · Mounts booking endpoints
- App → Availability Routes: mount · Mounts availability endpoints
- App → Org Routes: mount · Mounts organization endpoints
- App → Resource Routes: mount · Mounts resource endpoints
- App → User Routes: mount · Mounts user endpoints
- Auth Routes → Auth Ctrl: delegate · Routes auth requests to controller
- Booking Routes → Booking Ctrl: delegate · Routes booking requests to controller
- Availability Routes → Avail Ctrl: delegate · Routes availability requests to controller
- Org Routes → Org Ctrl: delegate · Routes organization requests to controller
- Resource Routes → Resource Ctrl: delegate · Routes resource requests to controller
- User Routes → User Ctrl: delegate · Routes user requests to controller
- Auth Ctrl → Auth Service: call · Executes auth business flows
- Booking Ctrl → Booking Service: call · Executes booking business flows
- Avail Ctrl → Availability Service: call · Computes available time slots
- Org Ctrl → Org Service: call · Handles organization operations
- Resource Ctrl → Resource Service: call · Handles resource operations
- User Ctrl → User Service: call · Handles user operations
- Auth Service → Models: use models · Creates and queries auth-related entities
- Booking Service → Models: use models · Reads and writes booking and tenant data
- Availability Service → Models: read bookings · Derives availability from persisted data
- Org Service → Models: use models · Reads and updates organizations
- Resource Service → Models: use models · Reads and updates resources
- User Service → Models: use models · Reads and updates users
- Auth Service → Errors: throw · Uses auth and validation errors
- Booking Service → Errors: throw · Uses conflict and not-found errors
- Availability Service → Timezone: normalize · Converts times between UTC and org timezone
- Booking Service → Timezone: normalize · Evaluates booking windows in tenant timezone
- Auth Service → HTTP Utils: respond · Uses shared response helpers
- Booking Service → Booking: persist · Booking persistence boundary
- Auth Service → Organization: create tenant · Registration creates organization
- Auth Service → User: create admin · Registration creates first admin user
- Resource Service → Resource: persist · Resource persistence boundary
- User Service → User: persist · User persistence boundary