# jeetpitale/classflow architecture

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

- Interactive diagram: https://gitdiagram.com/jeetpitale/classflow
- Repository: https://github.com/jeetpitale/classflow

## Overview

1. **Overall shape**: ClassFlow is a two-tier LMS with a React/Vite frontend and a PHP/MySQL backend. The frontend is a single-page app for student, teacher, and admin roles; the backend exposes a REST-style API and owns persistence, authentication, uploads, and notification logic.

2. **Frontend shell**: `src/main.jsx` boots the app, `src/App.jsx` wires routing, and `src/pages/*` contains the role-specific screens. The UI is built from shared components in `src/components/*`, especially the dashboard layout shell (`DashboardLayout`, `Header`, `Sidebar`) plus many reusable shadcn/radix-style primitives.

3. **Role-based application areas**: The page structure is strongly partitioned by user type:
   - `src/pages/student/*` for dashboards, quizzes, assignments, materials, marks, startup, schedule
   - `src/pages/teacher/*` for dashboards, quizzes, assignments, syllabus, materials, feedback
   - `src/pages/admin/*` for dashboards, announcements, performance, schedules, startups, syllabus tracking, user management  
   This is a clear architectural boundary for authorization and navigation.

4. **Frontend state and API access**: `src/contexts/AuthContext.jsx` centralizes authentication state, while `src/services/api.js` is the main HTTP boundary to the backend. The frontend also includes lightweight utility layers such as `src/hooks/*`, `src/lib/utils.js`, and `src/types/*`. React Query is mentioned in the README, so the app likely treats server data as cached remote state rather than local application state.

5. **Backend entry and request flow**: The backend is organized as a classic PHP API with `backend/index.php` as the entry point, then controller classes in `backend/controllers/*`, domain models in `backend/models/*`, and shared utilities in `backend/utils/*`. Requests flow from the browser to the API endpoint, through a controller, into a model/database operation, and then back as standardized JSON responses.

6. **Backend domain modules**: The codebase is split by business capability rather than generic CRUD:
   - `AuthController`, `ProfileController`, `DashboardController`
   - content and learning modules: `AnnouncementController`, `AssignmentController`, `MaterialController`, `QuizController`, `SyllabusController`
   - role/admin management: `StudentController`, `TeacherController`, `StartupController`
   - messaging/alerts: `NotificationController`  
   Matching model classes mirror those domains, which makes the backend fairly modular.

7. **Security and cross-cutting services**: `backend/utils/JWTHandler.php` suggests token-based auth, `RateLimiter.php` adds API throttling, and `Response.php` likely standardizes API payloads and error handling. `NotificationHelper.php` encapsulates notification generation/publishing logic, so notifications are treated as a shared service rather than duplicated in each controller.

8. **Data layer**: Persistence is MySQL, configured in `backend/config/database.php` with environment-driven settings and optional SSL CA support (`backend/config/certs/*`). Schema evolution is handled through SQL scripts in `backend/database/*` plus additional migrations in `backend/migrations/*`, indicating the project uses direct SQL migrations rather than a heavyweight ORM.

9. **File and artifact storage**: User-generated content is stored outside the database in upload directories such as `backend/uploads/` and top-level `uploads/`, with subfolders for assignments and profiles. This is an important boundary: the DB tracks metadata, while physical files live on disk and are served separately.

10. **Deployment/runtime concerns**: The repository contains multiple hosting artifacts: `backend/nginx.conf`, `backend/.htaccess`, `backend/startup.sh`, `backend/.azure/config`, `.github/workflows/*`, and `vercel.json`. That suggests the app can be deployed with a PHP server behind Nginx/Apache, with CI/CD automation and Azure-related configuration for the backend, while the frontend is built and served as a static Vite app.

11. **Operational configuration**: The README and file tree show environment-sensitive setup for local vs production endpoints. The frontend points at an API base URL in `src/services/api.js`, and the backend reads DB and SSL settings from env/config files, so the architecture expects the frontend and backend to be independently deployable and configurable.

12. **Primary end-to-end flow**: A typical interaction is: user signs in through the React app → auth state is stored in the frontend context → the app calls the PHP API via `api.js` → controller validates/authorizes via JWT/rate limiting → model reads/writes MySQL and possibly stores files → the API returns JSON → the frontend renders role-specific dashboard and list/detail views.

