# sadanandmiskin/intervai architecture

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

- Interactive diagram: https://gitdiagram.com/sadanandmiskin/intervai
- Repository: https://github.com/sadanandmiskin/intervai

## Overview

##### Project type and purpose
- This is a full-stack web application (“IntervAI”) for AI-powered interview preparation.
- The frontend is a React+TypeScript SPA (Vite + Tailwind) that users interact with in the browser.
- The backend is a Node.js/Express service (TypeScript) exposing REST endpoints and a WebSocket server.
- It uses MongoDB for persistence, JWT for auth, integrates with Google OAuth, and calls out to an external AI service (Fireworks AI) for question generation and evaluation.

##### File structure
- Top-level docker-compose.yml orchestrates two containers: “frontend” and “backend.”
- backend/
- src/controllers, routes, models, middleware → MVC structure in Express
- index.ts sets up HTTP + WebSocket servers
- .env for secrets (FIREWORKS_API_KEY, MONGODB URI, JWT_SECRET, GOOGLE_CLIENT_ID, FRONTEND_URL)
- frontend/
- src/pages for routing (Home, Login, Create session, Interview, Dashboard, Results)
- src/components for UI, contexts/AuthContext for JWT-based state
- src/services/api.ts wraps HTTP & WebSocket client logic
- Vite config + Tailwind + ESLint
- docker-compose.yml
- Defines two services (frontend, backend), links them, exposes ports 5173 and 3000

##### Key architecture insights from README
- Real-time Q&A & feedback over WebSockets
- AI question generation & answer evaluation via Fireworks AI
- Persistent session reports stored in MongoDB
- Google Sign-In for user auth

##### Relationships & data flow
1. Browser → HTTP → Backend REST API
2. Browser ↔ WebSocket → Backend real-time server
3. Backend → Fireworks AI API (HTTP)
4. Backend → MongoDB (read/write)
5. Browser ← JWT in HTTP headers or WS handshake
6. Browser ← Backend responses & WS events

##### Architectural patterns & design principles
- Single-page frontend separated from backend monolith
- MVC-style controllers, routes, models in backend
- WebSocket + REST hybrid for real-time and traditional API calls
- Environment-driven configuration (12-factor app)
- Containerized via Docker Compose (service orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["User Browser\n(React SPA)"]:::frontend
    end

    %% Frontend Service Container
    subgraph "Frontend Service (Container)"
        direction TB
        SPA["SPA Pages"]:::frontend
        UI["UI Components"]:::frontend
        AuthC["AuthContext\n(JWT & Google Sign-In)"]:::frontend
        API["api.ts\n(HTTP & WS Client)"]:::frontend
        Vite["vite.config.ts"]:::frontend
        Tailwind["tailwind.config.js"]:::frontend
        FE_Docker["Dockerfile"]:::frontend
    end

    %% Backend Service Container
    subgraph "Backend Service (Container)"
        direction TB
        Entry["index.ts\n(HTTP + WS Server)"]:::backend
        subgraph "Express API"
            direction TB
            Routes["Routes"]:::backend
            Controllers["Controllers"]:::backend
            Middleware["JWT Auth Middleware"]:::backend
            Models["MongoDB Models"]:::backend
        end
        BE_Docker["Dockerfile"]:::backend
        Env[".env.example"]:::backend
    end

    %% Data Layer
    MongoDB[(MongoDB)]:::db

    %% External Services
    subgraph "External Services"
        direction TB
        FireworksAI["Fireworks AI API"]:::external
        GoogleOAuth["Google OAuth"]:::external
    end

    %% Connections
    Browser -->|"HTTP:5173"| SPA
    Browser -->|"WS:5173"| API
    SPA -->|"invokes"| UI
    UI -->|"uses"| AuthC
    AuthC -->|"sends JWT\nin headers/WS"| API
    API -->|"HTTP:3000\nREST API"| Entry
    API -->|"WS:3000\nReal-time"| Entry
    Entry -->|"calls"| Controllers
    Controllers -->|"use middleware"| Middleware
    Controllers -->|"read/write"| Models
    Controllers -->|"HTTP"| FireworksAI
    Entry -->|"verify tokens"| GoogleOAuth
    Models -->|"persist data"| MongoDB

    %% Click events for frontend
    click SPA "https://github.com/sadanandmiskin/intervai/tree/master/frontend/src/pages"
    click UI "https://github.com/sadanandmiskin/intervai/tree/master/frontend/src/components"
    click AuthC "https://github.com/sadanandmiskin/intervai/blob/master/frontend/src/contexts/AuthContext.tsx"
    click API "https://github.com/sadanandmiskin/intervai/blob/master/frontend/src/services/api.ts"
    click Vite "https://github.com/sadanandmiskin/intervai/blob/master/frontend/vite.config.ts"
    click Tailwind "https://github.com/sadanandmiskin/intervai/blob/master/frontend/tailwind.config.js"
    click FE_Docker "https://github.com/sadanandmiskin/intervai/tree/master/frontend/Dockerfile"
    click Browser "https://github.com/sadanandmiskin/intervai/tree/master/frontend/src"

    %% Click events for backend
    click Entry "https://github.com/sadanandmiskin/intervai/blob/master/backend/src/index.ts"
    click Controllers "https://github.com/sadanandmiskin/intervai/tree/master/backend/src/controllers"
    click Routes "https://github.com/sadanandmiskin/intervai/tree/master/backend/src/routes"
    click Middleware "https://github.com/sadanandmiskin/intervai/blob/master/backend/src/middleware/auth.ts"
    click Models "https://github.com/sadanandmiskin/intervai/tree/master/backend/src/models"
    click BE_Docker "https://github.com/sadanandmiskin/intervai/tree/master/backend/Dockerfile"
    click Env "https://github.com/sadanandmiskin/intervai/blob/master/backend/.env.example"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#004d40;
    classDef backend fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20;
    classDef db fill:#fff3e0,stroke:#ef6c00,color:#e65100;
    classDef external fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c;
```
