High-Level Architecture

The AI Assistant is built as a production-ready, full-stack intelligent chat application utilizing a 3-tier REST API architecture. The system is designed to provide real-time conversational capabilities by orchestrating user management, multi-model AI inference, and persistent memory management across decoupled services.

The architecture comprises three primary layers:

1. Frontend (React/Vite): A modern user interface for real-time chat, authentication, and memory visualization.
2. Auth & Orchestration Service (Node.js/Express): A middleware layer handling JWT authentication, session persistence in MongoDB, and vector-based memory retrieval.
3. AI Service (Python/Flask): A specialized backend for heavy-duty ML tasks, including local model inference (Phi-3), external API integration (Gemini), and NLP utilities like sentiment analysis and memory extraction.

Sources: README.md:4-40, PROJECT_STRUCTURE_GIT.md:15-85

System Component Overview

The following diagram illustrates the relationship and communication protocols between the three major tiers.

The system uses a tiered request flow where the frontend never communicates directly with the AI models, ensuring security and centralized logging at the Node.js layer.
Sources: README.md:7-38, Ai-Assistant-v2/auth-service/server.js:15-22

Tier Specifications

Sources: README.md:183-205, PROJECT_STRUCTURE_GIT.md:15-85

Core Data Flows

Chat Request Orchestration

When a user sends a message, the Node.js Orchestration service performs a multi-step workflow to enrich the prompt before it reaches the AI models.

The Node.js service acts as the central brain, fetching the last 10 messages for context and using a vector service to retrieve up to 5 relevant user memories to provide "long-term" awareness to the LLM.
Sources: Ai-Assistant-v2/auth-service/routes/ai.js:11-85, Ai-Assistant-v2/auth-service/server.js:174-250

Memory Extraction and Persistence

The system features an automated memory loop. AI responses generate "memory candidates" which are filtered based on importance scores before being persisted.

• Extraction: The Python service analyzes conversation text to find facts.
• Thresholding: The Node.js service filters candidates based on a MEMORY_IMPORTANCE_THRESHOLD (default 0.6).
• Storage: Verified memories are stored in MongoDB with importance scores and tags.

Sources: Ai-Assistant-v2/auth-service/services/aiService.js:4-60, backend/routes/ai_routes.py:12-65

Service Architectures

Node.js Auth & Orchestration

This service manages the application's state. It provides a RESTful API V1 that secures access through HTTP-only JWT cookies.

• Models: User (settings/auth), Conversation (message history), Memory (vector facts).
• Key Services: vectorService.js for similarity search and aiService.js as the internal client for the Python backend.
• Security: Implements rateLimiter.js across auth, chat, and memory endpoints.

Sources: Ai-Assistant-v2/auth-service/server.js:24-110, Ai-Assistant-v2/auth-service/routes/ai.js:10-20

Python AI Backend

The AI service is purely functional and stateless regarding user data, receiving all necessary context via each request's payload.

The Python service exposes specialized endpoints for generation, extraction, and embedding, allowing the Node.js layer to modularly call AI capabilities.
Sources: backend/routes/ai_routes.py:11-100, PROJECT_STRUCTURE_GIT.md:87-130

Conclusion

The high-level architecture effectively separates concerns: the React frontend focuses on user experience, the Node.js layer manages business logic and security, and the Python service optimizes AI execution. This decoupling allows the system to support diverse AI models (local and cloud) while maintaining a consistent user memory across conversations.