# shafwansafi06/campus-entity-resolver architecture

> Architecture diagram of the GitHub repository shafwansafi06/campus-entity-resolver, 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/campus-entity-resolver
- Repository: https://github.com/shafwansafi06/campus-entity-resolver

## Overview

##### Project Type and Purpose
- This is a full-stack, AI-powered security & intelligence platform (“CampusFlow”) built for smart campuses.
- Frontend: React + TypeScript SPA; Backend: FastAPI Python server; ML Engine: PyTorch + XGBoost + LightGBM; Database/Auth: Supabase (PostgreSQL + Realtime + Auth).

##### File Structure
- Top level:
- package.json, vite.config.ts, tailwind.config.ts → frontend build & config
- src/ → React application (components/, pages/, contexts/, hooks/, lib/)
- public/ → static assets
- backend/ → Python FastAPI service
– main.py → API entrypoint
– database.py → Supabase integration
– entity_resolution.py → fuzzy-matching logic (FuzzyWuzzy)
– ml_predictor.py → loads ML artifacts (.pt, .json, .txt, .pkl)
– predictive_analytics.py → forecasts & analytics endpoints
– models/ → serialized ML models
- Config scripts: .env, creds.env, create-test-user.sh, bun.lockb, package-lock.json.

##### README Insights
- Tech stack and ML ensemble breakdown.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    External["External Data Sources"]:::external
    CardSwipe["Card Swipe System"]:::external
    WiFiLogs["WiFi Logs"]:::external
    CCTV["CCTV Feeds"]:::external
    LabBookings["Lab Booking System"]:::external

    %% UI Layer
    subgraph "UI Layer" 
        direction TB
        SPA["React SPA"]:::frontend
        APIUtils["API Utilities"]:::frontend
        AuthCtx["AuthContext"]:::frontend
        AlertsCtx["AlertsContext"]:::frontend
        PagesLogin["Login Page"]:::frontend
        PagesSignup["Signup Page"]:::frontend
        PagesAlerts["Alerts Page"]:::frontend
    end

    %% API Layer
    subgraph "API Layer" 
        direction TB
        FastAPI["FastAPI Server"]:::backend
        DBModule["Supabase Integration"]:::backend
        EntityRes["Entity Resolution"]:::backend
        Predictive["Predictive Analytics"]:::backend
        MLInfer["ML Inference"]:::backend
        Requirements["requirements.txt"]:::backend
    end

    %% Data Layer
    subgraph "Data & Models"
        direction TB
        SupabaseDB["Supabase Database & Auth"]:::database
        ModelArtifacts["Model Artifacts"]:::ml
        NNModel["NN Model (.pt)"]:::ml
        XGBModel["XGBoost Model (.json)"]:::ml
        LGBModel["LightGBM Model (.txt)"]:::ml
        PKLModel["Artifacts (.pkl)"]:::ml
        ModelsGitkeep[".gitkeep"]:::ml
        ModelsReadme["README.md"]:::ml
    end

    %% Flows
    External -->|Ingestion| SupabaseDB
    CardSwipe -->|Ingestion| SupabaseDB
    WiFiLogs -->|Ingestion| SupabaseDB
    CCTV -->|Ingestion| SupabaseDB
    LabBookings -->|Ingestion| SupabaseDB

    SPA -->|HTTP/WS Calls| FastAPI
    APIUtils -->|uses| SPA
    AuthCtx -->|provides| SPA
    AlertsCtx -->|provides| SPA
    PagesLogin -->|UI Route| SPA
    PagesSignup -->|UI Route| SPA
    PagesAlerts -->|UI Route| SPA

    FastAPI -->|SQL/Realtime| SupabaseDB
    FastAPI -->|call| EntityRes
    FastAPI -->|call| Predictive
    FastAPI -->|call| MLInfer

    DBModule -->|integrates| SupabaseDB

    MLInfer -->|loads| NNModel
    MLInfer -->|loads| XGBModel
    MLInfer -->|loads| LGBModel
    MLInfer -->|loads| PKLModel

    ModelArtifacts --> NNModel
    ModelArtifacts --> XGBModel
    ModelArtifacts --> LGBModel
    ModelArtifacts --> PKLModel
    ModelArtifacts --> ModelsGitkeep
    ModelArtifacts --> ModelsReadme

    %% Click Events
    click SPA "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/package.json"
    click SPA "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/vite.config.ts"
    click SPA "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/tailwind.config.ts"
    click SPA "https://github.com/shafwansafi06/campus-entity-resolver/tree/main/src/"
    click SPA "https://github.com/shafwansafi06/campus-entity-resolver/tree/main/public/"
    click SPA "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/index.html"
    click FastAPI "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/backend/main.py"
    click DBModule "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/backend/database.py"
    click DBModule "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/src/lib/supabase.ts"
    click EntityRes "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/backend/entity_resolution.py"
    click Predictive "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/backend/predictive_analytics.py"
    click MLInfer "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/backend/ml_predictor.py"
    click NNModel "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/backend/models/spaceflow_nn_model.pt"
    click XGBModel "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/backend/models/spaceflow_xgboost.json"
    click LGBModel "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/backend/models/spaceflow_lightgbm.txt"
    click PKLModel "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/backend/models/spaceflow_artifacts.pkl"
    click ModelsGitkeep "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/backend/models/.gitkeep"
    click ModelsReadme "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/backend/models/README.md"
    click Requirements "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/backend/requirements.txt"
    click APIUtils "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/src/lib/api.ts"
    click APIUtils "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/src/hooks/useAPI.ts"
    click AuthCtx "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/src/contexts/AuthContext.tsx"
    click AlertsCtx "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/src/contexts/AlertsContext.tsx"
    click PagesLogin "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/src/pages/Login.tsx"
    click PagesSignup "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/src/pages/Signup.tsx"
    click PagesAlerts "https://github.com/shafwansafi06/campus-entity-resolver/blob/main/src/pages/Alerts.tsx"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef backend fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef database fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef ml fill:#e1bee7,stroke:#8e24aa,color:#4a148c
    classDef external fill:#e0e0e0,stroke:#9e9e9e,color:#424242
```
