# sairohit022001/vidyavahini architecture

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

- Interactive diagram: https://gitdiagram.com/sairohit022001/vidyavahini
- Repository: https://github.com/sairohit022001/vidyavahini

## Overview

##### Project Type and Purpose
- Full-stack AI-driven education platform (“VidyaVāhinī”) supporting offline-first, multilingual, multimodal lessons, quizzes, and teacher dashboards.
- Frontend: React + Tailwind (TypeScript, Vite) in /frontend.
- Backend: FastAPI-style Python server (main.py + modules) exposing AI agent APIs.
- AI orchestration: “agents”, “crewflows”, “tasks”, “tools”, “llms” modules to generate content, quizzes, voice.

##### High-Level File-Structure Analysis
- Top-level:
- frontend/ – React SPA code, UI components, API wrappers (axios)
- agents/ – Prompt templates & agent-level logic
- crewflows/ – Conversational flow orchestrator, memory handlers
- routes/ – HTTP API endpoints
- tasks/ – Service-layer logic mapping API calls → agents/tools
- tools/ – LLM prompt loaders, tool abstractions, dialect adapters
- firestore/ – Firestore configuration, connectors, data utilities
- llms/ – LLM configuration
- main.py – FastAPI app bootstrap
- Dockerfile/docker-compose.yml – Containerization
- generated_audio/ & Audio/ – Local audio assets

##### Key Insights from README
- Offline-first with local caching & cloud sync (Sync Agent, Firestore).
- Multilingual/dialect voice output (VoiceTutorAgent, dialect maps).
- Teacher dashboards, course planning, analytics (PredictiveAnalyticsAgent, etc.).

a. Main Components
- Frontend SPA
- Backend API Server
- AI Orchestration Layer (Agents, Crewflows, Tasks, Tools)
- LLM Service(s) (e.g., OpenAI)
- Firestore Database
- Local Cache/Memory (offline mode)
- Audio Storage (generated_audio)
- External Cloud Services (GCP for sync, storage)

