# cubestar1/triage-flow architecture

> Architecture diagram of the GitHub repository cubestar1/triage-flow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cubestar1/triage-flow
- Repository: https://github.com/cubestar1/triage-flow

## Overview

##### Project type and purpose
- This is a full-stack, multimodal medical triage application (“Triage Flow”) that:
- Provides a Next.js/Tailwind CSS frontend
- Exposes a FastAPI-based backend API
- Integrates an image-classification ML pipeline (ResNet18 on DermNet)
- Runs a RAG (FAISS) knowledge base
- Orchestrates two Gemini ADK agents
- Offers voice & video assistants over WebSocket/external APIs
- Persists data in Supabase (PostgreSQL + Auth)

##### File structure
- Top-level:
- frontend/ → Next.js app (pages, API routes, supabase clients, hooks, UI components, voice‐assistant)
- backend/ → FastAPI service, RAG module, multi-agent version_3_multi_agent package
- classfication-model/ → standalone image classifier training/inference scripts
- Patterns:
- “version_3_multi_agent” shows a JSON-RPC agent orchestration (server, client, models, agents).
- RAG uses FAISS for vector retrieval.
- frontend/app/api/**/* are proxy endpoints to backend.
- Config & infra:
- frontend/env.example, backend/env.example
- Supabase migration SQL, Next.js config, Docker files (if any), deployment targets (Vercel, Render).

##### README for additional insights

