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
      Show whitespace changes
      Inline Side-by-side
      Showing with 340 additions and 10 deletions
      README.md
      View file @ cec0be4d
      ......@@ -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.
      ```
      ╔══════════════════════════════════════════════════════════════════════════════╗
      ║ Video AI Analysis Tool ║
      ║ Multi-Process • Cross-Platform • Distributed ║
      ╚══════════════════════════════════════════════════════════════════════════════╝
      ```
      ## Features
      - **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
      - **Configuration Management**: SQLite database for persistent settings and system prompts
      - **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
      This application is designed to work on both **Linux** and **Windows**:
      ......@@ -55,6 +107,85 @@ This application is designed to work on both **Linux** and **Windows**:
      - Open http://localhost:5000
      - 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
      - **Default Admin**: username: `admin`, password: `admin`
      ......
      docs/architecture.md
      View file @ cec0be4d
      ......@@ -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.
      ```
      ╔══════════════════════════════════════════════════════════════════════════════╗
      ║ System Architecture Overview ║
      ║ Multi-Process • Distributed • Cross-Platform ║
      ╚══════════════════════════════════════════════════════════════════════════════╝
      ```
      ## 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
      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
      ### 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
      {
      ......@@ -70,12 +146,67 @@ All inter-process communication uses Unix domain sockets with JSON messages for
      ### 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
      4. Worker processes request and sends result back
      5. Backend forwards result to web process
      6. Web process displays result to user
      ```
      ┌─────────────────────────────────────────────────────────────────────────────┐
      │ Data Flow Diagram │
      ├─────────────────────────────────────────────────────────────────────────────┤
      │ │
      │ ┌─────────────┐ │
      │ │ 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
      ......@@ -91,11 +222,79 @@ All inter-process communication uses Unix domain sockets with JSON messages for
      - File system access restricted to configured directories
      - 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
      ### 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
      ......
      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