# wiss84/robots-ai architecture

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

- Interactive diagram: https://gitdiagram.com/wiss84/robots-ai
- Repository: https://github.com/wiss84/robots-ai

## Overview

##### Project Type and Purpose
- This is a full-stack AI assistant platform comprising:
- A React/TypeScript single-page application (SPA) frontend served by Vite
- A Python FastAPI backend exposing REST (and possibly WebSocket) endpoints
- A multi-agent “plugin” system where each agent (coding, finance, news, etc.) is implemented as a separate Python module
- A persistent store (Supabase/Postgres) for conversations and messages
- Integration with multiple third-party AI and data services (Google AI, AI Horde, OpenRouteService, RealtyUS/ RapidAPI, etc.)

##### File Structure
- Top-level directories:
- robots_frontend/ → React SPA
- robots_backend/ → FastAPI application with agent modules, file processing, summarization, upload endpoints
- Key backend files:
- main.py → FastAPI app entrypoint, routes registration
- agent_*.py → Individual agent implementations (each handles domain-specific logic)
- tools.py, RealtyUS_tools.py, file_processor.py, summarize.py → Shared utilities and endpoints
- requirements.txt → Python dependencies
- Key frontend files:
- src/pages/ → High-level screens (Home, Auth, AgentSelection, ChatUI)
- src/components/ → Reusable UI components (ChatSidebar, ChatMessages, FileUpload, Map, Chessboard…)
- src/hooks/useAuth.ts → Auth/session management
- src/utils/ → Parsers, summarization helpers
- public/ → Static assets (agent avatars, service worker)
- Configuration & deployment:
- robots_frontend/vite.config.ts, tsconfig.json → Build and module resolution
- robots_backend/.env.example → Environment variables for API keys and CORS
- start_app.bat & robots-ai.bat → Shortcut to spin up both ends

##### README for Additional Insights
- Confirms a layered architecture: UI ↔ API ↔ Agents ↔ External Services
- Mentions Supabase for data persistence and RLS (Row-Level Security)
- Highlights multi-modal support (text + image) and file processing (OCR, PDF parsing)
- Describes each agent’s domain and third-party dependencies

##### Main Components
a. Frontend (React SPA)
- Components: ChatUI, FileUpload, MapDisplay, Chessboard
- Service Worker (cache strategy)
- Auth via Supabase client
b. Backend (FastAPI)
- API Layer: REST endpoints (/chat, /upload, /summarize, /tools, /agentswitch)
- Agent Engine: dynamically dispatches to agent_*.py modules
- File Processing Service: OCR, PDF, image handlers
- Summarization Service
- Data Access Layer: Supabase/Postgres connector
c. Persistent Store
- Supabase (Postgres)
- Tables: conversations, messages
d. External Services
- AI APIs: Google AI, AI Horde
- Data APIs: RealtyUS, OpenRouteService (Heigit), RapidAPI
- LangChain/Composio for tool orchestration
e. User
- Browser client interacts via HTTP(S) to the frontend dev server or static build

##### Relationships & Interactions
- User → Frontend (HTTP GET/WS)
- Frontend → Backend (HTTP POST/GET or WebSocket) for chat messages, file uploads, agent switching
- Backend → Agent Modules (in-process calls)
- Agent Modules → External Services (HTTP clients with respective API keys)
- Backend → Supabase/Postgres (CRUD for messages & conversation history)
- Frontend → Supabase (optional direct reads with anon key for UI state, e.g., usage monitoring)

##### Architectural Patterns & Design Principles
- Layered architecture (UI, API, Domain/Agents, Persistence, External Integrations)
- Plugin-style agent modules (each agent encapsulates its own logic and external tool calls)
- Single codebase for backend; agents are “micro-plugins,” not separate microservices
- Separation of concerns: file-processing, summarization, and chat orchestration are distinct services
- Use of modern SPA best practices: code splitting, service worker caching

##### Technologies & Frameworks
- Frontend: React, TypeScript, Vite, Supabase JS client, ESLint
- Backend: Python 3.11, FastAPI, Uvicorn, Pydantic, LangChain/Composio
- Database: Supabase (managed Postgres)
- External APIs: Google AI, AI Horde, RapidAPI, OpenRouteService, RealtyUS
- DevOps: .bat scripts for Windows, environment variables via .env, GitHub Actions templates

##### Elements to Include for Clarity
- Clear labels for frontend pages (AgentSelection, ChatUI) and backend services
- Notes on critical environment variables (CORS_ORIGINS, API_KEY usage)
- Emphasis on the plugin-based agent dispatch pattern

