# abhiram3107/virtual-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/abhiram3107/virtual-assistant
- Repository: https://github.com/abhiram3107/virtual-assistant

## Overview

##### Project Type and Purpose
- This is a full-stack, monolithic Django web application with a modular structure comprised of several Django “apps.” Its primary purpose is to provide a Role-Based Virtual Assistant within an LMS. Users interact via text or (optional) voice; the assistant performs intent recognition, routes the request to the correct handler, fetches/aggregates data (performance, attendance, etc.) from the database, and returns a customized response.

##### High-Level File‐Structure Analysis
- Top-Level Components:
- VA/               – Django project settings (ASGI/WSGI, URLs, env)
- Assistant/        – Core virtual assistant logic: NLP, intent router, handlers, static dataset
- assessments/, attendence/, program/, users/ – Domain apps containing models, views, migrations
- manage.py, requirements.txt, README.md
- Architectural Pattern:
- Monolithic Django MVC (Models in each app → Views → HTTP interface)
- “Handler” sub-pattern in Assistant/: IntentRouter → Router → Role‐specific handlers
- ORM models spanning multiple apps for user profiles, academic structure, tests, attendance

##### Insights from README
- Workflow:
1. User Input (text or voice)
2. Role Identification (via users.models.*Profile)
3. Intent Detection (Sentence-BERT + cosine similarity)
4. Routing to Handlers (Assistant/handlers/)
5. Data Fetch (ORM queries across assessments, attendence, program, users)
6. Response Generation (text or text+speech)
- Key Technologies:
- Django, Python, ORM
- sentence-transformers (paraphrase-MiniLM-L6-v2)
- speech_recognition, pyttsx3 (optional voice)
- Static JSON dataset for FAQs/navigation

##### Main Components
a. User Layer
- Web Client (Browser/mobile)
- Optional Voice Input/Output module
b. API Layer
- Django ASGI/WSGI Server (VA/asgi.py, VA/wsgi.py)
- URL Routing (VA/urls.py → app urls)
c. Virtual Assistant Service (Assistant/)
- Core Engine (Assistant/core.py)
- Intent Detection (Assistant/handlers/intent_router.py)
- Router (Assistant/handlers/router.py)
- Role-specific Handlers (student_analysis.py, teacher_analysis.py, hod_analysis.py)
- Static Dataset Loader (Assistant/data/dataset.json)
d. Domain Applications
- users/ (User, StudentProfile, TeacherProfile, HodProfile)
- program/ (Program, Subject, Chapter, Topic)
- assessments/ (Test, TestResult)
- attendence/ (Attendance)
e. Database
- Relational DB (PostgreSQL/MySQL/SQLite)
- Contains all model tables across the apps
f. External Libraries & Services
- Sentence-BERT model
- speech_recognition & pyttsx3

##### Relationships and Data Flow
1. User → HTTP/Voice request → Django Server
2. Django URL Dispatcher → Assistant.core entry point
3. Assistant.core → IntentRouter → Router → appropriate handler
4. Handler → ORM Queries (users, program, assessments, attendence)
5. Handler → Business logic & analytics → Response object
6. Core → Return JSON or rendered template (plus optional TTS)
7. Django → HTTP/Voice response → User

##### Architectural Patterns & Principles
- MVC (Models in each app → Controllers in views/handlers → Views/Responses)
- Modular apps for separation of concerns
- Handler/Router pattern for virtual assistant request processing
- Single source of truth: dataset.json for static Q&A
- Pluggable voice I/O layers (commented out for flexibility)

