Introduction
Relevant source files
The following files were used as context for generating this wiki page:
The AI Assistant is a full-stack, intelligent conversational platform designed to provide a production-ready environment for interacting with multiple AI models. It features a modern 3-tier architecture that integrates a React frontend, a Node.js orchestration and authentication service, and a Python-based machine learning service. The platform distinguishes itself through a "dual AI" approach—utilizing both local models (Phi-3) and cloud APIs (Google Gemini)—complemented by an intelligent vector-based memory system that persists and retrieves relevant user facts during conversations.
Sources: README.md:1-10, PROJECT_STRUCTURE_GIT.md:1-5
System Architecture
The project is structured into three distinct services that communicate via REST APIs. This decoupling allows for independent scaling of the user management logic and the resource-intensive AI inference logic.
- Frontend (React/Vite): Provides a real-time chat interface, user authentication UI, and management tools for conversation history and stored memories.
- Orchestration Service (Node.js): Handles JWT-based authentication, manages the MongoDB database (Users, Conversations, Memories), and orchestrates the flow of data between the user and the AI models.
- AI Service (Python/Flask): Executes the heavy lifting of AI inference, including local GGUF model execution, API calls to Gemini, intent detection, sentiment analysis, and embedding generation for the memory system.
Sources: README.md:13-43, PROJECT_STRUCTURE_GIT.md:15-135
High-Level Component Interaction
The following diagram illustrates how a user request flows through the three tiers of the application:
The system uses a top-down flow where the Node.js service acts as the central gateway for all data persistence and AI requests.
Sources: README.md:13-39, Ai-Assistant-v2/auth-service/server.js:141-160
Key Features and Components
Dual AI Models & Intelligence
The platform allows users to switch between models based on their needs. The local Phi-3 model offers privacy and speed, while the Gemini API provides advanced reasoning. The system further enhances these interactions through automated analysis of every message.
| Component | Description | Source File |
|---|---|---|
| Phi-3 (Local) | Privacy-focused, offline-capable model running via llama-cpp-python. | README.md:49-50 |
| Gemini (API) | Advanced reasoning and internet-connected knowledge via Google API. | backend/modules/ml/gemini_model.py |
| Intent Detection | Analyzes user messages to identify commands, questions, or notes. | README.md:65 |
| Sentiment Analysis | Detects emotional tone (Positive, Negative, Neutral) for context. | Ai-Assistant-v2/auth-service/server.js:255-265 |
Sources: README.md:46-68, Ai-Assistant-v2/auth-service/server.js:255-280
Memory & Context Management
The "Intelligent Memory System" is a core innovation of the platform. It doesn't just store logs; it extracts facts and retrieves them using vector similarity.
- Memory Extraction: The Python service extracts key facts from conversations.
- Importance Scoring: Memories are assigned scores; only those above a threshold (default 0.6) are stored.
- Vector Retrieval: When a user sends a message, the system generates an embedding to find the top 5 most relevant past memories to inject into the current AI prompt.
Sources: Ai-Assistant-v2/auth-service/routes/ai.js:11-30, Ai-Assistant-v2/auth-service/services/aiService.js:47-55, Ai-Assistant-v2/auth-service/server.js:235-250
Execution Flow: Chat Request
When a user sends a message through the ChatInterface.jsx, the system executes a complex orchestration sequence to ensure the AI has full context of the user's history.
This sequence ensures that every AI response is grounded in both the immediate conversation history (last 10 messages) and long-term user memories.
Sources: Ai-Assistant-v2/auth-service/routes/ai.js:20-80, Ai-Assistant-v2/auth-service/server.js:220-290, ai-assistant-react/src/components/Chat/ChatInterface.jsx:75-125
Configuration and Setup
The project relies on environment variables and specific port assignments to facilitate local development and inter-service communication.
Service Ports
- Frontend: Port 3000 (Vite)
- Node.js API: Port 5001
- Python ML: Port 5000
- MongoDB: Port 27017
Sources: QUICK_START.md:14-18, PROJECT_STRUCTURE_GIT.md:15-100
Core API Endpoints (V1)
The orchestration layer exposes several critical endpoints for the frontend:
| Endpoint | Method | Description |
|---|---|---|
/api/v1/auth/login | POST | Authenticates user and sets HTTP-only JWT cookie. |
/api/v1/ai/chat | POST | Primary entry point for AI interaction. |
/api/v1/memories/train | POST | Triggers batch extraction of facts from recent history. |
/api/v1/conversations | GET | Retrieves list of user's past chat sessions. |
Sources: README.md:105-135, Ai-Assistant-v2/auth-service/server.js:125-220
Summary
The AI Assistant provides a comprehensive framework for building context-aware conversational agents. By combining local and cloud-based AI with a persistent, vector-searchable memory layer, it bridges the gap between simple chatbots and personalized digital assistants. The modular 3-tier structure ensures that developers can easily swap models or database backends without disrupting the entire ecosystem.
Sources: README.md:1-10, QUICK_START.md:1-10