Backend REST Routing

Relevant source files

The following files were used as context for generating this wiki page:

• backend/src/app.ts
• backend/src/interfaces/http/routes/booking.routes.ts
• backend/src/interfaces/http/routes/ai.routes.ts
• backend/src/interfaces/controllers/BookingController.ts
• server.js
• src/routes/chat.js
• backend/src/interfaces/http/middleware/validation.middleware.ts

The Backend REST Routing system organizes the communication interface between clients and the AtlasCleanAI Enterprise core logic. It provides structured access to cleaning service bookings, AI-driven scheduling, authentication, and payment processing through a series of modular Express.js routers.

This routing architecture facilitates a clean separation between HTTP concerns and business logic. The system uses a centralized application factory to inject dependencies and mount specific resource routers under a versioned API prefix.

Sources: backend/src/app.ts:168-183, server.js:10-14

Routing Architecture

The application implements a modular routing structure where each domain resource (e.g., Bookings, AI, Auth) has a dedicated router factory. The main createApp function initializes these routers and applies global middleware including security headers via helmet, request compression, and CORS configuration.

Request Lifecycle

When a request arrives at the backend, it passes through a series of global and route-specific handlers:

1. Global Middleware: Applies rate limiting, security headers, and body parsing.
2. Authentication: Verifies JWT tokens or API keys for protected routes.
3. Validation: Ensures the request body, parameters, or query strings match expected Zod schemas.
4. Controller: Extracts data from the request and invokes relevant Use Cases.
5. Response: Returns JSON data or passes errors to a centralized error handler.

Sources: backend/src/app.ts:153-166, backend/src/interfaces/http/middleware/validation.middleware.ts:6-15, server.js:16-30

API Endpoint Reference

The system exposes endpoints categorized by resource type. Most endpoints, except for initial authentication and health checks, require active sessions or valid API keys.

Booking Management

The booking router handles the lifecycle of cleaning service requests. All booking routes are protected by the authMiddleware.

Method	Path	Description	Controller Action
GET	/api/v1/bookings	Lists bookings for the authenticated user	BookingController.list
POST	/api/v1/bookings	Creates a new cleaning service booking	BookingController.create
PATCH	/api/v1/bookings/:bookingId	Updates an existing booking's details	BookingController.update
POST	/api/v1/bookings/:bookingId/cancel	Cancels a scheduled booking	BookingController.cancel

Sources: backend/src/interfaces/http/routes/booking.routes.ts:7-12, backend/src/interfaces/controllers/BookingController.ts:16-56

AI and Scheduling Intelligence

The AI routing module provides endpoints for predictive features and automated decision-making.

Method	Path	Description	Controller Action
GET	/api/v1/ai/demand	Predicts future cleaning service demand	AIController.predictDemand
POST	/api/v1/ai/pricing	Calculates dynamic pricing for a service	AIController.dynamicPricing
POST	/api/v1/ai/schedule	Generates optimized scheduling slots	AIController.smartScheduling
POST	/api/v1/ai/recommend-cleaner	Identifies the best cleaner for a job	AIController.recommendCleaner

Sources: backend/src/interfaces/http/routes/ai.routes.ts:6-11

Atlas AI Chat (LLM Integration)

Standard and streaming chat endpoints are provided for interactive AI assistance. These routes are protected by apiKeyAuth.

Method	Path	Description	Data Format
POST	/api/chat	Standard request-response chat	application/json
POST	/api/chat/stream	Real-time Server-Sent Events (SSE) chat	text/event-stream

Sources: src/routes/chat.js:10-44, server.js:41-42

Middleware Integration

The routing layer relies on middleware factories to inject dependencies like JwtService into the request flow.

Validation Middleware

The validate middleware uses ZodSchema to parse and validate incoming data. If validation fails, it triggers the error handling pipeline before reaching the controller.

export const validate = <T>(schema: ZodSchema<T>, source: 'body' | 'query' | 'params' = 'body') => {
  return (request: Request, _response: Response, next: NextFunction): void => {
    try {
      const parsed = validateSchema(schema, request[source]);
      Object.assign(request[source], parsed);
      next();
    } catch (error) {
      next(error);
    }
  };
};

Sources: backend/src/interfaces/http/middleware/validation.middleware.ts:6-16

Rate Limiting

The platform implements multiple rate limiting tiers to protect endpoints:

• General Limiter: Applied to standard API routes (e.g., 200 requests per 15 minutes).
• Chat Limiter: Stricter limits for AI chat endpoints to manage provider costs (e.g., 30 requests per minute).

Sources: server.js:16-30, backend/src/app.ts:166

Health and Monitoring

A system-level health endpoint is available at /health (or /api/health). It provides operational status, including whether AI services are correctly configured.

Summary

The Backend REST Routing in AtlasCleanAI Enterprise provides a modular, secure, and validated interface for the platform's features. By utilizing Express routers combined with domain-specific controllers and AI services, it ensures that client requests are properly authenticated, throttled, and processed according to the business rules of the cleaning service ecosystem.