Atlas Chat Assistant
Relevant source files
The following files were used as context for generating this wiki page:
Atlas Chat Assistant provides an AI-powered interface for the AtlasCleanAI Enterprise platform. It facilitates cleaning operations management by helping users with crew scheduling, workforce assignments, service requests, and billing inquiries. The system integrates with OpenAI's ChatGPT to deliver both full responses and Server-Sent Events (SSE) for streaming interactions.
Sources: README.md:92-95, src/services/atlasAI.js:3-12
System Architecture
The Atlas Chat Assistant operates as a Node.js-based service within the backend API tier. It consists of a web-based frontend, a set of Express routes for handling requests, and a specialized service layer that communicates with the OpenAI API.
Component Overview
- Frontend (Web Portal): A browser-based UI that manages message history, user input, and real-time status indicators.
- Chat Router: Defines endpoints for standard JSON responses and SSE streaming.
- AtlasAI Service: Manages the OpenAI client, system prompts, and communication logic.
- Validation Layer: Enforces strict constraints on message length, entry counts, and total content size.
The following diagram illustrates the request flow from the user interface to the AI provider:
API Endpoints
The system exposes specific endpoints for chat interactions and service monitoring. All chat-related endpoints are protected by rate limiting and optional API key authentication.
Endpoint Summary
| Method | Endpoint | Description | Auth Required |
|---|---|---|---|
| POST | /api/chat | Receives conversation history and returns a full JSON reply. | Yes |
| POST | /api/chat/stream | Receives conversation history and returns an SSE stream. | Yes |
| GET | /api/health | Returns the configuration status of the AI service. | No |
Sources: server.js:37-47, src/routes/chat.js:10-60
Message Constraints
To ensure stability and manage costs, the system enforces the following limits on all incoming requests:
- Maximum Entries: 20 messages per request.
- Message Length: 4,000 characters per individual message.
- Total Content: 16,000 characters total across the message array.
- Roles: Only "user" and "assistant" roles are accepted in the message history.
Sources: src/validation/chat.js:1-10, README.md:102
Data Flow and Interaction
The interaction flow varies based on whether the client requests a standard response or a stream.
Sequence Diagram: Streaming Chat
This diagram shows how the system handles Server-Sent Events for real-time text delivery:
Request Structure
Requests must include a messages array containing the conversation history. The server automatically prepends a system prompt that defines Atlas's persona as a professional, solution-oriented enterprise assistant.
{
"messages": [
{ "role": "user", "content": "How do I assign a crew to a new booking?" }
]
}
Sources: src/routes/chat.js:12-15, src/services/atlasAI.js:3-12
Configuration and Security
The assistant requires specific environment variables to function. If ATLAS_API_KEY is set, the server enforces its presence in the x-api-key header for all chat requests.
Environment Variables
| Variable | Requirement | Default | Description |
|---|---|---|---|
OPENAI_API_KEY | Required | None | Key for OpenAI API access. |
OPENAI_MODEL | Optional | gpt-4o | Specifies the ChatGPT model version. |
ATLAS_API_KEY | Optional | None | Enables mandatory API-key authentication. |
PORT | Optional | 3000 | Port for the backend server. |
Sources: README.md:104-108, server.js:9-10
Security Controls
- Rate Limiting: The
/api/chatroute is limited to 30 requests per minute to prevent abuse. - Payload Limits: Express JSON parsing is restricted to a
64kblimit. - Header Protection: The system uses
helmetto secure HTTP headers and disables thex-powered-byheader.
Sources: server.js:13-35, backend/src/app.ts:160-165
Summary
The Atlas Chat Assistant serves as the intelligence layer for the platform, enabling users to interact with complex cleaning management systems through natural language. By utilizing structured validation and secure service-to-service communication, it provides a robust interface for scheduling, workforce management, and service optimization.