Summary
– Start by sketching five horizontal layers (User, Frontend, API, Agents, Persistence, External)
– Populate each layer with the relevant modules/files
– Show how chat requests flow from UI → FastAPI → appropriate agent → external AI service → back through summarization and persistence → UI
– Highlight long-running paths (image gen queue) and real-time flows (chat & chess moves)

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% User Layer
  subgraph "User & Browser"
    User["User (Browser)"]:::user
  end

  %% Frontend Layer
  subgraph "Frontend (React SPA)" 
    ChatUI["ChatUI"]:::frontend
    AgentSelection["AgentSelection Page"]:::frontend
    HomePage["Home Page"]:::frontend
    SignIn["SignIn Page"]:::frontend
    SignUp["SignUp Page"]:::frontend
    FileUpload["FileUpload Component"]:::frontend
    ChatSidebar["ChatSidebar Component"]:::frontend
    ChatMessages["ChatMessages Component"]:::frontend
    ChatInput["ChatInput Component"]:::frontend
    MapDisplay["Map Display Component"]:::frontend
    MapMessage["Map Message Component"]:::frontend
    Chessboard["Chessboard Component"]:::frontend
    UsageMonitor["UsageMonitor Component"]:::frontend
    AuthHook["useAuth Hook"]:::frontend
    ServiceWorker["Service Worker"]:::frontend
  end

  %% API Layer
  subgraph "API Layer (FastAPI)"
    API["FastAPI App (main.py)"]:::api
  end

  %% Domain Layer
  subgraph "Domain Layer (Agents & Tools)"
    subgraph "Agents"
      CodingAgent["agent_coding.py"]:::service
      FinanceAgent["agent_finance.py"]:::service
      GamesAgent["agent_games.py"]:::service
      ImageAgent["agent_image_generator.py"]:::service
      NewsAgent["agent_news.py"]:::service
      RealEstateAgent["agent_realestate.py"]:::service
      ShoppingAgent["agent_shopping.py"]:::service
      TravelAgent["agent_travel.py"]:::service
      AgentsSystem["agents_system_prompts.py"]:::service
    end
    subgraph "Tools & Utilities"
      GeneralTools["tools.py"]:::service
      FileProcessor["file_processor.py"]:::service
      FileUploadSvc["file_upload.py"]:::service
      Summarize["summarize.py"]:::service
      RealtyUSTools["RealtyUS_tools.py"]:::service
      ORSTools["ors_tools.py"]:::service
      OSMTools["osm_tools.py"]:::service
      ChessTool["chess_tool.py"]:::service
    end
  end

  %% Data Layer
  subgraph "Data Layer"
    DB["Supabase/Postgres"]:::db
  end

  %% External Services
  subgraph "External Services"
    GoogleAI["Google AI"]:::external
    AIHorde["AI Horde"]:::external
    RealtyAPI["RealtyUS (RapidAPI)"]:::external
    ORS["OpenRouteService"]:::external
    RapidAPI["RapidAPI Other"]:::external
    LangChain["LangChain/Composio"]:::external
  end

  %% Connections
  User -->|"HTTP/WS"| ChatUI
  ChatUI -->|"POST /chat"| API
  ChatUI -->|"GET /messages"| DB
  AgentSelection -->|navigate| ChatUI
  HomePage -->|navigate| AgentSelection
  SignIn -->|auth| AuthHook
  SignUp -->|auth| AuthHook
  ChatInput -->|send message| API
  FileUpload -->|upload file| API
  ChatSidebar -->|select chat| API
  MapDisplay -->|render| MapMessage
  API -->|"dispatch"| CodingAgent
  API -->|"dispatch"| FinanceAgent
  API -->|"dispatch"| GamesAgent
  API -->|"dispatch"| ImageAgent
  API -->|"dispatch"| NewsAgent
  API -->|"dispatch"| RealEstateAgent
  API -->|"dispatch"| ShoppingAgent
  API -->|"dispatch"| TravelAgent
  API -->|"load prompts"| AgentsSystem
  API -->|"call"| GeneralTools
  API -->|"process files"| FileProcessor
  API -->|"upload service"| FileUploadSvc
  API -->|"summarize"| Summarize
  GeneralTools -->|"calls"| RealtyUSTools
  GeneralTools -->|"calls"| ORSTools
  GeneralTools -->|"calls"| OSMTools
  GeneralTools -->|"calls"| ChessTool
  CodingAgent -->|"HTTP API"| GoogleAI
  ImageAgent -->|async| AIHorde
  RealEstateAgent -->|"HTTP API"| RealtyAPI
  TravelAgent -->|"HTTP API"| ORS
  FinanceAgent -->|HTTP| RapidAPI
  GeneralTools -->|"orchestrate"| LangChain
  API -->|"CRUD"| DB

  %% Click Events
  click ChatUI "https://github.com/wiss84/robots-ai/blob/main/robots_frontend/src/pages/ChatUI.tsx"
  click AgentSelection "https://github.com/wiss84/robots-ai/blob/main/robots_frontend/src/pages/AgentSelection.tsx"
  click HomePage "https://github.com/wiss84/robots-ai/blob/main/robots_frontend/src/pages/HomePage.tsx"
  click SignIn "https://github.com/wiss84/robots-ai/blob/main/robots_frontend/src/pages/SignIn.tsx"
  click SignUp "https://github.com/wiss84/robots-ai/blob/main/robots_frontend/src/pages/SignUp.tsx"
  click FileUpload "https://github.com/wiss84/robots-ai/blob/main/robots_frontend/src/components/FileUpload.tsx"
  click ChatSidebar "https://github.com/wiss84/robots-ai/blob/main/robots_frontend/src/components/ChatSidebar.tsx"
  click ChatMessages "https://github.com/wiss84/robots-ai/blob/main/robots_frontend/src/components/ChatMessages.tsx"
  click ChatInput "https://github.com/wiss84/robots-ai/blob/main/robots_frontend/src/components/ChatInput.tsx"
  click MapDisplay "https://github.com/wiss84/robots-ai/blob/main/robots_frontend/src/components/Map.tsx"
  click MapMessage "https://github.com/wiss84/robots-ai/blob/main/robots_frontend/src/components/MapMessage.tsx"
  click Chessboard "https://github.com/wiss84/robots-ai/blob/main/robots_frontend/src/components/Chessboard.tsx"
  click UsageMonitor "https://github.com/wiss84/robots-ai/blob/main/robots_frontend/src/components/UsageMonitor.tsx"
  click AuthHook "https://github.com/wiss84/robots-ai/blob/main/robots_frontend/src/hooks/useAuth.ts"
  click ServiceWorker "https://github.com/wiss84/robots-ai/blob/main/robots_frontend/public/service-worker.js"
  click API "https://github.com/wiss84/robots-ai/blob/main/robots_backend/main.py"
  click AgentsSystem "https://github.com/wiss84/robots-ai/blob/main/robots_backend/agents_system_prompts.py"
  click CodingAgent "https://github.com/wiss84/robots-ai/blob/main/robots_backend/agent_coding.py"
  click FinanceAgent "https://github.com/wiss84/robots-ai/blob/main/robots_backend/agent_finance.py"
  click GamesAgent "https://github.com/wiss84/robots-ai/blob/main/robots_backend/agent_games.py"
  click ImageAgent "https://github.com/wiss84/robots-ai/blob/main/robots_backend/agent_image_generator.py"
  click NewsAgent "https://github.com/wiss84/robots-ai/blob/main/robots_backend/agent_news.py"
  click RealEstateAgent "https://github.com/wiss84/robots-ai/blob/main/robots_backend/agent_realestate.py"
  click ShoppingAgent "https://github.com/wiss84/robots-ai/blob/main/robots_backend/agent_shopping.py"
  click TravelAgent "https://github.com/wiss84/robots-ai/blob/main/robots_backend/agent_travel.py"
  click GeneralTools "https://github.com/wiss84/robots-ai/blob/main/robots_backend/tools.py"
  click FileProcessor "https://github.com/wiss84/robots-ai/blob/main/robots_backend/file_processor.py"
  click FileUploadSvc "https://github.com/wiss84/robots-ai/blob/main/robots_backend/file_upload.py"
  click Summarize "https://github.com/wiss84/robots-ai/blob/main/robots_backend/summarize.py"
  click RealtyUSTools "https://github.com/wiss84/robots-ai/blob/main/robots_backend/RealtyUS_tools.py"
  click ORSTools "https://github.com/wiss84/robots-ai/blob/main/robots_backend/ors_tools.py"
  click OSMTools "https://github.com/wiss84/robots-ai/blob/main/robots_backend/osm_tools.py"
  click ChessTool "https://github.com/wiss84/robots-ai/blob/main/robots_backend/chess_tool.py"

  %% Styles
  classDef user fill:#cccccc,stroke:#333,stroke-width:1px
  classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:1px
  classDef api fill:#b8daff,stroke:#004085,stroke-width:1px
  classDef service fill:#d1ecf1,stroke:#0c5460,stroke-width:1px
  classDef db fill:#d4edda,stroke:#155724,stroke-width:1px
  classDef external fill:#ffe5b4,stroke:#cc8400,stroke-width:1px
```
