# eight-atulya/eye architecture

> Architecture diagram of the GitHub repository eight-atulya/eye, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eight-atulya/eye
- Repository: https://github.com/eight-atulya/eye

## Overview

##### Project Type and Purpose
- This is a full-stack, AI-driven annotation and memory-management platform (“EYE”) with three operating modes (Heavy Load, Light, God Mode).
- The frontend is a Next.js/React web application. The backend is a Python service exposing REST endpoints, integrating AI engines (YOLO-E, Ollama, custom nodes) and CVAT for annotation. An orchestrator dispatches and monitors background jobs.

##### File Structure Highlights
- frontend/ : Next.js app, pages under src/app, feature folders (annotation, inference, memory, training, eye-ai, YOLO-E, projects, settings).
- backend/ : Python service (main.py), FastAPI-style api/ routes, auth/, schemas/, services/ (CVAT, memory, jobs, queue, Ollama), config, requirements.txt, Dockerfile.
- orchestrator/ : dispatcher.py, scheduler.py, monitor.py, workers/ (redis_worker, yolo_e_worker, simple_worker), Dockerfile.
- engines/ : plugin-style AI engine nodes (base, custom, forge, spectra, ultra, yolo_e).
- storage/ : persistence adapters (S3).
- monitoring/ : Prometheus configuration, custom health exporter, dashboards, alerts.
- config/, k8s/, docker-compose.yml : deployment and environment configuration.
- scripts/ : utilities for setup, tests, weight downloads.

##### Key Architectural Patterns
- Three-tier/full-stack separation: Frontend ←→ Backend API ←→ Data & AI engines.
- Dispatcher–worker pattern: orchestrator pulls from job queue (Redis?), schedules tasks to workers.
- Plugin engine architecture: engines/ directory implements Strategy pattern for different AI nodes.
- Service layer: backend/services implements integrations (CVAT, Ollama, memory).
- Micro-service-ish components: API server vs. orchestrator vs. monitoring vs. storage adapters.
- Event/message queue: used for inter-component communication (jobs, metrics).

