# shahriar-hossain-alvi/edutrack-frontend architecture

> Architecture diagram of the GitHub repository shahriar-hossain-alvi/edutrack-frontend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shahriar-hossain-alvi/edutrack-frontend
- Repository: https://github.com/shahriar-hossain-alvi/edutrack-frontend

## Overview

1. **Project type and boundary**
   - This repository is the **React frontend** for Edutrack, a result management system.
   - It does **not** contain the FastAPI/PostgreSQL backend; instead it consumes backend APIs for auth, user management, marks, courses, logs, and results.

2. **Application shell**
   - The app boots from `src/main.jsx`, with global styling in `src/index.css`.
   - Root-level concerns are provided by `src/provider/AuthProvider.jsx` and `src/provider/ThemeProvider.jsx`, which make authentication state and UI theme available across the tree.

3. **Routing structure**
   - Routing is split by audience and access level:
     - `src/app/routes/Routes.jsx` for the overall route composition
     - `AdminRoutes.jsx`, `TeacherRoutes.jsx`, `StudentRoutes.jsx` for role-specific route sets
   - Public pages include signin, error, and unauthorized screens.
   - Private pages include authenticated views such as results and single-user details.

4. **Access control and redirects**
   - `src/components/RouteHandlers/PrivateRoutes.jsx` protects authenticated routes.
   - `RoleBasedRedirects.jsx` handles user-type redirection after login or when a role lands on an incompatible route.
   - This makes authorization a routing concern in the frontend, mirroring the backend role model.

5. **Layout hierarchy**
   - The UI uses separate shell layouts for different audiences:
     - `MainLayout.jsx`
     - `AdminLayout.jsx`
     - `TeacherLayout.jsx`
     - `StudentLayout.jsx`
   - These layouts likely define shared chrome such as navigation, sidebars, and page framing, while the inner route content changes by role.

6. **Authentication and API access**
   - `src/hooks/useAuth.jsx` exposes auth state and likely user profile/session details.
   - `src/utils/axios/axiosPublic.js` and `axiosSecure.js` define two API clients:
     - public requests for unauthenticated endpoints
     - secure requests for authenticated endpoints
   - `useAxiosInterceptor.jsx` is a key cross-cutting hook; it aligns frontend requests with the backend’s cookie-based JWT setup described in the README.

7. **Feature areas by role**
   - **Admin** pages dominate the app:
     - dashboard, users, departments/semesters, subjects, assigned courses, marks, audit logs, user creation
   - **Teacher** pages focus on assigned courses and profile
   - **Student** pages focus on offered courses, marks, and profile
   - This suggests the frontend is organized around a role-based CRUD and read-only workflow model rather than a single generic dashboard.

8. **Page composition pattern**
   - `src/pages/*` contains route-level screens.
   - `src/components/pageComponents/*` contains the transactional or form-heavy UI used inside those pages.
   - Examples:
     - user creation tabs for students/teachers
     - department and semester forms/tables
     - mark insertion and mark update flows
     - subject creation and course assignment flows
   - This split keeps routing/page concerns separate from reusable domain UI.

9. **Shared UI building blocks**
   - `src/components/ui` contains reusable presentation pieces:
     - navbar, drawer sidebar, loading spinner, skeletons, charts, dashboard cards, recent audit logs, generic user forms
   - These are used across multiple pages and layouts, acting as the frontend’s design system layer.

10. **Hooks and client behavior**
   - `useDebounce.jsx` indicates request-throttled interactions, likely for search or filter inputs.
   - `useTheme.jsx` centralizes theme switching.
   - `useAxiosSecure.jsx` and `useAxiosPublic.jsx` encapsulate API client selection, keeping pages free from request plumbing.

11. **Utilities and helpers**
   - `src/utils/errorMessageParser/errorMessageParser.js` normalizes backend/API errors into user-facing messages.
   - `src/utils/SectionHeader/SectionHeader.jsx` is a small shared layout utility.
   - This layer supports consistent UX around API failures and section presentation.

