# shafwansafi06/mindbridge architecture

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

- Interactive diagram: https://gitdiagram.com/shafwansafi06/mindbridge
- Repository: https://github.com/shafwansafi06/mindbridge

## Overview

##### Project Type and Purpose
- MindBridge is a full-stack, AI-powered adaptive learning platform.
- Frontend: React + TypeScript (Vite, Tailwind, shadcn/ui).
- Backend: FastAPI (Python) serving REST endpoints, orchestrating ML and LLM integrations.
- ML Pipeline: LightGBM classifier for mastery prediction, Mistral AI for quiz generation, Neo4j for concept graph.
- Data Stores: Supabase/PostgreSQL for relational data, Neo4j for knowledge graph, Redis for caching.

##### File-Structure Analysis
- Top-level:
- src/ — React application.
- public/ — static assets.
- backend/ — Python FastAPI app, organized into api/, core/, db/, ml_pipeline/, schemas/.
- docker-compose.yml + Dockerfiles — container orchestration.
- Patterns:
- Frontend components under src/components and pages.
- Backend layered architecture: API endpoints → business logic (services) → data layer (supabase, neo4j clients) → ML pipeline modules.
- Config files (.env, tsconfig, tailwind.config, etc.) for environment and build.

##### README Insights
- Contains a high-level architecture ASCII art.
- Describes system flow (Authentication → Quiz Generation → Answer Submission → ML Analysis → DB Update → Dashboard).
- Outlines ML pipeline stages and feature engineering.

- Frontend (React UI)
- Backend (FastAPI REST API)
- ML Pipeline
- Databases & Cache
- External Services
- User ↔ Frontend (HTTP requests, WebSocket or polling).
- Frontend → Backend (REST calls: /auth, /quiz, /ml).
- Backend → ML Pipeline modules (function calls or internal APIs).
- Backend → Supabase/PostgreSQL (CRUD).
- Backend → Neo4j (initialization & graph queries).
- Backend ↔ Redis (cache tokens, intermediate results).
- Backend → Mistral AI API (quiz generation, answer evaluation).
c. Architectural Patterns & Principles:
- Layered architecture in backend: API layer, service layer, data layer, ML layer.
- Component-based frontend with UI, state management (Context/Hooks), routing.
- Separation of concerns: ML logic isolated in ml_pipeline modules.
- Declarative infra via Docker Compose.
d. Key Technologies & Frameworks:
- React, Vite, TypeScript, Tailwind, shadcn/ui
- FastAPI, Uvicorn, Pydantic
- Python ML: LightGBM, scikit-learn
- LLM: Mistral AI
- Databases: Supabase (PostgreSQL), Neo4j, Redis