##### Main Components and Interactions (to illustrate
A. Frontend (Next.js web UI)
- Sends HTTP(S) requests to Backend API
- WebSockets or polling for job/status updates
B. Backend API (FastAPI-style)
- Routes: annotations, jobs, memory, inference, metrics, Ollama, YOLO-E
- Auth service (JWT or session)
- Enqueues tasks in Redis queue
- Reads/writes from storage (S3 adapter) and database (if any)
C. Orchestrator
- Dispatcher: reads queue, assigns tasks to workers
- Scheduler: periodic maintenance or batch tasks
- Monitor: health checks, metrics export
D. Workers
- RedisWorker: general purpose
- YOLO-EWorker: runs YOLO-E inference/training
- SimpleWorker: lightweight jobs
E. Engines (plugin modules loaded by workers)
- BaseNode, CustomNode, ForgeNode, SpectraNode, UltraNode, YoloENode
F. External Services
- CVAT (annotation integration)
- Ollama (LLM inference)
- S3 or other blob storage
- Prometheus/Grafana (monitoring)
G. Configuration & Deployment
- Docker/Docker-Compose
- Kubernetes manifests (k8s/)
- Environment files (env.txt, eye.yaml)
- Makefile/scripts

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend
    subgraph "Frontend Layer"
        direction TB
        UI["Next.js/React Web UI"]:::frontend
    end

    %% Backend API
    subgraph "Backend API (Python/FastAPI)" 
        direction TB
        API["main.py"]:::backend
        Routes["API Routes (/annotations, /jobs, /memory, /metrics, /ollama, /yolo-e)"]:::backend
        Auth["Auth Service"]:::backend
        CVATSvc["CVAT Integration Service"]:::backend
        JobsSvc["Job Management Service"]:::backend
        QueueSvc["Queue Integration Service"]:::backend
        MemorySvc["Memory Processing Services"]:::backend
        OllamaSvc["Ollama LLM Service"]:::backend
    end

    %% Message Queue
    Queue["Redis Queue"]:::external

    %% Orchestrator
    subgraph "Orchestrator"
        direction TB
        Dispatcher["Dispatcher"]:::orchestrator
        Scheduler["Scheduler"]:::orchestrator
        Monitor["Monitor"]:::orchestrator
    end

    %% Workers
    subgraph "Workers"
        direction TB
        RedisWorker["RedisWorker"]:::workers
        SimpleWorker["SimpleWorker"]:::workers
        YOLOEWorker["YOLO-EWorker"]:::workers
    end

    %% Engines
    subgraph "Plugin Engines"
        direction TB
        BaseNode["BaseNode"]:::engines
        CustomNode["CustomNode"]:::engines
        ForgeNode["ForgeNode"]:::engines
        SpectraNode["SpectraNode"]:::engines
        UltraNode["UltraNode"]:::engines
        YoloENode["YoloENode"]:::engines
    end

    %% External Services & Storage
    subgraph "External Services & Storage"
        direction TB
        S3["S3 Storage Adapter"]:::external
        CVAT["CVAT Service"]:::external
        Ollama["Ollama Service"]:::external
    end

    %% Monitoring
    subgraph "Monitoring Stack"
        direction TB
        Prometheus["Prometheus Config"]:::monitoring
        HealthExp["Health Exporter"]:::monitoring
        Dashboards["Dashboards"]:::monitoring
        Alerts["Alerts"]:::monitoring
    end

    %% Configuration & Deployment
    subgraph "Config & Deployment"
        direction TB
        DockerComp["Docker Compose"]:::config
        K8s["Kubernetes Manifests"]:::config
        Env["Environment Config"]:::config
        Scripts["Utility Scripts"]:::config
    end

    %% Connections
    UI -->|"HTTP Requests"| API
    UI -->|"WebSocket/Polling"| API

    API -->|"enqueue task"| Queue
    API -->|"calls CVAT API"| CVAT
    API -->|"calls Ollama"| Ollama
    API -->|"push metrics"| Prometheus

    Dispatcher -->|"dequeue task"| Queue
    Dispatcher -->|"dispatch job"| RedisWorker
    Dispatcher -->|"dispatch job"| SimpleWorker
    Dispatcher -->|"dispatch job"| YOLOEWorker
    Scheduler -->|"/batch tasks"| RedisWorker
    Monitor -->|"health checks"| API
    Monitor -->|"metrics export"| Prometheus

    RedisWorker -->|"invoke"| BaseNode
    RedisWorker -->|"invoke"| CustomNode
    RedisWorker -->|"invoke"| ForgeNode
    RedisWorker -->|"invoke"| SpectraNode
    RedisWorker -->|"invoke"| UltraNode
    RedisWorker -->|"invoke"| YoloENode

    SimpleWorker -->|"invoke BaseNode"| BaseNode

    YOLOEWorker -->|"invoke YoloENode"| YoloENode

    RedisWorker -->|"store artifacts"| S3
    SimpleWorker -->|"store artifacts"| S3
    YOLOEWorker -->|"store artifacts"| S3

    Prometheus -->|"drives"| Dashboards
    Prometheus -->|"triggers"| Alerts
    HealthExp -->|"exports to"| Prometheus

    DockerComp --> API
    DockerComp --> Dispatcher
    DockerComp --> Workers
    K8s --> API
    K8s --> Dispatcher

    %% Click Events
    click UI "https://github.com/eight-atulya/eye/tree/main/frontend/src/app"
    click API "https://github.com/eight-atulya/eye/blob/main/backend/main.py"
    click Routes "https://github.com/eight-atulya/eye/tree/main/backend/api/"
    click Auth "https://github.com/eight-atulya/eye/tree/main/backend/auth/"
    click CVATSvc "https://github.com/eight-atulya/eye/blob/main/backend/services/cvat_integration.py"
    click JobsSvc "https://github.com/eight-atulya/eye/blob/main/backend/services/jobs.py"
    click QueueSvc "https://github.com/eight-atulya/eye/blob/main/backend/services/queue.py"
    click MemorySvc "https://github.com/eight-atulya/eye/blob/main/backend/services/memory_service.py"
    click OllamaSvc "https://github.com/eight-atulya/eye/blob/main/backend/services/ollama_service.py"
    click YOLOEWorker "https://github.com/eight-atulya/eye/blob/main/orchestrator/workers/yolo_e_worker.py"
    click RedisWorker "https://github.com/eight-atulya/eye/blob/main/orchestrator/workers/redis_worker.py"
    click SimpleWorker "https://github.com/eight-atulya/eye/blob/main/orchestrator/workers/simple_worker.py"
    click Dispatcher "https://github.com/eight-atulya/eye/blob/main/orchestrator/dispatcher.py"
    click Scheduler "https://github.com/eight-atulya/eye/blob/main/orchestrator/scheduler.py"
    click Monitor "https://github.com/eight-atulya/eye/blob/main/orchestrator/monitor.py"
    click BaseNode "https://github.com/eight-atulya/eye/blob/main/engines/base.py"
    click CustomNode "https://github.com/eight-atulya/eye/blob/main/engines/custom_node.py"
    click ForgeNode "https://github.com/eight-atulya/eye/blob/main/engines/forge_node.py"
    click SpectraNode "https://github.com/eight-atulya/eye/blob/main/engines/spectra_node.py"
    click UltraNode "https://github.com/eight-atulya/eye/blob/main/engines/ultra_node.py"
    click YoloENode "https://github.com/eight-atulya/eye/blob/main/engines/yolo_e_node.py"
    click S3 "https://github.com/eight-atulya/eye/blob/main/storage/adapters/s3.py"
    click Prometheus "https://github.com/eight-atulya/eye/blob/main/monitoring/prometheus/prometheus.yml"
    click HealthExp "https://github.com/eight-atulya/eye/blob/main/monitoring/exporters/health_exporter.py"
    click Dashboards "https://github.com/eight-atulya/eye/tree/main/monitoring/dashboards/"
    click Alerts "https://github.com/eight-atulya/eye/tree/main/monitoring/alerts/"
    click DockerComp "https://github.com/eight-atulya/eye/blob/main/docker-compose.yml"
    click K8s "https://github.com/eight-atulya/eye/tree/main/k8s/"
    click Env "https://github.com/eight-atulya/eye/blob/main/config/eye.yaml"
    click Scripts "https://github.com/eight-atulya/eye/tree/main/scripts/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#FFD580,stroke:#333,stroke-width:1px
    classDef workers fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef engines fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef monitoring fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef config fill:#F0E68C,stroke:#333,stroke-width:1px
```