b. Relationships & Interactions
1. User (Teacher/Student) interacts with Frontend UI →
2. Frontend makes HTTPS calls to Backend API (routes/firestore_routes.py + other routers).
3. Backend routes delegate to Service Layer (tasks/*) → Agent Layer (agents/*) + Crewflows orchestrator.
4. Agents invoke Tools/prompts → llms calls to external LLM API.
5. Results returned through tasks → routes → Frontend.
6. Backend reads/writes persistent data via Firestore Connector (firestore/*).
7. Offline-first: Frontend caches data locally (IndexedDB, service worker) and syncs via SyncAgent.
8. Voice output: Agents call TTS tool → generate audio files → stored in generated_audio → served to Frontend.

c. Architectural Patterns & Principles
- Layered Architecture:
- Presentation (React UI)
- API/Controller (routes/)
- Service (tasks/)
- Domain/Orchestration (agents/, crewflows/)
- Integration (tools/, llms/)
- Data (firestore/)
- Separation of Concerns: clear modular boundaries.
- Offline-First with Synchronization Pattern.
- Plugin-style AI tooling (each Agent/Tool is a pluggable module).

d. Key Technologies & Frameworks
- Frontend: React, TypeScript, Tailwind, Vite, Axios
- Backend: Python 3.x, FastAPI (main.py), Firestore SDK
- AI: Prompt-based agents, OpenAI (or equivalent) via llms/llm_config
- Caching: local memory handler (crewflows/memory/local_memory_handler)
- Voice: Audio files, dialect adapter
- Containerization: Docker, docker-compose, Google Cloud deployment (app.yaml)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Tier
    subgraph "Frontend Tier"
        UI["React SPA"]:::frontend
        Cache["Local Cache (IndexedDB)"]:::cache
    end

    %% Backend Tier
    subgraph "Backend Tier"
        API["FastAPI Server<br/>main.py"]:::backend

        subgraph "API/Controller Layer"
            Routes["routes/"]:::controller
        end

        subgraph "Service Layer"
            Tasks["tasks/"]:::service
        end

        subgraph "Orchestration Layer"
            AgentsGrp["agents/"]:::agent
            CrewflowsGrp["crewflows/"]:::crewflow
        end

        subgraph "Integration Layer"
            ToolsGrp["tools/"]:::tool
            LLM["llms/llm_config.py"]:::llm
        end
    end

    %% External Services and Storage
    FirestoreDB["Firestore DB"]:::db
    LLMService["External LLM API"]:::external
    GenAudio["generated_audio/"]:::storage

    %% User Interaction
    User["User (Teacher/Student)"]:::user
    User -->|interacts with| UI

    %% Frontend to Backend
    UI -->|REST API Call| API
    API -->|routes delegate| Routes
    Routes -->|calls| Tasks
    Tasks -->|invoke agent| AgentsGrp
    Tasks -->|invoke crewflow| CrewflowsGrp
    AgentsGrp -->|use tool| ToolsGrp
    CrewflowsGrp -->|manage memory| ToolsGrp
    ToolsGrp -->|LLM prompt| LLM
    LLM -->|API call| LLMService
    AgentsGrp -->|TTS request| ToolsGrp
    ToolsGrp -->|generate audio| GenAudio
    GenAudio -->|stream audio| UI

    %% Data Storage & Sync
    API -->|read/write| FirestoreDB
    UI <--> |local cache sync| Cache
    Cache -->|sync request| AgentsGrp
    AgentsGrp -->|sync data| FirestoreDB

    %% Click Events
    click UI "https://github.com/sairohit022001/vidyavahini/tree/main/frontend/"
    click Cache "https://github.com/sairohit022001/vidyavahini/blob/main/crewflows/memory/local_memory_handler.py"
    click API "https://github.com/sairohit022001/vidyavahini/blob/main/main.py"
    click Routes "https://github.com/sairohit022001/vidyavahini/tree/main/routes/"
    click Tasks "https://github.com/sairohit022001/vidyavahini/tree/main/tasks/"
    click AgentsGrp "https://github.com/sairohit022001/vidyavahini/tree/main/agents/"
    click CrewflowsGrp "https://github.com/sairohit022001/vidyavahini/tree/main/crewflows/"
    click ToolsGrp "https://github.com/sairohit022001/vidyavahini/tree/main/tools/"
    click LLM "https://github.com/sairohit022001/vidyavahini/blob/main/llms/llm_config.py"
    click FirestoreDB "https://github.com/sairohit022001/vidyavahini/tree/main/firestore/"
    click GenAudio "https://github.com/sairohit022001/vidyavahini/tree/main/generated_audio/"
    click Dockerfile "https://github.com/sairohit022001/vidyavahini/tree/main/Dockerfile"
    click dockerCompose "https://github.com/sairohit022001/vidyavahini/blob/main/docker-compose.yml"
    click appYaml "https://github.com/sairohit022001/vidyavahini/blob/main/app.yaml"

    %% Styles
    classDef frontend fill:#CDE8FF,stroke:#0366D6,color:#0366D6;
    classDef cache fill:#FFF4C1,stroke:#D29922,color:#8A5A00;
    classDef backend fill:#E8F6EF,stroke:#117A65,color:#117A65;
    classDef controller fill:#E8F6EF,stroke:#28B463,color:#117A65;
    classDef service fill:#E8F6EF,stroke:#239B56,color:#117A65;
    classDef agent fill:#FDEDEC,stroke:#C0392B,color:#C0392B;
    classDef crewflow fill:#FDEDEC,stroke:#E74C3C,color:#C0392B;
    classDef tool fill:#FEF9E7,stroke:#F1C40F,color:#B7950B;
    classDef llm fill:#EBF5FB,stroke:#3498DB,color:#145A82;
    classDef db fill:#E8DAEF,stroke:#8E44AD,color:#6C3483;
    classDef external fill:#F4F6F7,stroke:#95A5A6,color:#7F8C8D;
    classDef storage fill:#EBF5FB,stroke:#5DADE2,color:#2471A3;
    classDef user fill:#FFF5F7,stroke:#EC7063,color:#A93226;
```
