Node.js API Reference
Relevant source files
The following files were used as context for generating this wiki page:
The Node.js Auth & Orchestration Service acts as the central middleware for the AI Assistant platform. It handles user authentication, manages persistent storage in MongoDB, and orchestrates the data flow between the React frontend and the Python AI service.
This service is responsible for enforcing security via JWT, managing user-specific conversation histories, and maintaining a "memory" system that uses vector embeddings to provide long-term context for AI interactions. It runs on port 5001 by default and provides a RESTful API for all frontend operations.
Sources: Ai-Assistant-v2/auth-service/server.js:10-15, README.md:16-24
Service Architecture
The service follows a 3-tier architecture where it serves as the middle orchestration layer. It communicates with MongoDB for data persistence and a Flask-based Python service for intensive ML tasks such as response generation and embedding creation.
Data Flow Diagram
The following diagram illustrates the request-response flow for a typical chat interaction through the Node.js service.
Authentication API
The authentication system uses JSON Web Tokens (JWT) stored in HTTP-only cookies to manage user sessions securely.
Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/v1/auth/register | POST | Registers a new user with username and password. |
/api/v1/auth/login | POST | Authenticates user and sets an HTTP-only JWT cookie. |
/api/v1/auth/logout | POST | Clears the authentication cookie. |
/api/v1/auth/check | GET | Verifies if the current session is valid. |
Sources: Ai-Assistant-v2/auth-service/server.js:90-149
User Data Model
AI & Conversation Orchestration
The AI endpoints orchestrate complex flows by combining conversation context, user memories, and external AI model calls.
Chat Flow Sequence
This diagram shows the internal logic of the /ai/chat endpoint.
Model Management
The service supports dual models: phi3 (local) and gemini (API). Users can switch models via the following routes:
GET /api/v1/settings/model: Retrieves the active model for the user.POST /api/v1/settings/model: Updates the preferred model in user settings.
Sources: Ai-Assistant-v2/auth-service/routes/ai.js:125-163, Ai-Assistant-v2/auth-service/server.js:192-212
Memory System
The memory system allows the AI to "remember" facts across different conversations. It uses vector embeddings for similarity search.
Memory Data Model
| Field | Type | Description |
|---|---|---|
userId | ObjectId | Reference to the owner of the memory. |
fact | String | The actual information stored. |
importanceScore | Number | Priority of the memory (0.0 to 1.0). |
embedding | Array[Number] | Vector representation for similarity search. |
tags | Array[String] | Categorization labels (e.g., 'extracted'). |
Sources: Ai-Assistant-v2/auth-service/models/Memory.js:3-37
Memory Training Logic
The /api/v1/memories/train endpoint automates memory extraction by processing recent conversations through the Python AI service.
Configuration and Middleware
The service utilizes several middleware components to ensure stability and security.
- Rate Limiting: Separate limiters for authentication (
authLimiter), chat (chatLimiter), and memory operations (memoryLimiter) to prevent abuse. - Retry Logic: The
callPythonServicehelper implements a 3-retry mechanism with exponential backoff for communicating with the AI backend. - CORS: Configured to allow credentials and specific origins (localhost:3000, 5173, etc.).
Sources: Ai-Assistant-v2/auth-service/server.js:16-25, Ai-Assistant-v2/auth-service/server.js:63-82
Conclusion
The Node.js API serves as the backbone of the AI Assistant, providing the necessary glue between the user interface and the machine learning models. By managing stateful conversations and long-term vector memory, it enables a sophisticated, context-aware user experience while maintaining security through standard JWT and rate-limiting practices.