# aashmitmckenzie/aura-ai-powered-interview-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/aashmitmckenzie/aura-ai-powered-interview-assistant
- Repository: https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant

## Overview

##### Project Type and Purpose
- This is a full-stack AI‐powered interview platform (“Aura 7.0”) with a React/TypeScript frontend and a FastAPI/Python backend.
- Key use cases: live audio transcription, sentiment & bias analysis, question generation, admin user management, PDF reporting.

##### File Structure
- Top‐level:
- Questions_Data/ – CSV files for 20+ role‐specific question banks
- backend/ – FastAPI service under app/ with routers, models, schemas, security, middleware
- frontend/ – React components, contexts, Vite build config
- requirements.txt / package.json – dependency manifests
- backend/app/routers/ contains modular endpoints (auth, admin, ai, sentiment, realtime_bias, question_selector, etc.) suggesting a micro‐modular service design.
- security_middleware.py, security_utils.py, and config.py encapsulate auth and configuration concerns.
- SQLite (app_data.db) plus CSVs form the data layer.
- frontend/src/components and contexts follow a clean React Context + component hierarchy.

##### Extract Architecture Insights from README
- Real‐time speech: Web Speech API in browser + local Whisper tiny model
- Hybrid AI analysis: VADER (rule‐based) + Transformers (ML‐based)
- JWT and RBAC for secure auth, audit logging middleware
- Modular FastAPI (microservice style) with SQLAlchemy ORM
- React state management via Context API, Vite optimizations

##### Main Components
a. Client Layer
- Browser UI (React + Web Speech API), includes Admin Panel & Candidate Interview Screen
b. API Gateway / Backend Layer
- FastAPI server—grouped by functional modules:
- Authentication & Security (auth.py, security_middleware, JWT service)
- Question Service (question_selector.py, seed_questions)
- Real‐time Analysis (realtime_bias.py, continuous_ai.py, sentiment.py)
- Reporting (reports.py)
- User/Admin Management (users.py, admin.py)
c. AI Processing Layer
- Whisper transcription engine
- VADER sentiment analyzer
- Transformers bias detector
d. Data Layer
- SQLite database (app_data.db) via SQLAlchemy ORM
- Questions_Data CSV question stores
e. External Services
- OpenAI Whisper (if using cloud API)
- Hugging Face Transformers repos (downloaded models)

##### Relationships & Data Flows
- UI → HTTP/WS calls → FastAPI endpoints
- Audio stream: Browser → FastAPI → Whisper → transcribed text → AI modules
- AI modules publish analysis results → FastAPI → WebSocket or HTTP responses → UI
- Question generation: UI requests → question_selector → CSV/DB → session payload
- Reporting: FastAPI generates PDF → UI download
- Auth flows: UI login/signup → auth router → JWT issuance → UI stores token → all backend calls include token

##### Architectural Patterns & Principles
- Modular “micro‐router” approach in FastAPI (each feature a separate router)
- API‐First design (clear RESTful endpoints, documented via Swagger)
- Separation of concerns: security, business logic, data access, AI modules
- React Context for global state, component‐based UI
- Lazy loading of AI models, caching strategies