1. Client Layer
– Web Browser (React/Next.js UI)
– Voice/Video Assistant UI
2. Frontend/API Layer
– Next.js pages & components
– Next.js API routes (auth, triage)
– Supabase client library
3. Backend Services
– FastAPI “triage_endpoint” service
– RAG module (FAISS vector store, retrieval logic)
– Multi-Agent Orchestrator (Gemini ADK Agent 1 & 2 processes)
– Classification-Model service (Tensorflow/ResNet scripts)
4. Datastores
– Supabase PostgreSQL (users, triage_history)
– FAISS vector index (local/in-memory or persisted)
5. External APIs
– Google Gemini Live (WebSocket server for voice)
– Heygen API (video avatars)
– OpenAI/Gemini ADK (NLP agents)
– Resend (email verification)
6. Hosting/Deployment
– Vercel (frontend)
– Render (backend FastAPI, WebSocket)
- Browser⇆Next.js API routes (HTTP/REST)
- Next.js API routes→FastAPI API (HTTP)
- FastAPI→ClassificationModel and RAG modules (function calls or internal HTTP)
- FastAPI→Multi-Agent Orchestrator (local library import or JSON-RPC)
- FastAPI→Supabase (Postgres writes/reads via supabase-py)
- Multi-Agent→OpenAI/Gemini ADK (HTTPS)
- VoiceAssistant UI⇆WebSocket Server (wss://.../ws)→Gemini Live API
- Video Assistant UI→Heygen API
c. Architectural patterns & principles:
- Layered architecture (presentation, API gateway, business logic, data)
- Micro-library pattern for multi-agent orchestration
- Modular ML pipelines (classification, retrieval, agentic reasoning)
- Separation of concerns for identity/auth (Supabase) vs. triage logic
d. Technologies & libraries:
- Frontend: Next.js, Tailwind CSS, shadcn/ui, Supabase JS
- Backend: Python 3.9+, FastAPI, uvicorn, google-adk, tensorflow, faiss-cpu, sentence-transformers, python-dotenv
- DB: Supabase (PostgreSQL + Auth + Storage)
- ML/RAG: Tensorflow/ResNet, FAISS, Gemini API, Google ADK
- Voice: wss (Gemini Live), React hooks (useAudioStream)
- Video: Heygen API

##### Details
- Major components (classification-model folder, version_3_multi_agent sub-packages).
- Do not omit the voice & video assistants and their WebSocket link.
- Deployment targets (Vercel, Render) in the perimeter.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        WebBrowser["Web Browser (Next.js UI)"]:::frontend
        VoiceVideoUI["Voice & Video Assistant UI"]:::frontend
    end

    %% Frontend/API Layer
    subgraph "Frontend/API Layer"
        direction TB
        NextAPI["Next.js API Routes (Auth & Triage)"]:::frontend
        SupabaseClient["Supabase Client Library"]:::frontend
    end

    %% Backend Services
    subgraph "Backend Services"
        direction TB
        FastAPI["FastAPI TriageEndpoint"]:::backend
        RAG_FAISS["FAISS Vector Store"]:::ml
        RAG_Utils["RAG Utilities"]:::ml
        RAG_Data["RAG Data (ragData.json)"]:::ml
        MultiAgent["Multi-Agent Orchestrator"]:::backend
        ClassModelSave["Save Model Script"]:::ml
        ClassModelInfer["Inference Script"]:::ml
    end

    %% Datastores
    subgraph "Datastores"
        direction TB
        SupabaseDB["Supabase PostgreSQL"]:::db
        FAISSIndex["FAISS Vector Index"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GeminiLive["Google Gemini Live (WebSocket)"]:::external
        Heygen["Heygen API (Video)"]:::external
        OpenAI_ADK["OpenAI/Gemini ADK"]:::external
        ResendAPI["Resend (Email)"]:::external
    end

    %% Deployment
    subgraph "Deployment"
        direction TB
        Vercel["Vercel (Frontend)"]:::deployment
        RenderSrv["Render (Backend)"]:::deployment
    end

    %% Connections
    WebBrowser -->|"HTTP/REST"| NextAPI
    VoiceVideoUI -->|"WSS"| GeminiLive
    NextAPI -->|"HTTP POST /triage"| FastAPI
    NextAPI -->|"Auth Calls"| SupabaseClient
    SupabaseClient -->|"JS SDK"| SupabaseDB
    FastAPI -->|"vector search query"| RAG_FAISS
    FastAPI -->|"use similarityScore"| RAG_Utils
    FastAPI -->|"load ragData.json"| RAG_Data
    FastAPI -->|"import JSON-RPC"| MultiAgent
    FastAPI -->|"invoke"| ClassModelInfer
    FastAPI -->|"invoke training"| ClassModelSave
    MultiAgent -->|"HTTPS"| OpenAI_ADK
    GeminiLive -->|"streams to"| MultiAgent
    Heygen -->|"HTTPS"| FastAPI
    FastAPI -->|"reads/writes"| SupabaseDB
    RAG_FAISS --> SupabaseDB
    SupabaseDB -->|"persists index"| FAISSIndex
    WebBrowser -->|"deploy via"| Vercel
    FastAPI -->|"deploy via"| RenderSrv

    %% Click Events Frontend
    click WebBrowser "https://github.com/cubestar1/triage-flow/tree/main/frontend/app"
    click VoiceVideoUI "https://github.com/cubestar1/triage-flow/tree/main/frontend/app/(default)/voice-assistant"
    click NextAPI "https://github.com/cubestar1/triage-flow/blob/main/frontend/app/api/auth/signup/route.ts"
    click NextAPI "https://github.com/cubestar1/triage-flow/blob/main/frontend/app/api/auth/callback/route.ts"
    click NextAPI "https://github.com/cubestar1/triage-flow/blob/main/frontend/app/api/triage/route.ts"
    click NextAPI "https://github.com/cubestar1/triage-flow/blob/main/frontend/app/api/triage/new/route.ts"
    click NextAPI "https://github.com/cubestar1/triage-flow/blob/main/frontend/app/api/triage/[id]/route.ts"
    click SupabaseClient "https://github.com/cubestar1/triage-flow/blob/main/frontend/lib/supabase/client.ts"
    click SupabaseClient "https://github.com/cubestar1/triage-flow/blob/main/frontend/lib/supabase/admin.ts"
    click SupabaseClient "https://github.com/cubestar1/triage-flow/blob/main/frontend/lib/supabase/middleware.ts"
    click Migration "https://github.com/cubestar1/triage-flow/blob/main/frontend/lib/supabase/migrations/schema.sql"

    %% Click Events Backend
    click FastAPI "https://github.com/cubestar1/triage-flow/blob/main/backend/api/triage_endpoint.py"
    click RAG_FAISS "https://github.com/cubestar1/triage-flow/blob/main/backend/rag/FAISS.py"
    click RAG_Utils "https://github.com/cubestar1/triage-flow/blob/main/backend/rag/utils/similarityScore.py"
    click RAG_Data "https://github.com/cubestar1/triage-flow/blob/main/backend/rag/ragData.json"
    click MultiAgent "https://github.com/cubestar1/triage-flow/blob/main/backend/version_3_multi_agent/server/server.py"
    click MultiAgent "https://github.com/cubestar1/triage-flow/blob/main/backend/version_3_multi_agent/server/task_manager.py"
    click MultiAgent "https://github.com/cubestar1/triage-flow/blob/main/backend/version_3_multi_agent/client/client.py"
    click MultiAgent "https://github.com/cubestar1/triage-flow/blob/main/backend/version_3_multi_agent/client/cmd.py"
    click MultiAgent "https://github.com/cubestar1/triage-flow/blob/main/backend/version_3_multi_agent/agents/agent1/agent.py"
    click MultiAgent "https://github.com/cubestar1/triage-flow/blob/main/backend/version_3_multi_agent/agents/agent1/agent_cmd.py"
    click MultiAgent "https://github.com/cubestar1/triage-flow/blob/main/backend/version_3_multi_agent/agents/agent1/task_manager.py"
    click MultiAgent "https://github.com/cubestar1/triage-flow/blob/main/backend/version_3_multi_agent/agents/agent2/agent.py"
    click MultiAgent "https://github.com/cubestar1/triage-flow/blob/main/backend/version_3_multi_agent/agents/agent2/agent_cmd.py"
    click MultiAgent "https://github.com/cubestar1/triage-flow/blob/main/backend/version_3_multi_agent/agents/agent2/task_manager.py"
    click MultiAgent "https://github.com/cubestar1/triage-flow/blob/main/backend/version_3_multi_agent/models/json_rpc.py"
    click MultiAgent "https://github.com/cubestar1/triage-flow/blob/main/backend/version_3_multi_agent/models/request.py"
    click MultiAgent "https://github.com/cubestar1/triage-flow/blob/main/backend/version_3_multi_agent/models/task.py"
    click MultiAgent "https://github.com/cubestar1/triage-flow/blob/main/backend/version_3_multi_agent/models/agent.py"
    click ClassModelSave "https://github.com/cubestar1/triage-flow/blob/main/classfication-model/save_model.py"
    click ClassModelInfer "https://github.com/cubestar1/triage-flow/blob/main/classfication-model/inference.py"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064
    classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef ml fill:#FFFDE7,stroke:#F9A825,color:#F9A825
    classDef external fill:#FFF3E0,stroke:#EF6C00,color:#EF6C00
    classDef db fill:#ECEFF1,stroke:#37474F,color:#37474F
    classDef deployment fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A
```
