Automation Scripts
Relevant source files
The following files were used as context for generating this wiki page:
The automation scripts in this project are designed to streamline the deployment and local execution of a multi-tier AI assistant application. These scripts handle process management, database verification, and service orchestration, ensuring that the Python ML backend, Node.js authentication service, and React frontend are initialized in the correct order with appropriate environment checks.
Sources: README.md:90-112, start_app.bat:1-10
Service Orchestration Logic
The primary automation is handled via Windows Batch files that coordinate the lifecycle of the application's three main services. The scripts implement a sequential dependency flow where each service must pass a health check before the next one is initiated.
Startup Workflow
The orchestration logic follows a strict hierarchy to ensure data persistence and backend availability before the UI is presented to the user.
The diagram above illustrates the sequential execution and health verification loops implemented in the automation layer.
Sources: start_app.bat:12-92, QUICK_START.md:5-15
Script Components and Descriptions
The project utilizes specific scripts for targeted administrative tasks and general orchestration.
| Script Name | Purpose | Key Actions |
|---|---|---|
start_app.bat | Main Orchestrator | Kills zombie processes, checks MongoDB, starts Python/Node/React, opens browser. |
START_MONGODB.bat | Database Manager | Initializes the local MongoDB instance (requires Admin privileges). |
FIX_MEMORY.bat | Troubleshooting | Addressed when Python service crashes due to memory exhaustion. |
CLEANUP.bat | Maintenance | Manual trigger to terminate duplicate python.exe and node.exe processes. |
Sources: PROJECT_STRUCTURE_GIT.md:20-25, QUICK_START.md:5-40, start_app.bat:12-16
Implementation Details
Process Cleanup and Environment Preparation
Before starting services, start_app.bat performs an auto-cleanup by forcibly terminating any existing python.exe or node.exe instances. This prevents port conflicts and memory leaks caused by "zombie" processes from previous sessions.
:: STEP 1: Auto-cleanup (kill zombies)
echo [CLEANUP] Killing old processes...
taskkill /F /IM python.exe >nul 2>&1
taskkill /F /IM node.exe >nul 2>&1
timeout /t 2 /nobreak >nul
Sources: start_app.bat:12-17
Health Check Mechanisms
The automation scripts utilize PowerShell commands to perform non-blocking HTTP requests against service health endpoints. This ensures that the Node.js Auth service (Port 5001) does not attempt to start until the Python AI service (Port 5000) is fully initialized and responding.
- Python Health Check:
http://localhost:5000/health - Node Health Check:
http://localhost:5001/api/v1/health
:wait_python
powershell -NoLogo -NoProfile -Command "try { Invoke-WebRequest -UseBasicParsing -Uri http://localhost:5000/health -TimeoutSec 3 | Out-Null; exit 0 } catch { exit 1 }"
if not "%ERRORLEVEL%"=="0" (
set /a __PY_RETRY+=1
if %__PY_RETRY% GEQ 20 (
goto :eof
)
timeout /t 3 /nobreak >nul
goto :wait_python
)
Sources: start_app.bat:34-48, Ai-Assistant-v2/auth-service/server.js:239-253
Troubleshooting via Automation
The scripts are designed to provide feedback on common failure points.
Common Failure Indicators
- Admin Rights:
START_MONGODB.batrequires elevated permissions to initiate the database service. - Model Availability: The Python service startup sequence will fail if the Phi-3 GGUF model is missing from
backend/models/phi3/. - Connection Errors: If
start_app.batdetects MongoDB is not running (checked viatasklist), it halts execution to prevent application-wide failures.
Sources: QUICK_START.md:21-35, start_app.bat:20-30
Conclusion
Automation scripts serve as the operational backbone of the AI Assistant platform, abstracting the complexity of managing a distributed three-tier architecture. By integrating health checks and automated cleanup, these scripts provide a reliable "one-click" entry point for developers and users alike.