Technology Stack
Relevant source files
The following files were used as context for generating this wiki page:
The AI Assistant platform is built using a modern 3-tier REST API architecture designed to handle intelligent conversational flows, user authentication, and multi-model AI orchestration. The stack is divided into a React-based frontend, a Node.js orchestration and authentication service, and a Python-based machine learning service.
Sources: README.md:9-12, README.md:231-255
System Architecture Overview
The platform operates through three distinct services communicating over REST:
- Frontend: A React application serving as the user interface.
- Auth & Orchestration: A Node.js/Express service managing security, database persistence, and vector-based memory logic.
- ML Service: A Python/Flask service managing local and cloud-based AI model inference.
The architecture facilitates a clear separation of concerns, where the Node.js service acts as the central hub for business logic and the Python service focuses on heavy computational ML tasks.
Sources: README.md:14-46, Ai-Assistant-v2/auth-service/server.js:12-14
Core Technologies
Frontend Stack
The frontend is built with React 19 and bundled using Vite. It utilizes a modern CSS architecture with custom variables for theme management.
| Technology | Purpose | Implementation Details |
|---|---|---|
| React 19 | UI Framework | Component-based architecture for Chat and Auth |
| Vite | Build Tool | Fast HMR and optimized production builds |
| Axios | HTTP Client | Communicates with Auth Service (Port 5001) |
| React Router | Navigation | Manages routing between Chat and Login/Register |
| Zustand | State Mgmt | Global state management (dependency listed in package.json) |
Sources: ai-assistant-react/package.json:14-20, README.md:233-238
Backend Orchestration (Node.js)
The middle tier is an Express server responsible for securing the application and managing the database.
- Authentication: Implemented using JSON Web Tokens (JWT) with HTTP-only cookies and bcryptjs for password hashing.
- Database: Uses MongoDB via the Mongoose ODM. It stores Users, Conversations, and Memories.
- Security: Includes rate limiting via
express-rate-limitto prevent abuse of AI and Auth endpoints.
Sources: Ai-Assistant-v2/auth-service/package.json:11-23, Ai-Assistant-v2/auth-service/server.js:34-45, README.md:50-55
AI & Machine Learning Service (Python)
The ML tier is a Flask application that serves as the interface for AI model inference.
- Dual Models: Supports Phi-3 (local GGUF via
llama-cpp-python) and Gemini (viagoogle-generativeai). - NLP Utilities: Uses
sentence-transformersfor generating 384-dimensional text embeddings andscikit-learnfor similarity computations. - Memory Management: Extracts facts and generates importance scores for conversation context.
Sources: README.md:246-253, README.md:126-135, PROJECT_STRUCTURE_GIT.md:123-145
Data Models and Persistence
The system uses MongoDB to persist user state and conversational history. The Node.js service defines three primary schemas:
| Model | Description | Key Fields |
|---|---|---|
| User | User account and preferences | username, password, settings (model, theme) |
| Conversation | Chat history threads | userId, messages (role, text, intent, sentiment) |
| Memory | Long-term vector facts | userId, fact, importanceScore, embedding |
Sources: Ai-Assistant-v2/auth-service/server.js:34-45, Ai-Assistant-v2/auth-service/routes/ai.js:25-45, Ai-Assistant-v2/auth-service/routes/memories.js:46-60
Communication Flow
The following sequence diagram illustrates the flow of a single chat request across the stack:
Service Configuration
Environmental variables and service ports are strictly defined across the repository:
- Python AI Service: Port
5000 - Node.js Auth Service: Port
5001 - React Frontend: Port
3000/5173 - MongoDB: Port
27017
Sources: README.md:14-46, Ai-Assistant-v2/auth-service/server.js:12-14
Conclusion
The AI Assistant platform leverages a polyglot approach, using Node.js for robust service orchestration and Python for specialized machine learning tasks. This decoupled architecture allows for efficient scaling and the flexible integration of both local (Phi-3) and cloud (Gemini) AI models while maintaining a persistent, memory-aware user experience.