How wiss84/robots-ai works
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)