12. **Data flow at a glance**
   - User signs in through the auth page.
   - Auth state is stored in the provider and propagated through the app.
   - Protected routes and role-based redirects determine which layout and pages are visible.
   - Pages invoke secure/public axios clients to call the backend.
   - Backend responses populate tables, dashboards, charts, and forms; errors are parsed into readable messages.

13. **Deployment and runtime**
   - The frontend is built with **Vite** and deployed separately from the backend.
   - `Dockerfile` and `docker-compose.yml` support containerized local development/builds.
   - `vercel.json` indicates Vercel deployment support for the frontend.
   - `public/test_data.json` suggests some local/mock data usage for development or UI testing.

14. **Architecture summary**
   - Overall, this is a **role-based single-page application** with:
     - auth/theme providers at the root
     - route guards and role redirects
     - separate layouts per user type
     - page-level screens backed by reusable domain components
     - centralized axios clients and hooks for API access
   - The main architectural boundary is between this React client and the external FastAPI backend it consumes.

Main entry points: [`src/app/routes/Routes.jsx`](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/app/routes/Routes.jsx) (Routes), [`src/hooks/useAxiosPublic.jsx`](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/hooks/useAxiosPublic.jsx) (API Hooks), [`src/components/ui/Navbar.jsx`](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/components/ui/Navbar.jsx) (Shared UI), [`src/pages/admin/AdminDashboard.jsx`](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/pages/admin/AdminDashboard.jsx) (Admin Domain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Shell"]
  node_main(("Main<br/>entry<br/>[main.jsx]"))
  node_auth_provider["Auth Provider<br/>state provider<br/>[AuthProvider.jsx]"]
  node_theme_provider["Theme Provider<br/>state provider<br/>[ThemeProvider.jsx]"]
end

subgraph group_routing["Routing & Access"]
  node_routes["Routes<br/>route composer<br/>[Routes.jsx]"]
  node_private_routes["Private Routes<br/>route guard<br/>[PrivateRoutes.jsx]"]
  node_role_redirects["Role Redirects<br/>route logic"]
  node_admin_layout["Admin Layout<br/>shell layout<br/>[AdminLayout.jsx]"]
  node_teacher_layout["Teacher Layout<br/>shell layout<br/>[TeacherLayout.jsx]"]
  node_student_layout["Student Layout<br/>shell layout<br/>[StudentLayout.jsx]"]
  node_main_layout["Main Layout<br/>shell layout<br/>[MainLayout.jsx]"]
end

subgraph group_features["Feature Areas"]
  node_admin_domain["Admin Domain<br/>admin workflow<br/>[AdminDashboard.jsx]"]
  node_teacher_domain["Teacher Domain<br/>teacher workflow"]
  node_student_domain["Student Domain<br/>student workflow<br/>[OfferedCourses.jsx]"]
  node_auth_public["Auth & Public<br/>public screens<br/>[Signin.jsx]"]
end

subgraph group_shared["Shared Infrastructure"]
  node_api_hooks["API Hooks<br/>request hooks<br/>[useAxiosPublic.jsx]"]
  node_auth_hook["Auth Hook<br/>state hook<br/>[useAuth.jsx]"]
  node_theme_hook["Theme Hook<br/>state hook<br/>[useTheme.jsx]"]
  node_debounce_hook["Debounce Hook<br/>interaction hook<br/>[useDebounce.jsx]"]
  node_shared_ui["Shared UI<br/>ui kit<br/>[Navbar.jsx]"]
  node_page_components["Page Components<br/>domain ui"]
end

node_main -->|"wraps"| node_auth_provider
node_main -->|"wraps"| node_theme_provider
node_auth_provider -->|"feeds state"| node_routes
node_theme_provider -->|"feeds state"| node_main_layout
node_routes -->|"uses"| node_private_routes
node_routes -->|"uses"| node_role_redirects
node_routes -->|"renders"| node_main_layout
node_routes -->|"renders"| node_admin_layout
node_routes -->|"renders"| node_teacher_layout
node_routes -->|"renders"| node_student_layout
node_main_layout -->|"hosts"| node_auth_public
node_admin_layout -->|"hosts"| node_admin_domain
node_teacher_layout -->|"hosts"| node_teacher_domain
node_student_layout -->|"hosts"| node_student_domain
node_auth_public -->|"reads"| node_auth_hook
node_admin_domain -->|"calls"| node_api_hooks
node_teacher_domain -->|"calls"| node_api_hooks
node_student_domain -->|"calls"| node_api_hooks
node_admin_domain -->|"composes"| node_page_components
node_teacher_domain -->|"composes"| node_page_components
node_student_domain -->|"composes"| node_page_components
node_admin_domain -->|"uses"| node_shared_ui
node_teacher_domain -->|"uses"| node_shared_ui
node_student_domain -->|"uses"| node_shared_ui
node_api_hooks -->|"aligns with"| node_auth_hook
node_api_hooks -->|"supports"| node_debounce_hook
node_api_hooks -->|"drives"| node_shared_ui
node_theme_hook -->|"styles"| node_shared_ui

click node_main "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/main.jsx"
click node_auth_provider "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/provider/AuthProvider.jsx"
click node_theme_provider "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/provider/ThemeProvider.jsx"
click node_routes "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/app/routes/Routes.jsx"
click node_private_routes "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/components/RouteHandlers/PrivateRoutes.jsx"
click node_role_redirects "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/components/RouteHandlers/RoleBasedRedirects.jsx"
click node_admin_layout "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/app/layout/AdminLayout.jsx"
click node_teacher_layout "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/app/layout/TeacherLayout.jsx"
click node_student_layout "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/app/layout/StudentLayout.jsx"
click node_main_layout "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/app/layout/MainLayout.jsx"
click node_api_hooks "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/hooks/useAxiosPublic.jsx"
click node_auth_hook "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/hooks/useAuth.jsx"
click node_theme_hook "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/hooks/useTheme.jsx"
click node_debounce_hook "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/hooks/useDebounce.jsx"
click node_shared_ui "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/components/ui/Navbar.jsx"
click node_admin_domain "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/pages/admin/AdminDashboard.jsx"
click node_teacher_domain "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/pages/teacher/MyAssignedCourses.jsx"
click node_student_domain "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/pages/student/OfferedCourses.jsx"
click node_auth_public "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/pages/auth/Signin.jsx"
click node_page_components "https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/components/pageComponents/AddUserPage/CreateStudentTab.jsx"

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_auth_provider,node_theme_provider toneBlue
class node_routes,node_private_routes,node_role_redirects,node_admin_layout,node_teacher_layout,node_student_layout,node_main_layout toneAmber
class node_admin_domain,node_teacher_domain,node_student_domain,node_auth_public toneMint
class node_api_hooks,node_auth_hook,node_theme_hook,node_debounce_hook,node_shared_ui,node_page_components toneRose
```

## Components

### App Shell

Entry point and global providers

- [Main](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/main.jsx): entry · Vite React bootstrap · `src/main.jsx`
- [Auth Provider](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/provider/AuthProvider.jsx): state provider · Shares session and auth state · `src/provider/AuthProvider.jsx`
- [Theme Provider](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/provider/ThemeProvider.jsx): state provider · Shares UI theme state · `src/provider/ThemeProvider.jsx`

### Routing & Access

Route composition, guards, and role redirects

- [Routes](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/app/routes/Routes.jsx): route composer · Top-level route composition · `src/app/routes/Routes.jsx`
- [Private Routes](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/components/RouteHandlers/PrivateRoutes.jsx): route guard · Protects authenticated screens · `src/components/RouteHandlers/PrivateRoutes.jsx`
- [Role Redirects](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/components/RouteHandlers/RoleBasedRedirects.jsx): route logic · Sends users to role-appropriate screens · `src/components/RouteHandlers/RoleBasedRedirects.jsx`
- [Admin Layout](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/app/layout/AdminLayout.jsx): shell layout · Admin chrome and framing · `src/app/layout/AdminLayout.jsx`
- [Teacher Layout](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/app/layout/TeacherLayout.jsx): shell layout · Teacher chrome and framing · `src/app/layout/TeacherLayout.jsx`
- [Student Layout](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/app/layout/StudentLayout.jsx): shell layout · Student chrome and framing · `src/app/layout/StudentLayout.jsx`
- [Main Layout](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/app/layout/MainLayout.jsx): shell layout · Shared app framing · `src/app/layout/MainLayout.jsx`

### Feature Areas

Role-based page sets and domain workflows

- [Admin Domain](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/pages/admin/AdminDashboard.jsx): admin workflow · Dashboard, users, departments, semesters, subjects, marks, logs · `src/pages/admin/AdminDashboard.jsx`
- [Teacher Domain](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/pages/teacher/MyAssignedCourses.jsx): teacher workflow · Assigned courses and profile screens · `src/pages/teacher/MyAssignedCourses.jsx`
- [Student Domain](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/pages/student/OfferedCourses.jsx): student workflow · Offered courses, marks, and profile screens · `src/pages/student/OfferedCourses.jsx`
- [Auth & Public](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/pages/auth/Signin.jsx): public screens · Signin, error, and unauthorized pages · `src/pages/auth/Signin.jsx`

### Shared Infrastructure

Reusable UI, hooks, and API plumbing

- [API Hooks](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/hooks/useAxiosPublic.jsx): request hooks · Public/secure axios wrappers and interceptor · `src/hooks/useAxiosPublic.jsx`
- [Auth Hook](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/hooks/useAuth.jsx): state hook · Reads auth/session state · `src/hooks/useAuth.jsx`
- [Theme Hook](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/hooks/useTheme.jsx): state hook · Controls theme switching · `src/hooks/useTheme.jsx`
- [Debounce Hook](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/hooks/useDebounce.jsx): interaction hook · Throttles search and filter input · `src/hooks/useDebounce.jsx`
- [Shared UI](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/components/ui/Navbar.jsx): ui kit · Navbar, sidebar, spinner, charts, cards, skeletons · `src/components/ui/Navbar.jsx`
- [Page Components](https://github.com/shahriar-hossain-alvi/edutrack-frontend/blob/main/src/components/pageComponents/AddUserPage/CreateStudentTab.jsx): domain ui · Forms, tables, and modals used inside pages · `src/components/pageComponents/AddUserPage/CreateStudentTab.jsx`

## Connections

- Main → Auth Provider: wraps · Root providers mount around the app
- Main → Theme Provider: wraps · Root providers mount around the app
- Auth Provider → Routes: feeds state · Routes consume auth state
- Theme Provider → Main Layout: feeds state · Layouts and UI consume theme state
- Routes → Private Routes: uses · Authenticated branches are guarded
- Routes → Role Redirects: uses · Role-aware landing and fallback redirects
- Routes → Main Layout: renders · Shared public shell
- Routes → Admin Layout: renders · Admin route subtree
- Routes → Teacher Layout: renders · Teacher route subtree
- Routes → Student Layout: renders · Student route subtree
- Main Layout → Auth & Public: hosts · Public pages use the shared shell
- Admin Layout → Admin Domain: hosts · Admin screens render inside admin shell
- Teacher Layout → Teacher Domain: hosts · Teacher screens render inside teacher shell
- Student Layout → Student Domain: hosts · Student screens render inside student shell
- Auth & Public → Auth Hook: reads · Signin and public flow read auth state
- Admin Domain → API Hooks: calls · Admin workflows hit backend APIs
- Teacher Domain → API Hooks: calls · Teacher workflows hit backend APIs
- Student Domain → API Hooks: calls · Student workflows hit backend APIs
- Admin Domain → Page Components: composes · Page-level screens use transactional UI pieces
- Teacher Domain → Page Components: composes · Page-level screens use transactional UI pieces
- Student Domain → Page Components: composes · Page-level screens use transactional UI pieces
- Admin Domain → Shared UI: uses · Shared UI powers tables, cards, logs, and navigation
- Teacher Domain → Shared UI: uses · Shared UI powers layout and display
- Student Domain → Shared UI: uses · Shared UI powers layout and display
- API Hooks → Auth Hook: aligns with · Secure requests depend on auth/session state
- API Hooks → Debounce Hook: supports · Search and filter interactions can be throttled
- API Hooks → Shared UI: drives · Fetched data populates reusable UI
- Theme Hook → Shared UI: styles · Theme state affects shared presentation