Skip to content

V
vidai
Commit cec0be4d authored by Stefy Lanza (nextime / spora )'s avatar Stefy Lanza (nextime / spora )
Browse files
Options

Add comprehensive ASCII art documentation with visual diagrams 

- Add detailed system architecture diagrams to README
- Create visual data flow and usage workflow diagrams
- Enhance docs/architecture.md with process and communication diagrams
- Add cluster architecture visualization with load balancing flows
- Include cross-platform deployment diagrams
- Provide visual representation of inter-process communication
- Document cluster communication protocols with ASCII schemas
parent 9b4a4f65
Pipeline #188 canceled with stages
      Hide whitespace changes
      Inline Side-by-side
      Showing with 340 additions and 10 deletions
      README.md
      View file @ cec0be4d
      ...@@ -2,6 +2,13 @@ ...@@ -2,6 +2,13 @@
      A comprehensive multi-process web-based tool for analyzing images and videos using AI models. Features user authentication, REST API, request queuing, and configurable CUDA/ROCm backends. A comprehensive multi-process web-based tool for analyzing images and videos using AI models. Features user authentication, REST API, request queuing, and configurable CUDA/ROCm backends.
      ```
      ╔══════════════════════════════════════════════════════════════════════════════╗
      ║ Video AI Analysis Tool ║
      ║ Multi-Process • Cross-Platform • Distributed ║
      ╚══════════════════════════════════════════════════════════════════════════════╝
      ```
      ## Features ## Features
      - **User Authentication**: Secure login system with admin and user roles - **User Authentication**: Secure login system with admin and user roles
      ...@@ -17,6 +24,51 @@ A comprehensive multi-process web-based tool for analyzing images and videos usi ...@@ -17,6 +24,51 @@ A comprehensive multi-process web-based tool for analyzing images and videos usi
      - **Configuration Management**: SQLite database for persistent settings and system prompts - **Configuration Management**: SQLite database for persistent settings and system prompts
      - **Self-Contained**: No external dependencies beyond Python and system libraries - **Self-Contained**: No external dependencies beyond Python and system libraries
      ## System Architecture
      ```
      ┌─────────────────────────────────────────────────────────────────────────────┐
      │ System Overview │
      ├─────────────────────────────────────────────────────────────────────────────┤
      │ │
      │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
      │ │ Web UI │ │ REST API │ │ Queue │ │ Database │ │
      │ │ (Flask) │◄──►│ (FastAPI) │◄──►│ Management │◄──►│ (SQLite) │ │
      │ │ │ │ │ │ │ │ │ │
      │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
      │ │
      │ ┌─────────────────────────────────────────────────────────────────────────┐ │
      │ │ Process Architecture │ │
      │ ├─────────────────────────────────────────────────────────────────────────┤ │
      │ │ │ │
      │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
      │ │ │ Backend │ │ Analysis │ │ Training │ │ Queue │ │ │
      │ │ │ Process │◄──►│ Worker │ │ Worker │ │ Manager │ │ │
      │ │ │ │ │ (CUDA) │ │ (ROCm) │ │ │ │ │
      │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
      │ │ │ │
      │ └─────────────────────────────────────────────────────────────────────────┘ │
      │ │
      │ ┌─────────────────────────────────────────────────────────────────────────┐ │
      │ │ Cluster Architecture │ │
      │ ├─────────────────────────────────────────────────────────────────────────┤ │
      │ │ │ │
      │ │ ┌─────────────┐ ┌─────────────┐ │ │
      │ │ │ Cluster │◄──────────────────►│ Worker │ │ │
      │ │ │ Master │ Load Balancing │ Node │ │ │
      │ │ │ │◄──────────────────►│ │ │ │
      │ │ └─────────────┘ └─────────────┘ │ │
      │ │ │ │ │ │
      │ │ └────────────────────────────────┼───────────────────────────────┘ │
      │ │ ▼ │ │
      │ │ ┌─────────────────────┐ │ │
      │ │ │ Distributed │ │ │
      │ │ │ Processing │ │ │
      │ │ └─────────────────────┘ │ │
      │ └─────────────────────────────────────────────────────────────────────────┘ │
      └─────────────────────────────────────────────────────────────────────────────┘
      ```
      ## Platform Support ## Platform Support
      This application is designed to work on both **Linux** and **Windows**: This application is designed to work on both **Linux** and **Windows**:
      ...@@ -52,8 +104,87 @@ This application is designed to work on both **Linux** and **Windows**: ...@@ -52,8 +104,87 @@ This application is designed to work on both **Linux** and **Windows**:
      ``` ```
      3. **Access Web Interface**: 3. **Access Web Interface**:
      - Open http://localhost:5000 - Open http://localhost:5000
      - Login with admin/admin (change password after first login) - Login with admin/admin (change password after first login)
      ## Data Flow Architecture
      ```
      ┌─────────────────────────────────────────────────────────────────────────────┐
      │ Data Flow Diagram │
      ├─────────────────────────────────────────────────────────────────────────────┤
      │ │
      │ User Request ──┐ │
      │ │ │
      │ ┌─────────────▼─────────────┐ ┌─────────────┐ ┌─────────────┐ │
      │ │ Web Interface │ │ Backend │ │ Queue │ │
      │ │ (Authentication) │───►│ Routing │───►│ Management │ │
      │ │ │ │ │ │ │ │
      │ └─────────────┬─────────────┘ └─────────────┘ └──────┬──────┘ │
      │ │ │ │
      │ │ │ │
      │ ▼ ▼ │
      │ ┌─────────────┴─────────────┐ ┌─────────────┴─────────────┐ │
      │ │ REST API Response │ │ Worker Processing │ │
      │ │ (JSON/WebSocket) │◄───│ (CUDA/ROCm/Analysis) │ │
      │ │ │ │ │ │
      │ └───────────────────────────┘ └───────────────────────────┘ │
      │ │
      │ ┌─────────────────────────────────────────────────────────────────────────┐ │
      │ │ Cluster Data Flow │ │
      │ ├─────────────────────────────────────────────────────────────────────────┤ │
      │ │ │ │
      │ │ Master Node Worker Node │ │
      │ │ ┌─────────────┐ ┌─────────────┐ │ │
      │ │ │ Load │◄─────────────────►│ Process │ │ │
      │ │ │ Balancer │ │ Queue │ │ │
      │ │ └─────────────┘ └─────────────┘ │ │
      │ │ ▲ ▲ │ │
      │ │ │ │ │ │
      │ │ └───────────────┬────────────────┘ │ │
      │ │ │ │ │
      │ │ ┌────────▼────────┐ │ │
      │ │ │ Results │ │ │
      │ │ │ Aggregation │ │ │
      │ │ └─────────────────┘ │ │
      │ └─────────────────────────────────────────────────────────────────────────┘ │
      └─────────────────────────────────────────────────────────────────────────────┘
      ```
      ## Usage Workflow
      ```
      ┌─────────────────────────────────────────────────────────────────────────────┐
      │ Usage Workflow │
      ├─────────────────────────────────────────────────────────────────────────────┤
      │ │
      │ 1. Setup Environment 2. Start Services │
      │ ┌─────────────────────────────────┐ ┌─────────────────────────────────┐ │
      │ │ ./setup.sh cuda │ │ ./start.sh cuda │ │
      │ │ (Linux/macOS) │ │ (Linux/macOS) │ │
      │ │ │ │ │ │
      │ │ setup.bat cuda │ │ start.bat cuda │ │
      │ │ (Windows) │ │ (Windows) │ │
      │ └─────────────────────────────────┘ └─────────────────────────────────┘ │
      │ │
      │ 3. Access Web Interface 4. Process Media │
      │ ┌─────────────────────────────────┐ ┌─────────────────────────────────┐ │
      │ │ http://localhost:5000 │ │ • Upload images/videos │ │
      │ │ │ │ • Configure analysis │ │
      │ │ Login: admin/admin │ │ • Monitor progress │ │
      │ │ (change password!) │ │ • View results │ │
      │ └─────────────────────────────────┘ └─────────────────────────────────┘ │
      │ │
      │ 5. API Integration 6. Cluster Scaling │
      │ ┌─────────────────────────────────┐ ┌─────────────────────────────────┐ │
      │ │ POST /api/analyze │ │ • Add worker nodes │ │
      │ │ Authorization: Bearer <token> │ │ • Automatic load balancing │ │
      │ │ │ │ • Monitor cluster health │ │
      │ │ Real-time results via WebSocket │ │ • Scale processing capacity │ │
      │ └─────────────────────────────────┘ └─────────────────────────────────┘ │
      │ │
      └─────────────────────────────────────────────────────────────────────────────┘
      ```
      ## User Management ## User Management
      ......
      docs/architecture.md
      View file @ cec0be4d
      ...@@ -4,8 +4,52 @@ ...@@ -4,8 +4,52 @@
      The Video AI Analysis Tool is designed as a multi-process application to provide scalability, fault isolation, and flexible backend selection for GPU acceleration. The Video AI Analysis Tool is designed as a multi-process application to provide scalability, fault isolation, and flexible backend selection for GPU acceleration.
      ```
      ╔══════════════════════════════════════════════════════════════════════════════╗
      ║ System Architecture Overview ║
      ║ Multi-Process • Distributed • Cross-Platform ║
      ╚══════════════════════════════════════════════════════════════════════════════╝
      ```
      ## Process Architecture ## Process Architecture
      ```
      ┌─────────────────────────────────────────────────────────────────────────────┐
      │ Process Architecture │
      ├─────────────────────────────────────────────────────────────────────────────┤
      │ │
      │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
      │ │ Web Interface │ │ Backend │ │ Queue Manager │ │
      │ │ Process │◄──►│ Process │◄──►│ Process │ │
      │ │ (Flask) │ │ (Router) │ │ (Job Queue) │ │
      │ │ │ │ │ │ │ │
      │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
      │ │ │ │ │
      │ │ │ │ │
      │ ▼ ▼ ▼ │
      │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
      │ │ User Auth │ │ Worker Routing │ │ Job Scheduling │ │
      │ │ & Sessions │ │ & Load Bal. │ │ & Monitoring │ │
      │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
      │ │
      │ ┌─────────────────────────────────────────────────────────────────────────┐ │
      │ │ Worker Processes │ │
      │ ├─────────────────────────────────────────────────────────────────────────┤ │
      │ │ │ │
      │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │
      │ │ │ Analysis CUDA │ │ Analysis ROCm │ │ Training CUDA │ │ │
      │ │ │ Worker │ │ Worker │ │ Worker │ │ │
      │ │ │ │ │ │ │ │ │ │
      │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │
      │ │ │ │
      │ │ ┌─────────────────┐ │ │
      │ │ │ Training ROCm │ │ │
      │ │ │ Worker │ │ │
      │ │ └─────────────────┘ │ │
      │ └─────────────────────────────────────────────────────────────────────────┘ │
      └─────────────────────────────────────────────────────────────────────────────┘
      ```
      ### Components ### Components
      1. **Web Interface Process** (`vidai/web.py`) 1. **Web Interface Process** (`vidai/web.py`)
      ...@@ -36,7 +80,39 @@ The Video AI Analysis Tool is designed as a multi-process application to provide ...@@ -36,7 +80,39 @@ The Video AI Analysis Tool is designed as a multi-process application to provide
      ### Communication Protocol ### Communication Protocol
      All inter-process communication uses Unix domain sockets with JSON messages for optimal local performance: ```
      ┌─────────────────────────────────────────────────────────────────────────────┐
      │ Communication Architecture │
      ├─────────────────────────────────────────────────────────────────────────────┤
      │ │
      │ ┌─────────────────┐ ┌─────────────────┐ │
      │ │ Web Process │ │ Backend Process │ │
      │ │ │ │ │ │
      │ │ TCP Socket │◄──────────────────────►│ TCP Socket │ │
      │ │ Port 5001 │ JSON Messages │ Port 5001 │ │
      │ └─────────────────┘ └─────────────────┘ │
      │ │
      │ ┌─────────────────┐ ┌─────────────────┐ │
      │ │ Backend Process │ │ Worker Process │ │
      │ │ │ │ │ │
      │ │ TCP Socket │◄──────────────────────►│ TCP Socket │ │
      │ │ Port 5002 │ JSON Messages │ Port 5002 │ │
      │ └─────────────────┘ └─────────────────┘ │
      │ │
      │ ┌─────────────────────────────────────────────────────────────────────────┐ │
      │ │ Cross-Platform Communication │ │
      │ ├─────────────────────────────────────────────────────────────────────────┤ │
      │ │ │ │
      │ │ Linux/macOS: │ Windows: │ │
      │ │ • Unix Domain Sockets │ • TCP Sockets │ │
      │ │ • High Performance │ • Universal Compatibility │ │
      │ │ • Local Security │ • Firewall Friendly │ │
      │ │ • File Permissions │ • Simple Configuration │ │
      │ └─────────────────────────────────────────────────────────────────────────┘ │
      └─────────────────────────────────────────────────────────────────────────────┘
      ```
      All inter-process communication uses sockets with JSON messages for optimal local performance:
      ```json ```json
      { {
      ...@@ -70,12 +146,67 @@ All inter-process communication uses Unix domain sockets with JSON messages for ...@@ -70,12 +146,67 @@ All inter-process communication uses Unix domain sockets with JSON messages for
      ### Data Flow ### Data Flow
      1. User uploads media via web interface ```
      2. Web process sends request to backend ┌─────────────────────────────────────────────────────────────────────────────┐
      3. Backend routes to appropriate worker based on config │ Data Flow Diagram │
      4. Worker processes request and sends result back ├─────────────────────────────────────────────────────────────────────────────┤
      5. Backend forwards result to web process │ │
      6. Web process displays result to user │ ┌─────────────┐ │
      │ │ User │ │
      │ │ Request │ │
      │ └──────┬──────┘ │
      │ │ │
      │ ▼ │
      │ ┌─────────────┐ ┌─────────────────────────────────┐ ┌─────────────┐ │
      │ │ Web Process │ │ Backend Process │ │ Database │ │
      │ │ │ │ │ │ (SQLite) │ │
      │ │ • Auth │───►│ • Request Validation │◄──►│ │ │
      │ │ • Upload │ │ • Queue Management │ │ • Config │ │
      │ │ • Results │ │ • Worker Routing │ │ • Users │ │
      │ └─────────────┘ └─────────────────────────────────┘ └─────────────┘ │
      │ ▲ │ │ │
      │ │ │ │ │
      │ └───────────────────┼───────────────────────────────┘ │
      │ │ │
      │ ▼ │
      │ ┌─────────────────┐ │
      │ │ Worker Pool │ │
      │ │ │ │
      │ │ ┌────────────┐ │ │
      │ │ │ Analysis │ │ │
      │ │ │ Worker │ │ │
      │ │ │ (CUDA/ROCm)│ │ │
      │ │ └────────────┘ │ │
      │ │ │ │
      │ │ ┌────────────┐ │ │
      │ │ │ Training │ │ │
      │ │ │ Worker │ │ │
      │ │ │ (CUDA/ROCm)│ │ │
      │ │ └────────────┘ │ │
      │ └─────────────────┘ │
      │ │ │
      │ ▼ │
      │ ┌─────────────────┐ │
      │ │ Processing │ │
      │ │ Results │ │
      │ └─────────────────┘ │
      │ │
      └─────────────────────────────────────────────────────────────────────────────┘
      ```
      #### Detailed Flow Steps
      1. **User Request**: User uploads media via web interface and submits analysis request
      2. **Authentication**: Web process validates user session and permissions
      3. **Request Queuing**: Backend process adds job to queue with priority and metadata
      4. **Worker Selection**: Backend routes job to appropriate worker based on:
      - Configured backend preference (CUDA/ROCm)
      - Worker availability and load
      - Job type (analysis vs training)
      5. **Processing**: Worker processes the job using AI models and GPU acceleration
      6. **Result Storage**: Results stored in temporary files for reliability
      7. **Response Delivery**: Backend forwards results back to web process
      8. **User Display**: Web process formats and displays results to user
      ### Error Handling ### Error Handling
      ...@@ -91,11 +222,79 @@ All inter-process communication uses Unix domain sockets with JSON messages for ...@@ -91,11 +222,79 @@ All inter-process communication uses Unix domain sockets with JSON messages for
      - File system access restricted to configured directories - File system access restricted to configured directories
      - Input validation on all message data - Input validation on all message data
      ## Cluster Architecture
      ```
      ┌─────────────────────────────────────────────────────────────────────────────┐
      │ Cluster Architecture │
      ├─────────────────────────────────────────────────────────────────────────────┤
      │ │
      │ ┌─────────────────────────────────────────────────────────────────────────┐ │
      │ │ Master Node │ │
      │ ├─────────────────────────────────────────────────────────────────────────┤ │
      │ │ │ │
      │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
      │ │ │ Cluster │ │ Backend │ │ Queue │ │ Database │ │ │
      │ │ │ Master │◄──►│ Process │◄──►│ Management │◄──►│ (SQLite) │ │ │
      │ │ │ │ │ │ │ │ │ │ │ │
      │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
      │ │ │ │ │ │ │
      │ │ └─────────────────┼────────────────────────┼──────────────────────┘ │
      │ │ │ │ │
      │ └───────────────────────────┼────────────────────────┼────────────────────────┘
      │ │ │
      │ ┌───────────────────────────▼────────────────────────▼────────────────────────┐
      │ │ Load Balancing & Routing │
      │ └─────────────────────────────────────────────────────────────────────────────┘
      │ │ │
      │ ┌───────────────────────────▼────────────────────────▼────────────────────────┐
      │ │ Worker Nodes │
      │ ├─────────────────────────────────────────────────────────────────────────────┤
      │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
      │ │ │ Analysis │ │ Analysis │ │ Training │ │ Training │ │
      │ │ │ CUDA │ │ ROCm │ │ CUDA │ │ ROCm │ │
      │ │ │ Worker │ │ Worker │ │ Worker │ │ Worker │ │
      │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
      │ │ │
      │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │
      │ │ │ Distributed Processing │ │
      │ │ ├─────────────────────────────────────────────────────────────────────────┤ │
      │ │ │ • Automatic workload distribution across cluster nodes │ │
      │ │ │ • Weight-based load balancing for optimal resource utilization │ │
      │ │ │ • Failover support when worker nodes become unavailable │ │
      │ │ │ • Real-time cluster health monitoring and management │ │
      │ │ └─────────────────────────────────────────────────────────────────────────┘ │
      │ └─────────────────────────────────────────────────────────────────────────────┘
      │ ▲ ▲
      │ │ │
      │ ┌───────────────────────────▼────────────────────────▼────────────────────────┐
      │ │ Result Aggregation │
      │ └─────────────────────────────────────────────────────────────────────────────┘
      └─────────────────────────────────────────────────────────────────────────────┘
      ```
      ### Cluster Communication Flow
      ```
      Master Node (Port 5003) ◄── Cluster Control ──► Worker Node
      │ │
      │ │
      ▼ ▼
      ┌─────────────┐ ┌─────────────┐
      │ Web Process │ │ Worker Pool │
      │ (Port 5001) │ │ (Port 5002) │
      └─────────────┘ └─────────────┘
      ▲ ▲
      │ │
      └───────── Backend Router ─────────────────────┘
      (Port 5002)
      ```
      ## Deployment ## Deployment
      ### Development ### Development
      Use `start.sh` to launch all processes manually for development and debugging. Use `start.sh` (Linux/macOS) or `start.bat` (Windows) to launch all processes manually for development and debugging.
      ### Production ### Production
      ......
      Markdown is supported
      0% or
      You are about to add 0 people to the discussion. Proceed with caution.
      Finish editing this message first!
      Please register or to comment