Data Flow & Communication
Relevant source files
The following files were used as context for generating this wiki page:
The AI Assistant platform utilizes a 3-tier REST API architecture to manage communication between the user interface, the orchestration layer, and the specialized AI services. Data flow is primarily driven by asynchronous HTTP requests, with a central Node.js service acting as the primary orchestrator for authentication, database persistence, and vector-based memory retrieval.
The system is designed to handle complex conversational flows by integrating dual AI models (local Phi-3 and remote Gemini API), maintaining conversation history in MongoDB, and performing intent detection and sentiment analysis on user inputs.
Sources: README.md:10-38, Ai-Assistant-v2/auth-service/server.js:189-250
System Architecture & Tier Communication
The platform is divided into three distinct layers that communicate over dedicated network ports:
- Frontend (Port 3000/5173): A React-based UI that handles user interactions and displays chat messages.
- Auth & Orchestration (Port 5001): A Node.js Express service that manages JWT authentication, MongoDB transactions, and coordinates requests to the AI backend.
- AI Service (Port 5000): A Python Flask service responsible for ML model inference (Phi-3/Gemini), embedding generation, and text analysis.
The following diagram illustrates the high-level data flow between these components:
Request Lifecycle: Chat Processing
When a user sends a message, the system follows a specific sequence of operations to generate a contextually aware response. The orchestration service fetches the last 10 messages for context and performs a vector search to find relevant user memories before querying the AI models.
Sequence of a Chat Request
- UI Submission: User input is sent via
POST /api/v1/ai/chat. - Authentication:
authMiddlewareverifies the JWT in the HTTP-only cookie. - Context Retrieval: The service loads the conversation from MongoDB and fetches up to 5 relevant memories using the
vectorService. - AI Orchestration: The
aiServiceforwards the prompt, context, and memories to the Python backend. - Model Inference: The Python service executes either the local Phi-3 model or the Gemini API.
- Persistence: The resulting response, intent, and sentiment are saved back to the conversation record.
AI Service Communication Interface
The Node.js Orchestrator interacts with the Python AI Service through the AIService class. This service abstracts the HTTP logic and implements retry mechanisms to handle potential service downtime.
Key API Endpoints (Internal)
| Endpoint | Method | Payload Description | Source |
|---|---|---|---|
/generate | POST | Includes prompt, model type, context array, and memory facts. | server.js:219 |
/extract-memory | POST | Sends message history to identify new facts for storage. | aiService.js:46 |
/embed | POST | Generates 384-dimensional vector embeddings for text. | README.md:155 |
/health | GET | Connectivity check between Node.js and Python. | server.js:264 |
Service Retry Logic
The orchestrator implements a retry loop for communication with the Python service, attempting the request up to 3 times with a 500ms delay between failures.
Sources: Ai-Assistant-v2/auth-service/server.js:63-81, Ai-Assistant-v2/auth-service/services/aiService.js:18-38
Data Models & Schema Relationships
Data is structured in MongoDB to support multi-user isolation and persistent memory. The User model tracks global settings (like the preferred AI model), while Conversation and Memory models handle historical data.
Memory & Context Flow
The system distinguishes between Short-term Context (the last 10 messages in the current thread) and Long-term Memory (facts extracted across all conversations).
Context Building Logic
When preparing a request for the Python AI service, the Node.js layer performs the following:
- Slicing: Extracts exactly the last 10 messages from the
messagesarray in theConversationdocument. - Mapping: Transforms the messages into a simplified format:
[{ role: 'user', text: '...' }]. - Vector Search: If enabled, searches the
Memorycollection for facts relevant to the current user's prompt.
Sources: Ai-Assistant-v2/auth-service/routes/ai.js:48-60, Ai-Assistant-v2/auth-service/server.js:209-224
Summary
Data flow in the AI Assistant platform is a coordinated effort between a reactive frontend and a two-stage backend. The Node.js orchestrator serves as the "source of truth" for user data and history, while the Python service provides the computational power for language modeling and NLP tasks. This separation allows the platform to switch between local (Phi-3) and cloud-based (Gemini) models seamlessly while maintaining a consistent user experience.
Sources: README.md:10-45, Ai-Assistant-v2/auth-service/server.js:263-275