Main entry points: [`src/App.jsx`](https://github.com/jeetpitale/classflow/blob/main/src/App.jsx) (Router), [`backend/controllers`](https://github.com/jeetpitale/classflow/tree/main/backend/controllers) (Controllers), [`src/services/api.js`](https://github.com/jeetpitale/classflow/blob/main/src/services/api.js) (API Client), [`backend/models`](https://github.com/jeetpitale/classflow/tree/main/backend/models) (Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_main(("Entry<br/>vite bootstrap<br/>[main.jsx]"))
  node_app["Router<br/>app shell<br/>[App.jsx]"]
  node_auth_ctx["Auth State<br/>react context<br/>[AuthContext.jsx]"]
  node_api_client["API Client<br/>http boundary<br/>[api.js]"]
  node_layout["Dashboard Shell<br/>ui layout"]
  node_student_pages["Student Area<br/>role pages"]
  node_teacher_pages["Teacher Area<br/>role pages"]
  node_admin_pages["Admin Area<br/>role pages"]
  node_ui_primitives["UI Primitives<br/>component library"]
end

subgraph group_backend["Backend"]
  node_entry_php(("API Entry<br/>php front controller<br/>[index.php]"))
  node_controllers["Controllers"]
  node_models["Models"]
  node_utils["Core Utils<br/>cross-cutting services"]
  node_db_config["DB Config<br/>mysql config<br/>[database.php]"]
  node_schema["Schema/Migrations<br/>sql migrations"]
  node_uploads_dir[("File Storage<br/>artifact storage")]
end

subgraph group_ops["Deployment"]
  node_deploy_cfg["Deploy Config<br/>runtime config<br/>[nginx.conf]"]
  node_ci["CI/CD<br/>workflow"]
  node_frontend_build["Static Build<br/>vite app<br/>[vercel.json]"]
end

node_main -->|"starts"| node_app
node_app -->|"uses"| node_auth_ctx
node_app -->|"wraps"| node_layout
node_app -->|"routes"| node_student_pages
node_app -->|"routes"| node_teacher_pages
node_app -->|"routes"| node_admin_pages
node_student_pages -->|"fetches"| node_api_client
node_teacher_pages -->|"fetches"| node_api_client
node_admin_pages -->|"fetches"| node_api_client
node_layout -->|"composes"| node_ui_primitives
node_api_client -->|"calls"| node_entry_php
node_entry_php -->|"dispatches"| node_controllers
node_controllers -->|"uses"| node_utils
node_controllers -->|"persists"| node_models
node_models -->|"connects"| node_db_config
node_models -.->|"migrated by"| node_schema
node_controllers -->|"stores files"| node_uploads_dir
node_utils -.->|"references"| node_uploads_dir
node_deploy_cfg -.->|"serves"| node_entry_php
node_ci -.->|"deploys"| node_deploy_cfg
node_frontend_build -.->|"serves"| node_app

click node_main "https://github.com/jeetpitale/classflow/blob/main/src/main.jsx"
click node_app "https://github.com/jeetpitale/classflow/blob/main/src/App.jsx"
click node_auth_ctx "https://github.com/jeetpitale/classflow/blob/main/src/contexts/AuthContext.jsx"
click node_api_client "https://github.com/jeetpitale/classflow/blob/main/src/services/api.js"
click node_layout "https://github.com/jeetpitale/classflow/blob/main/src/components/layout/DashboardLayout.jsx"
click node_student_pages "https://github.com/jeetpitale/classflow/tree/main/src/pages/student"
click node_teacher_pages "https://github.com/jeetpitale/classflow/tree/main/src/pages/teacher"
click node_admin_pages "https://github.com/jeetpitale/classflow/tree/main/src/pages/admin"
click node_ui_primitives "https://github.com/jeetpitale/classflow/tree/main/src/components/ui"
click node_entry_php "https://github.com/jeetpitale/classflow/blob/main/backend/index.php"
click node_controllers "https://github.com/jeetpitale/classflow/tree/main/backend/controllers"
click node_models "https://github.com/jeetpitale/classflow/tree/main/backend/models"
click node_utils "https://github.com/jeetpitale/classflow/tree/main/backend/utils"
click node_db_config "https://github.com/jeetpitale/classflow/blob/main/backend/config/database.php"
click node_schema "https://github.com/jeetpitale/classflow/tree/main/backend/database"
click node_uploads_dir "https://github.com/jeetpitale/classflow/tree/main/backend/uploads"
click node_deploy_cfg "https://github.com/jeetpitale/classflow/blob/main/backend/nginx.conf"
click node_ci "https://github.com/jeetpitale/classflow/blob/main/.github/workflows/main_classflow-backend-jeet.yml"
click node_frontend_build "https://github.com/jeetpitale/classflow/blob/main/vercel.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_app,node_auth_ctx,node_api_client,node_layout,node_student_pages,node_teacher_pages,node_admin_pages,node_ui_primitives toneBlue
class node_entry_php,node_controllers,node_models,node_utils,node_db_config,node_schema,node_uploads_dir toneAmber
class node_deploy_cfg,node_ci,node_frontend_build toneMint
```

## Components

### Frontend

React/Vite single-page app and shared UI

- [Entry](https://github.com/jeetpitale/classflow/blob/main/src/main.jsx): vite bootstrap · Bootstraps the React app · `src/main.jsx`
- [Router](https://github.com/jeetpitale/classflow/blob/main/src/App.jsx): app shell · Wires top-level routing and app structure · `src/App.jsx`
- [Auth State](https://github.com/jeetpitale/classflow/blob/main/src/contexts/AuthContext.jsx): react context · Centralizes login state and user session · `src/contexts/AuthContext.jsx`
- [API Client](https://github.com/jeetpitale/classflow/blob/main/src/services/api.js): http boundary · Primary frontend wrapper for backend requests · `src/services/api.js`
- [Dashboard Shell](https://github.com/jeetpitale/classflow/blob/main/src/components/layout/DashboardLayout.jsx): ui layout · Shared dashboard chrome for role-based screens · `src/components/layout/DashboardLayout.jsx`
- [Student Area](https://github.com/jeetpitale/classflow/tree/main/src/pages/student): role pages · Student dashboards, learning, and assessments · `src/pages/student`
- [Teacher Area](https://github.com/jeetpitale/classflow/tree/main/src/pages/teacher): role pages · Teacher dashboards, content, and grading tools · `src/pages/teacher`
- [Admin Area](https://github.com/jeetpitale/classflow/tree/main/src/pages/admin): role pages · Admin dashboards, governance, and management screens · `src/pages/admin`
- [UI Primitives](https://github.com/jeetpitale/classflow/tree/main/src/components/ui): component library · Reusable forms, tables, dialogs, and other shared widgets · `src/components/ui`

### Backend

PHP API, persistence, and domain logic

- [API Entry](https://github.com/jeetpitale/classflow/blob/main/backend/index.php): php front controller · Main backend request entry point · `backend/index.php`
- [Controllers](https://github.com/jeetpitale/classflow/tree/main/backend/controllers): api controllers · Request handlers organized by domain · `backend/controllers`
- [Models](https://github.com/jeetpitale/classflow/tree/main/backend/models): domain models · Persistence-facing domain objects · `backend/models`
- [Core Utils](https://github.com/jeetpitale/classflow/tree/main/backend/utils): cross-cutting services · Auth, responses, throttling, and notification helpers · `backend/utils`
- [DB Config](https://github.com/jeetpitale/classflow/blob/main/backend/config/database.php): mysql config · Environment-driven database connection settings · `backend/config/database.php`
- [Schema/Migrations](https://github.com/jeetpitale/classflow/tree/main/backend/database): sql migrations · Database schema and incremental SQL changes · `backend/database`
- [File Storage](https://github.com/jeetpitale/classflow/tree/main/backend/uploads): artifact storage · On-disk uploads for assignments and profiles · `backend/uploads`

### Deployment

Hosting, CI, and runtime configuration

- [Deploy Config](https://github.com/jeetpitale/classflow/blob/main/backend/nginx.conf): runtime config · Nginx, Apache, startup, and cloud deployment files · `backend/nginx.conf`
- [CI/CD](https://github.com/jeetpitale/classflow/blob/main/.github/workflows/main_classflow-backend-jeet.yml): workflow · GitHub Actions and hosting configuration · `.github/workflows/main_classflow-backend-jeet.yml`
- [Static Build](https://github.com/jeetpitale/classflow/blob/main/vercel.json): vite app · Frontend build and static hosting configuration · `vercel.json`

## Connections

- Entry → Router: starts · Application bootstraps routing and UI shell
- Router → Auth State: uses · Routes and screens depend on auth state
- Router → Dashboard Shell: wraps · Role pages render inside shared dashboard shell
- Router → Student Area: routes · Student screens are mounted through app routing
- Router → Teacher Area: routes · Teacher screens are mounted through app routing
- Router → Admin Area: routes · Admin screens are mounted through app routing
- Student Area → API Client: fetches · Student features load remote data through the API client
- Teacher Area → API Client: fetches · Teacher features load remote data through the API client
- Admin Area → API Client: fetches · Admin features load remote data through the API client
- Dashboard Shell → UI Primitives: composes · Shell is built from shared UI primitives
- API Client → API Entry: calls · Frontend requests hit the PHP API entry point
- API Entry → Controllers: dispatches · Requests are routed to domain controllers
- Controllers → Core Utils: uses · Controllers rely on auth, response, and throttling helpers
- Controllers → Models: persists · Controllers delegate domain reads and writes to models
- Models → DB Config: connects · Models use the configured MySQL connection
- Models → Schema/Migrations: migrated by · Database structure is defined by SQL schema and migration scripts
- Controllers → File Storage: stores files · Content controllers write uploaded artifacts to disk
- Core Utils → File Storage: references · Shared helpers may coordinate file-related notifications or paths
- Deploy Config → API Entry: serves · Runtime config hosts the backend API
- CI/CD → Deploy Config: deploys · Workflow and cloud config automate backend delivery
- Static Build → Router: serves · Static frontend build serves the React app