##### Elements
- Clear labels (e.g., “IntentRouter,” “StudentAnalysisHandler,” “TestResult ORM Query”)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User Layer"
        User["User (Web Client / Voice)"]:::frontend
    end

    subgraph "API Layer"
        ASGI["ASGI Server"]:::backend
        WSGI["WSGI Server"]:::backend
        UrlRouter["URL Routing"]:::backend
    end

    User -->|"HTTP/Voice request"| ASGI
    User -->|"HTTP/Voice request"| WSGI
    ASGI -->|"dispatch"| UrlRouter
    WSGI -->|"dispatch"| UrlRouter

    subgraph "Assistant Module"
        Core["Core Virtual Assistant Engine"]:::backend
        IR["IntentRouter"]:::backend
        Router["Request Router"]:::backend
        subgraph "Role-specific Handlers"
            Student["StudentAnalysisHandler"]:::backend
            Teacher["TeacherAnalysisHandler"]:::backend
            Hod["HodAnalysisHandler"]:::backend
        end
        DataSet["Static Dataset"]:::static
    end

    UrlRouter -->|"route request"| Core
    Core -->|"detect intent"| IR
    IR -->|"route"| Router
    Router --> Student
    Router --> Teacher
    Router --> Hod
    Core --> DataSet

    subgraph "Domain Applications"
        Users["Users App"]:::backend
        Program["Program App"]:::backend
        Assess["Assessments App"]:::backend
        Attendance["Attendance App"]:::backend
    end

    Student -->|"ORM queries"| Users
    Student -->|"ORM queries"| Program
    Student -->|"ORM queries"| Assess
    Student -->|"ORM queries"| Attendance
    Teacher -->|"ORM queries"| Users
    Teacher -->|"ORM queries"| Program
    Teacher -->|"ORM queries"| Assess
    Teacher -->|"ORM queries"| Attendance
    Hod -->|"ORM queries"| Users
    Hod -->|"ORM queries"| Program
    Hod -->|"ORM queries"| Assess
    Hod -->|"ORM queries"| Attendance

    subgraph "Database"
        DB["Relational Database"]:::db
    end

    Users -->|"reads/writes"| DB
    Program -->|"reads/writes"| DB
    Assess -->|"reads/writes"| DB
    Attendance -->|"reads/writes"| DB

    subgraph "External Services"
        SBERT["Sentence-BERT Model"]:::external
        VoiceLib["speech_recognition & pyttsx3"]:::external
    end

    IR -->|"model inference"| SBERT
    Core -.->|"optional TTS"| VoiceLib

    Core -->|"response"| ASGI
    Core -->|"response"| WSGI
    ASGI -->|"HTTP/Voice response"| User
    WSGI -->|"HTTP/Voice response"| User

    %% Click Events
    click ASGI "https://github.com/abhiram3107/virtual-assistant/blob/main/VA/asgi.py"
    click WSGI "https://github.com/abhiram3107/virtual-assistant/blob/main/VA/wsgi.py"
    click UrlRouter "https://github.com/abhiram3107/virtual-assistant/blob/main/VA/urls.py"
    click Core "https://github.com/abhiram3107/virtual-assistant/blob/main/Assistant/core.py"
    click IR "https://github.com/abhiram3107/virtual-assistant/blob/main/Assistant/handlers/intent_router.py"
    click Router "https://github.com/abhiram3107/virtual-assistant/blob/main/Assistant/handlers/router.py"
    click Student "https://github.com/abhiram3107/virtual-assistant/blob/main/Assistant/handlers/student_analysis.py"
    click Teacher "https://github.com/abhiram3107/virtual-assistant/blob/main/Assistant/handlers/teacher_analysis.py"
    click Hod "https://github.com/abhiram3107/virtual-assistant/blob/main/Assistant/handlers/hod_analysis.py"
    click DataSet "https://github.com/abhiram3107/virtual-assistant/blob/main/Assistant/data/dataset.json"
    click Users "https://github.com/abhiram3107/virtual-assistant/blob/main/users/models/user.py"
    click Program "https://github.com/abhiram3107/virtual-assistant/blob/main/program/models/program.py"
    click Assess "https://github.com/abhiram3107/virtual-assistant/blob/main/assessments/models/test.py"
    click Attendance "https://github.com/abhiram3107/virtual-assistant/blob/main/attendence/models/attendance.py"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#D0E8FF,stroke:#00509E,color:#00509E;
    classDef static fill:#CCCCCC,stroke:#666666,color:#333333;
    classDef db fill:#A3D3A2,stroke:#2E8B57,color:#2E8B57;
    classDef external fill:#FFE699,stroke:#CC9900,color:#996600;
```
