Node.js Service Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Node.js Service, also referred to as the Auth & Orchestration Service, serves as the central middleware of the AI Assistant platform. It handles user authentication, manages the persistent storage of conversations and "memories" in MongoDB, and orchestrates requests between the React frontend and the Python-based AI Service.
The service is built using Express 5 and utilizes a RESTful API architecture to manage user sessions via JWT-based authentication and secure cookies. It acts as a gatekeeper for the AI features, ensuring that chat interactions are personalized, rate-limited, and contextually aware by retrieving relevant historical data before querying the AI models.
Sources: README.md:12-25, Ai-Assistant-v2/auth-service/server.js:1-25
Core Architecture and Data Flow
The Node.js service is positioned as the middle tier in a 3-tier architecture. It communicates with the frontend via HTTP/REST and connects to the Python AI service using an internal REST API with built-in retry logic.
Request Orchestration Flow
When a user sends a message, the service orchestrates a multi-step process:
- Validates the user's JWT token.
- Loads the conversation context (last 10 messages).
- Performs a vector-based similarity search to find relevant user memories.
- Forwards the combined context to the Python AI service.
- Persists the AI's response and any new memory candidates generated during the interaction.
API Implementation
The service exposes several modules via Express routers, primarily focusing on Authentication, AI interactions, Conversations, and Memory management.
Key API Endpoints
| Category | Endpoint | Method | Description |
|---|---|---|---|
| Auth | /api/v1/auth/register | POST | Registers a new user with hashed passwords. |
| Auth | /api/v1/auth/login | POST | Validates credentials and sets an HTTP-only JWT cookie. |
| AI | /api/v1/ai/chat | POST | Main chat orchestration endpoint. |
| Memory | /api/v1/memories/train | POST | Extracts facts from conversations to create memories. |
| Settings | /api/v1/settings/model | POST | Switches the default AI model (Phi-3 or Gemini). |
Sources: README.md:118-145, Ai-Assistant-v2/auth-service/server.js:84-180
Security and Rate Limiting
The service implements multi-layered security including:
- JWT Authentication: Tokens are stored in HTTP-only, secure cookies to prevent XSS-based theft.
- Password Hashing: Utilizes
bcryptjsfor secure password storage. - Rate Limiting: Distinct limiters for different actions (e.g.,
authLimiter,chatLimiter,memoryLimiter).
Sources: Ai-Assistant-v2/auth-service/server.js:11-13, 128-135, Ai-Assistant-v2/auth-service/middleware/auth.js:8-60
Memory and AI Orchestration
The service interacts with a Python backend to perform heavy lifting for AI and ML tasks. The AIService class manages these communications.
AI Service Client Logic
The service includes a retry mechanism for the Python backend to ensure reliability if the AI service is momentarily unavailable.
// Example of retry logic used for Python service calls
const callPythonService = async (endpoint, payload, retries = 3) => {
for (let i = 0; i < retries; i++) {
try {
const response = await axios.post(`${PYTHON_AI_URL}${endpoint}`, payload);
return response;
} catch (error) {
if (i === retries - 1) throw error;
await new Promise(resolve => setTimeout(resolve, 500));
}
}
};
Sources: Ai-Assistant-v2/auth-service/server.js:61-80
Memory Extraction System
The memory system automatically extracts facts from conversation history. It filters these "candidates" based on an importance score threshold (defaulting to 0.6) before persisting them as Memory documents.
Database Schema (MongoDB)
The service defines several Mongoose schemas to maintain user state and conversation history.
| Model | Field | Type | Description |
|---|---|---|---|
| User | username | String | Unique identifier for the user. |
| User | settings | Object | Preferences (theme, defaultModel, voiceEnabled). |
| Memory | fact | String | The extracted information. |
| Memory | importanceScore | Number | Ranking of how useful the memory is for context. |
| Conversation | messages | Array | List of role-based (user/assistant) message objects. |
Sources: Ai-Assistant-v2/auth-service/server.js:29-45, Ai-Assistant-v2/auth-service/routes/ai.js:25-50, Ai-Assistant-v2/auth-service/routes/memories.js:35-50
Conclusion
The Node.js Service acts as the intelligence router and security layer of the platform. By managing the lifecycle of users, conversations, and long-term memories, it enables a stateful AI experience while abstracting the complexities of AI model inference and vector similarity searches from the frontend. Its integration of JWT security, MongoDB persistence, and robust communication with the Python AI service provides a stable backbone for the full-stack application.