Atlas AI Orchestration Layer

Relevant source files

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

• backend/src/infrastructure/services/AtlasAIService.ts
• src/services/atlasAI.js
• src/routes/chat.js
• server.js
• backend/src/app.ts
• README.md

The Atlas AI Orchestration Layer manages the integration of artificial intelligence across the AtlasCleanAI Enterprise platform. It provides specialized services for cleaning operations, including automated scheduling, dynamic pricing, and a ChatGPT-powered assistant for customer and workforce inquiries.

Sources: README.md:103-107, src/services/atlasAI.js:3-13

Architecture and Components

The orchestration layer consists of two primary implementations: a business logic service (backend/src/infrastructure/services/AtlasAIService.ts) and a conversational interface service (src/services/atlasAI.js). These services interact with external AI providers, primarily OpenAI, to process operational data and generate natural language responses.

System Interaction Flow

The following diagram illustrates how the frontend and backend interact with the AI services.

Operational Intelligence Services

The AtlasAIService class in the backend infrastructure provides methods to optimize business operations. It supports remote API calls with local heuristic fallbacks to ensure system availability if the AI provider is unreachable.

Key Capabilities

Feature	Description	File Reference
Schedule Optimization	Ranks cleaners for specific jobs based on skills, rating, and location.	AtlasAIService.ts:44
Demand Prediction	Forecasts service demand for specific postal codes and service types.	AtlasAIService.ts:98
Dynamic Pricing	Calculates final pricing based on base rates, demand multipliers, and rush hours.	AtlasAIService.ts:119
Cleaner Recommendation	Identifies the best candidate for a new booking request.	AtlasAIService.ts:110

Fallback Logic

When the external AI client is not configured or a request fails, the service executes local heuristics. For scheduling, it calculates a score based on:

• Skill Boost: +0.25 for matching skills.
• Area Boost: +0.2 for local service areas.
• Experience: Up to +0.2 based on completed jobs.
• Rating: Raw rating divided by 5.

Sources: backend/src/infrastructure/services/AtlasAIService.ts:70-82, backend/src/infrastructure/services/AtlasAIService.ts:133-138

Conversational AI (Atlas Assistant)

The conversational layer utilizes OpenAI's GPT models to provide a solution-oriented assistant. It supports both standard JSON responses and Server-Sent Events (SSE) for streaming text.

Implementation Details

Configuration and Security

• Model: Defaults to gpt-4o if OPENAI_MODEL is not provided.
• Authentication: Protected by apiKeyAuth middleware requiring the x-api-key header.
• Prompting: Uses a hardcoded SYSTEM_PROMPT defining Atlas as a professional assistant for scheduling, workforce, and payments.

Sources: src/services/atlasAI.js:15-22, src/middleware/auth.js:9-15, server.js:42

API Endpoints

The system exposes endpoints for both internal orchestration and external chat interfaces.

Endpoint	Method	Purpose
/api/chat	POST	Standard non-streaming chat interface.
/api/chat/stream	POST	SSE streaming chat interface.
/api/health	GET	Checks if AI services are configured and reachable.
/api/v1/ai/pricing/dynamic	POST	Internal endpoint for pricing calculations.

Sources: src/routes/chat.js:12-45, server.js:30-36, backend/src/app.ts:223

Summary

The Atlas AI Orchestration Layer provides the platform's "intelligence" by bridging raw operational data with machine learning models. Through the AtlasAIService, the platform automates complex decisions like cleaner dispatching and dynamic pricing, while the conversational components offer a natural language interface for system users. The inclusion of heuristic fallbacks ensures that core business functions remain operational even during AI provider outages.