Directory Structure

Relevant source files

The following files were used as context for generating this wiki page:

• PROJECT_STRUCTURE_GIT.md
• README.md
• QUICK_START.md
• Ai-Assistant-v2/auth-service/server.js
• ai-assistant-react/src/components/Chat/ChatInterface.jsx

The AI Assistant project is organized into a 3-tier REST API architecture, split across three primary top-level directories. This structure facilitates the isolation of concerns: the frontend user interface, the Node.js orchestration and authentication layer, and the Python-based machine learning service. The project utilizes a microservices-style approach where each directory corresponds to a service running on a specific port.

Sources: README.md:10-38, PROJECT_STRUCTURE_GIT.md:11-133

Project Organization Overview

The repository is divided into functional blocks that handle specific parts of the application lifecycle.

Directory	Purpose	Primary Port	Tech Stack
ai-assistant-react/	Modern React Frontend (Vite)	5173 / 3000	React 19, Vite, Axios
Ai-Assistant-v2/	Node.js Backend & Auth Service	5001	Express 5, Mongoose, JWT
backend/	Python AI & ML Service	5000	Flask, Llama-cpp, Gemini API

Sources: README.md:144-168, PROJECT_STRUCTURE_GIT.md:20-23

Service Interaction Flow

The following diagram illustrates how the directory structure reflects the data flow between services.

Core Directories

1. ai-assistant-react/ (Frontend)

This directory contains the modern React application built with Vite. It serves as the primary user interface for chat, authentication, and memory management.

• src/components/: Organized by feature, containing Auth/ for login/registration and Chat/ for the main interface.
• src/services/: Contains api.js for handling Axios client configurations.
• public/: Static assets like icons and SVGs.

Sources: PROJECT_STRUCTURE_GIT.md:20-39, ai-assistant-react/src/components/Chat/ChatInterface.jsx:1-15

2. Ai-Assistant-v2/auth-service/ (Node.js API)

This directory houses the "orchestration layer." It manages user sessions, persistent storage in MongoDB, and mediates communication between the frontend and the AI backend.

• models/: Defines Mongoose schemas for User, Conversation, and Memory.
• routes/: Express routers for ai.js (orchestration), conversations.js, and memories.js.
• middleware/: Logic for JWT auth.js and rateLimiter.js.
• services/: Integration logic such as aiService.js (Python client) and vectorService.js (similarity search).

Sources: PROJECT_STRUCTURE_GIT.md:43-66, Ai-Assistant-v2/auth-service/server.js:144-150

3. backend/ (Python AI Service)

The Python service handles heavy computation, including natural language processing and local model inference.

• modules/ml/: Specific wrappers for AI models like phi3_model.py and gemini_model.py.
• modules/voice/: Sub-modules for voice recognition and text-to-speech.
• services/: High-level logic for embedding_service.py and memory_extraction_service.py.
• ml_config/: Configuration files for AI model parameters.

Sources: PROJECT_STRUCTURE_GIT.md:85-133, README.md:148-154

Execution and Utility Files

The root directory contains scripts for managing the lifecycle of the multi-service architecture.

File	Description
start_app.bat	Automates the startup of MongoDB, Python AI, Node.js, and React.
START_MONGODB.bat	Launches the local MongoDB database instance.
.gitignore	Specifies files ignored by Git, including .venv, node_modules, and .env.
PROJECT_STRUCTURE_GIT.md	Provides a legend and status tree of the repository files.

Sources: start_app.bat:1-12, PROJECT_STRUCTURE_GIT.md:1-15, QUICK_START.md:1-10

Startup Sequence Diagram

The startup script follows a strict dependency order to ensure service availability.

Summary

The directory structure follows a clear separation of technologies. The ai-assistant-react/ folder manages the client-side state, while Ai-Assistant-v2/auth-service/ acts as the secure gateway and data manager. The backend/ directory serves as a specialized compute node for AI tasks. This modular approach allows individual components to be updated, such as swapping the local Phi-3 model in the backend/ without affecting the authentication logic in the Node.js layer.

Sources: README.md:138-168, PROJECT_STRUCTURE_GIT.md:135-145