Troubleshooting & Logging
Relevant source files
The following files were used as context for generating this wiki page:
The Troubleshooting and Logging system in the AI Assistant platform is designed to provide visibility into the multi-tier architecture, ensuring developers and users can diagnose issues across the React frontend, Node.js orchestration layer, and Python AI service. It encompasses automated startup health checks, structured backend logging, and proactive error handling within the user interface.
Effective troubleshooting is facilitated through centralized startup scripts that perform environment validation and service cleanup, while logging utilities ensure that runtime events—such as intent detection and sentiment analysis—are recorded for audit and debugging.
Sources: README.md, start_app.bat, backend/utils/logger.py
Automated Diagnostic & Startup Flow
The project utilizes start_app.bat to manage the lifecycle of all services. Before initialization, the script performs an "Auto-cleanup" to terminate zombie processes and verifies the availability of the MongoDB database.
Service Health Validation
The startup sequence implements a retry-based health check mechanism. It uses PowerShell commands to query the /health and /api/v1/health endpoints of the Python and Node.js services respectively before proceeding to launch the frontend.
The diagram shows the sequential health-check dependencies required for a successful platform launch.
Sources: start_app.bat:10-75, QUICK_START.md:5-20
Logging Architecture
Backend Python Logging
The Python backend employs a dedicated logger utility to track ML operations and API request status. Significant events like intent classification and sentiment analysis results are logged to the console or log files.
| Level | Usage Context | Source Component |
|---|---|---|
| Info | Successful model initialization, Intent detection results | ml_service.py, gemini_model.py |
| Error | Failed API calls, model loading errors, internal server errors | routes.py, logger.py |
Sources: backend/modules/ml/routes.py:34, 62, backend/modules/ml/gemini_model.py:31, 72
Node.js Service Monitoring
The Node.js Auth Service logs connection statuses for the database and external service calls. It specifically implements retry logic for communicating with the Python AI service, logging each attempt and failure detail.
// Retry logic logging in Node.js
const callPythonService = async (endpoint, payload, retries = 3) => {
for (let i = 0; i < retries; i++) {
try {
console.log(`[Attempt ${i + 1}/${retries}] Calling ${PYTHON_AI_URL}${endpoint}`);
const response = await axios.post(`${PYTHON_AI_URL}${endpoint}`, payload);
return response;
} catch (error) {
console.error(`[Attempt ${i + 1}/${retries}] Error:`, {
message: error.message,
status: error.response?.status
});
// ... retry delay ...
}
}
};
Sources: Ai-Assistant-v2/auth-service/server.js:65-83
Troubleshooting Common Issues
The platform documentation identifies several recurring failure states and provides specific remediation steps based on observed symptoms.
Connectivity & Service Failures
| Symptom | Probable Cause | Resolution |
|---|---|---|
| "AI Service Unavailable" | Python service OOM or crashed | Close windows and run start_app.bat; if persistent, run FIX_MEMORY.bat |
| Stuck on "Signing in..." | MongoDB is not active | Execute START_MONGODB.bat before launching the app |
| Slow Performance | Duplicate zombie processes | End all python.exe and node.exe in Task Manager |
Sources: QUICK_START.md:23-45, README.md:162-185
Frontend Error Handling
The React ChatInterface captures network failures during chat interactions and renders them directly within the message stream to inform the user of backend unavailability.
Diagnostic Endpoints
Both backend services expose health check routes used by the monitoring scripts and for manual verification.
| Endpoint | Method | Service | Description |
|---|---|---|---|
/health | GET | Python AI | Returns model and service readiness |
/api/v1/health | GET | Node.js Auth | Returns status of DB connection and Python bridge |
Sources: README.md:144-150, Ai-Assistant-v2/auth-service/server.js:255-267
The logging and troubleshooting framework ensures that the complex interactions between the local LLM (Phi-3), the external Gemini API, and the MongoDB vector store remain transparent and maintainable. By combining automated script-based checks with structured runtime logging, the system provides a robust path for resolving environment-specific failures.