##### Technologies / Frameworks
- Frontend: React 18, TypeScript, Vite, Axios, Web Speech API
- Backend: FastAPI, Python 3.8+, SQLAlchemy, Pydantic, Uvicorn
- AI/ML: OpenAI Whisper, NLTK/VADER, Hugging Face Transformers
- Database: SQLite + CSV files
- Security: JWT, RBAC, CORS, middleware audit logging

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer (Blue)
    subgraph "Client Layer" 
        direction TB
        AdminPanel["Admin Panel"]:::client
        Dashboard["Candidate Interview Screen"]:::client
        RealtimeBiasDisplay["Real-time Bias Display"]:::client
        UnifiedAnalysis["Unified Analysis View"]:::client
        Login["Login View"]:::client
        Signup["Signup View"]:::client
    end

    %% Backend Layer (Green)
    subgraph "Backend Layer (FastAPI)" 
        direction TB
        subgraph "Authentication & Security"
            direction TB
            AuthRouter["auth router"]:::backend
            SecurityMiddleware["security_middleware"]:::backend
            SecurityUtils["security_utils"]:::backend
            Config["config"]:::backend
        end
        subgraph "Question Service"
            direction TB
            QuestionSelector["question_selector"]:::backend
            SeedQuestions["seed_questions"]:::backend
        end
        subgraph "Real-time Analysis"
            direction TB
            RealtimeBias["realtime_bias router"]:::backend
            ContinuousAI["continuous_ai router"]:::backend
            Sentiment["sentiment router"]:::backend
            UnifiedAnalysisRouter["unified_analysis router"]:::backend
        end
        subgraph "Reporting"
            direction TB
            Reports["reports router"]:::backend
        end
        subgraph "User/Admin Management"
            direction TB
            Users["users router"]:::backend
            Admin["admin router"]:::backend
        end
    end

    %% AI Processing Layer (Orange)
    subgraph "AI Processing Layer"
        direction TB
        WhisperEngine["Whisper Transcription Engine"]:::ai
        VADERSentiment["VADER Sentiment Analyzer"]:::ai
        TransformersBias["Transformers Bias Detector"]:::ai
    end

    %% Data Layer (Gray)
    subgraph "Data Layer"
        direction TB
        SQLiteDB["SQLite Database"]:::data
        CSVStore["Questions_Data (CSV files)"]:::data
    end

    %% External Services (Purple)
    subgraph "External Services"
        direction TB
        OpenAIWhisperAPI["OpenAI Whisper API"]:::external
        HuggingFace["Hugging Face Transformers"]:::external
    end

    %% Connections
    AdminPanel -->|HTTP/WS calls| AuthRouter
    Dashboard -->|HTTP/WS calls| AuthRouter
    Login -->|POST /auth/login| AuthRouter
    Signup -->|POST /auth/signup| AuthRouter

    Dashboard -->|GET /questions| QuestionSelector
    Dashboard -->|WS audio stream| RealtimeBias
    RealtimeBias -->|"model inference call"| WhisperEngine
    ContinuousAI -->|"model inference call"| WhisperEngine
    WhisperEngine -->|"transcript"| Sentiment
    Sentiment -->|"sentiment data"| UnifiedAnalysisRouter
    TransformersBias -->|"bias data"| UnifiedAnalysisRouter
    UnifiedAnalysisRouter -->|response| UnifiedAnalysis
    Reports -->|PDF| Dashboard

    AuthRouter -->|middleware| SecurityMiddleware
    AuthRouter -->|utils| SecurityUtils
    AuthRouter -->|config| Config

    QuestionSelector -->|reads| CSVStore
    SeedQuestions -->|writes| SQLiteDB
    Users -->|CRUD| SQLiteDB
    Admin -->|CRUD| SQLiteDB

    RealtimeBias -->|store transcript| SQLiteDB
    UnifiedAnalysisRouter -->|writes report data| SQLiteDB

    ContinuousAI -->|calls| OpenAIWhisperAPI
    ContinuousAI -->|calls| HuggingFace
    UnifiedAnalysisRouter -->|calls| HuggingFace

    %% Click Events for Frontend
    click AdminPanel "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/frontend/src/components/AdminPanel.tsx"
    click Dashboard "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/frontend/src/components/Dashboard.tsx"
    click RealtimeBiasDisplay "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/frontend/src/components/RealtimeBiasDisplay.tsx"
    click UnifiedAnalysis "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/frontend/src/components/UnifiedAnalysis.tsx"
    click Login "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/frontend/src/components/Login.tsx"
    click Signup "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/frontend/src/components/Signup.tsx"

    %% Click Events for Backend
    click AuthRouter "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/backend/app/routers/auth.py"
    click SecurityMiddleware "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/backend/app/security_middleware.py"
    click SecurityUtils "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/backend/app/security_utils.py"
    click Config "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/backend/app/config.py"
    click QuestionSelector "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/backend/app/routers/question_selector.py"
    click SeedQuestions "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/backend/app/seed_questions.py"
    click RealtimeBias "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/backend/app/routers/realtime_bias.py"
    click ContinuousAI "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/backend/app/routers/continuous_ai.py"
    click Sentiment "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/backend/app/routers/sentiment.py"
    click UnifiedAnalysisRouter "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/backend/app/routers/unified_analysis.py"
    click Reports "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/backend/app/routers/reports.py"
    click Users "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/backend/app/routers/users.py"
    click Admin "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/backend/app/routers/admin.py"

    %% Click Events for Data Layer
    click SQLiteDB "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/blob/main/backend/app/database.py"
    click CSVStore "https://github.com/aashmitmckenzie/aura-ai-powered-interview-assistant/tree/main/Questions_Data/"

    %% Classes
    classDef client fill:#cce5ff,stroke:#007bff,color:#0056b3
    classDef backend fill:#d4edda,stroke:#28a745,color:#155724
    classDef ai fill:#ffe5b4,stroke:#fd7e14,color:#bd5d0b
    classDef data fill:#f8f9fa,stroke:#6c757d,color:#343a40
    classDef external fill:#e2e3e5,stroke:#6f42c1,color:#4e3171
```
