How hamzakhan0712/qsync-frontend works
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?