##### Essential Elements to Capture
- Frontend → Backend HTTP interactions
- Backend internal layering: API → Services → Data & ML modules
- ML pipeline stages: feature extraction → LightGBM → predictions → recommendations
- Data storage: Supabase tables, Neo4j graph, Redis cache
- External calls to Mistral AI
- Containers/orchestration (Docker Compose) if relevant

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User"]:::user

    %% Frontend Layer
    subgraph "Frontend (React UI)"
        FE["React App"]:::frontend
    end

    User -->|"interacts"| FE

    %% Backend Layer
    subgraph "Backend (FastAPI REST API)"
        subgraph "API Endpoints"
            auth["auth.py"]:::backend
            quiz_ep["quiz.py"]:::backend
            predict["predict.py"]:::backend
            analyze["analyze.py"]:::backend
            adaptive["adaptive_quiz.py"]:::backend
            onboarding["onboarding.py"]:::backend
        end
        subgraph "Service Layer"
            quiz_svc["quiz_service"]:::backend
            analytics_svc["analytics_service"]:::backend
        end
        subgraph "Data Access Layer"
            supabase_client["supabase_client.py"]:::db
            supabase_db["supabase_db.py"]:::db
            neo4j_client["neo4j_client.py"]:::db
            init_neo4j["init_neo4j.py"]:::db
        end
        subgraph "ML Pipeline"
            embed["embed.py"]:::ml
            extract["extract.py"]:::ml
            kg["knowledge_graph.py"]:::ml
            llm_mod["llm.py"]:::ml
            quiz_mod["quiz.py"]:::ml
            scoring["scoring.py"]:::ml
            student_an["student_analyzer.py"]:::ml
        end
    end

    %% Data Stores
    subgraph "Data Stores"
        Postgres["PostgreSQL"]:::db
        Neo4jDB["Neo4j"]:::db
        Redis["Redis"]:::db
    end

    %% External Services
    subgraph "External Services"
        Mistral["Mistral AI API"]:::external
    end

    %% Infrastructure & Config
    Config["Configuration (.env, config.py)"]:::config
    Docker["Docker Compose & Containers"]:::infra

    %% Connections
    FE -->|"REST /auth, /quiz, /predict"| auth
    FE -->|"REST /analyze"| analyze
    FE -->|"REST /onboarding"| onboarding
    auth -->|calls| quiz_svc
    quiz_ep -->|calls| quiz_svc
    predict -->|calls| analytics_svc
    analyze -->|calls| analytics_svc
    adaptive -->|calls| quiz_svc
    onboarding -->|calls| analytics_svc

    quiz_svc -->|uses| supabase_client
    quiz_svc -->|uses| neo4j_client
    quiz_svc -->|runs| quiz_mod
    analytics_svc -->|runs| extract
    analytics_svc -->|runs| scoring
    analytics_svc -->|runs| student_an
    analytics_svc -->|runs| kg

    supabase_client -->|CRUD| Postgres
    supabase_db -->|migration| Postgres
    neo4j_client -->|graph ops| Neo4jDB
    init_neo4j -->|setup| Neo4jDB

    ml_pipeline["ML Pipeline"] -->|feature| embed
    llm_mod -->|generates quizzes| Mistral
    scoring -->|evaluates| Mistral

    Config -->|env| Docker
    Docker -->|deploy| FE
    Docker -->|deploy| backend_app["FastAPI App"]:::backend

    %% Styling
    classDef user fill:#eef,stroke:#333,stroke-width:1px;
    classDef frontend fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
    classDef backend fill:#c8e6c9,stroke:#43a047,stroke-width:2px;
    classDef db fill:#eeeeee,stroke:#757575,stroke-width:1px;
    classDef ml fill:#ffe0b2,stroke:#fb8c00,stroke-width:2px;
    classDef external fill:#e1bee7,stroke:#8e24aa,stroke-width:2px;
    classDef config fill:#d7ccc8,stroke:#6d4c41,stroke-width:1px;
    classDef infra fill:#cfd8dc,stroke:#607d8b,stroke-width:1px;

    %% Click Events - Frontend
    click FE "https://github.com/shafwansafi06/mindbridge/tree/main/src/"
    click FE "https://github.com/shafwansafi06/mindbridge/tree/main/src/components/"
    click FE "https://github.com/shafwansafi06/mindbridge/tree/main/src/pages/"
    click FE "https://github.com/shafwansafi06/mindbridge/tree/main/src/lib/"
    click FE "https://github.com/shafwansafi06/mindbridge/tree/main/src/contexts/"
    click FE "https://github.com/shafwansafi06/mindbridge/tree/main/src/hooks/"

    %% Click Events - Backend API
    click auth "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/api/auth.py"
    click quiz_ep "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/api/quiz.py"
    click predict "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/api/predict.py"
    click analyze "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/api/analyze.py"
    click adaptive "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/api/adaptive_quiz.py"
    click onboarding "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/api/onboarding.py"
    click main "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/main.py"

    %% Click Events - Config
    click Config "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/core/config.py"
    click Config "https://github.com/shafwansafi06/mindbridge/blob/main/.env"
    click Config "https://github.com/shafwansafi06/mindbridge/blob/main/.env.example"
    click Config "https://github.com/shafwansafi06/mindbridge/blob/main/backend/.env.example"

    %% Click Events - Data Access
    click supabase_client "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/db/supabase_client.py"
    click supabase_db "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/db/supabase_db.py"
    click neo4j_client "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/db/neo4j_client.py"
    click init_neo4j "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/db/init_neo4j.py"

    %% Click Events - ML Pipeline
    click embed "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/ml_pipeline/embed.py"
    click extract "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/ml_pipeline/extract.py"
    click kg "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/ml_pipeline/knowledge_graph.py"
    click llm_mod "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/ml_pipeline/llm.py"
    click quiz_mod "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/ml_pipeline/quiz.py"
    click scoring "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/ml_pipeline/scoring.py"
    click student_an "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/ml_pipeline/student_analyzer.py"
    click models "https://github.com/shafwansafi06/mindbridge/tree/main/backend/app/ml_pipeline/models/"

    %% Click Events - Docker & Orchestration
    click Docker "https://github.com/shafwansafi06/mindbridge/blob/main/docker-compose.yml"
    click Docker "https://github.com/shafwansafi06/mindbridge/blob/main/Dockerfile.frontend"
    click Docker "https://github.com/shafwansafi06/mindbridge/tree/main/backend/Dockerfile"
    click Docker "https://github.com/shafwansafi06/mindbridge/blob/main/README.md"
    click Docker "https://github.com/shafwansafi06/mindbridge/blob/main/backend/app/ml_pipeline/ML_MODEL_DOCS.md"
    click Docker "https://github.com/shafwansafi06/mindbridge/blob/main/backend/CORS_GUIDE.md"
    click Docker "https://github.com/shafwansafi06/mindbridge/blob/main/backend/SUPABASE_SETUP.md"
```
