# hamzakhan0712/qsync-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/hamzakhan0712/qsync-frontend
- Repository: https://github.com/hamzakhan0712/qsync-frontend

## Overview

##### Project type and purpose
- Qsync is a full‑stack, queue‑management web application with an AI/ML microservice and a Streamlit business dashboard.
- The React/Vite frontend provides user‑facing pages for customers, business owners, and admins.
- A Python backend (FastAPI) exposes REST endpoints for queue operations, authentication, analytics, and invokes an ML recommender.
- A Streamlit app under `AI/BusinessDashboard.py` provides a business analytics dashboard.
- The ML microservice loads a pickled model (`gbc_queueu_recommender.pkl`) to recommend optimal queue settings or next actions.

##### File structure
- Top‑level “AI/” directory:
- `api/routes.py` — FastAPI controllers
- `config/model_loader.py` — loads the ML model
- `models/schemas.py` — Pydantic request/response schemas
- `services/recommender.py` & `fine_tune.py` — ML inference & fine‑tuning logic
- `BusinessDashboard.py` — Streamlit dashboard UI
- `main.py` — FastAPI application entry point
- Root React/Vite SPA:
- `src/` — React components, pages, routing, context & hooks
- `src/services/…` — API client wrappers (auth, queueService, etc.)
- `public/`, `index.html`, `vite.config.js` — static assets & build config
- Tailwind + custom UI primitives under `src/components/ui/`
- Config and tooling:
- `.streamlit/config.toml` — Streamlit settings
- `package.json` / `requirements.txt` — JS & Python dependencies

##### README
- Very minimal; the file structure itself reveals the architecture.
- The name “Qsync” implies queue synchronization and management with AI‑driven recommendations.

##### Main components & their interactions
A. Web Client (Browser / React App)
- Runs on user's browser
- Served by Vite / static host
- Pages: Landing, Login, Dashboard, QueuePage, AdminDashboard, etc.
B. API Gateway / Backend (Python FastAPI)
- Exposes REST endpoints under `/api/*`
- Controllers: `AI/api/routes.py`
- Business logic / service layer:
- Auth, business, queue, analytics services
- ML recommender & fine‑tune services
- Model loader reads the pickled model at startup.
- Pydantic schemas validate payloads.
C. ML Model Storage
- `AI/models/gbc_queueu_recommender.pkl`
- Loaded via `config/model_loader.py`
D. Streamlit Business Dashboard
- `AI/BusinessDashboard.py`
- Visualizes queue performance, customer analytics
- Reads from the same backend or via direct model calls
E. (Optional) Database / Persistence
- Not visible in code, but implied by queueService, businessService, etc.
- Could be PostgreSQL / MongoDB / any SQL database
- Accessed by the FastAPI service layer
F. External Services
- Potentially OpenAI or other APIs for fine‑tuning
- Third‑party analytics or notification services

##### Relationships & data flows
- Auth calls → AuthService
- Queue calls → QueueService
- Business calls → BusinessService

##### Architectural patterns & design principles
- Microservice separation: Frontend SPA, Backend API, ML microservice, Analytics dashboard
- Layered architecture in backend:
- Routes (controllers) → Services (business logic) → Data/model loader → Persistence
- Modular React: component‑based, context for global state, hooks for cross‑cutting concerns
- Model‑serving pattern: separate config/loader, pluggable service modules

##### Final checklist
- Have you separated UI vs. API vs. ML vs. Analytics?
- Are all REST endpoints and data flows annotated?
- Did you highlight the pickled ML model and loader?
- Is there a clear representation of persistence (DB)?
- Are external dependencies (e.g., OpenAI) shown if used?
- Did you group related modules under logical subsystems?

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Web Client
    subgraph "Web Client (React/Vite SPA)"
        direction TB
        index["index.html"]:::frontend
        vite["vite.config.js"]:::frontend
        pkg["package.json"]:::frontend
        public["public"]:::frontend
        subgraph "Source Code"
            direction TB
            src_dir["/src"]:::frontend
            subgraph "Router"
                direction TB
                router1["index.jsx"]:::frontend
                router2["ProtectedRoute.jsx"]:::frontend
            end
            subgraph "Pages"
                pages["/src/pages"]:::frontend
            end
            subgraph "UI Components"
                ui["/src/components/ui"]:::frontend
                comp["/src/components"]:::frontend
            end
            subgraph "API Clients & Services"
                apiClient["apiClient.js"]:::frontend
                services["/src/services"]:::frontend
            end
            subgraph "Context & Hooks"
                context["/src/context"]:::frontend
                hooks["/src/hooks"]:::frontend
            end
        end
    end

    %% Backend API
    subgraph "Backend API (FastAPI)"
        direction TB
        main["main.py"]:::backend
        routes["routes.py"]:::backend
        model_loader["model_loader.py"]:::backend
        schemas["schemas.py"]:::backend
        recommender["recommender.py"]:::backend
        fine_tune["fine_tune.py"]:::backend
        utils["time_utils.py"]:::backend
        requirements["requirements.txt"]:::backend
    end

    %% ML Model Storage
    gbc["gbc_queueu_recommender.pkl"]:::datastore

    %% Streamlit Dashboard
    subgraph "Business Analytics (Streamlit)"
        direction TB
        board["BusinessDashboard.py"]:::analytics
        streamconfig["config.toml"]:::analytics
    end

    %% Database & External
    db["Database"]:::datastore
    extAI["External AI API"]:::external

    %% Connections
    index -->|"serves bundle"| src_dir
    apiClient -->|"/api/* calls"| routes
    routes -->|calls services| recommender
    routes -->|calls services| fine_tune
    routes -->|validates via schemas| schemas
    routes -->|exposes endpoints| main
    recommender -->|loads model| model_loader
    model_loader -->|loads file| gbc
    recommender -->|inference| gbc
    routes -->|CRUD ops| db
    fine_tune -->|calls| extAI
    board -->|calls API or imports| routes
    board -->|uses model_loader| model_loader

    %% Click Events
    click index "https://github.com/hamzakhan0712/qsync-frontend/blob/main/index.html"
    click vite "https://github.com/hamzakhan0712/qsync-frontend/blob/main/vite.config.js"
    click pkg "https://github.com/hamzakhan0712/qsync-frontend/blob/main/package.json"
    click public "https://github.com/hamzakhan0712/qsync-frontend/tree/main/public"
    click src_dir "https://github.com/hamzakhan0712/qsync-frontend/tree/main//src"
    click router1 "https://github.com/hamzakhan0712/qsync-frontend/blob/main//src/router/index.jsx"
    click router2 "https://github.com/hamzakhan0712/qsync-frontend/blob/main//src/router/ProtectedRoute.jsx"
    click pages "https://github.com/hamzakhan0712/qsync-frontend/tree/main//src/pages"
    click ui "https://github.com/hamzakhan0712/qsync-frontend/tree/main//src/components/ui"
    click comp "https://github.com/hamzakhan0712/qsync-frontend/tree/main//src/components"
    click apiClient "https://github.com/hamzakhan0712/qsync-frontend/blob/main//src/api/apiClient.js"
    click services "https://github.com/hamzakhan0712/qsync-frontend/tree/main//src/services"
    click context "https://github.com/hamzakhan0712/qsync-frontend/tree/main//src/context"
    click hooks "https://github.com/hamzakhan0712/qsync-frontend/tree/main//src/hooks"
    click main "https://github.com/hamzakhan0712/qsync-frontend/blob/main//AI/main.py"
    click routes "https://github.com/hamzakhan0712/qsync-frontend/blob/main//AI/api/routes.py"
    click model_loader "https://github.com/hamzakhan0712/qsync-frontend/blob/main//AI/config/model_loader.py"
    click schemas "https://github.com/hamzakhan0712/qsync-frontend/blob/main//AI/models/schemas.py"
    click recommender "https://github.com/hamzakhan0712/qsync-frontend/blob/main//AI/services/recommender.py"
    click fine_tune "https://github.com/hamzakhan0712/qsync-frontend/blob/main//AI/services/fine_tune.py"
    click utils "https://github.com/hamzakhan0712/qsync-frontend/blob/main//AI/utils/time_utils.py"
    click requirements "https://github.com/hamzakhan0712/qsync-frontend/blob/main//AI/requirements.txt"
    click gbc "https://github.com/hamzakhan0712/qsync-frontend/blob/main//AI/models/gbc_queueu_recommender.pkl"
    click board "https://github.com/hamzakhan0712/qsync-frontend/blob/main//AI/BusinessDashboard.py"
    click streamconfig "https://github.com/hamzakhan0712/qsync-frontend/blob/main//AI/.streamlit/config.toml"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#3399ff,color:#000
    classDef backend fill:#d4edda,stroke:#28a745,color:#000
    classDef datastore fill:#ffe5b4,stroke:#ff9900,color:#000
    classDef analytics fill:#f3e5f5,stroke:#9c27b0,color:#000
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000
```
