# fu-capstone-su2025/front-end architecture

> Architecture diagram of the GitHub repository fu-capstone-su2025/front-end, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fu-capstone-su2025/front-end
- Repository: https://github.com/fu-capstone-su2025/front-end

## Overview

##### Project type and purpose
- This is a single-page, client-side React application (TypeScript) for an AI-powered academic advising platform.
- It serves multiple user roles (Student, Advisor, Staff, Manager, Admin), displaying dashboards, chat, data tables, charts, and AI features.
- It communicates via RESTful APIs (Axios) to a back-end (AISEA Back-End) and uses real-time hubs (SignalR) for chat/notifications.

##### File structure
Top-level files & folders:
- Dockerfile, nginx.conf, .github/workflows: deployment configs (Docker + DigitalOcean + CI/CD)
- public/, index.html: static assets and entry HTML
- src/
– api/: wrappers around Axios REST calls, organized by domain (Account, SchoolAPI, advisor, student, etc.)
– components/: reusable UI pieces, grouped by user role (admin, advisor, manager, staff, student) plus common controls
– pages/: route-level components (one per view) matching user roles
– hooks/: custom hooks encapsulating business logic, data fetching, state interactions, chat hubs
– router/: React Router definitions
– utils/, data/, interfaces/: helper functions, mock data, type definitions
– App.tsx, main.tsx: application bootstrap, provider setup (Zustand store, Router, Layout)

##### README for extra context
- Confirms React+TypeScript, REST API via Axios, Zustand for state, JWT auth, Docker+Nginx deployment, GitHub Actions CI.
- Mentions AI‐integration (Gemini AI, Google Agent Dev Kit) on the back end and real‐time features (SignalR).
- Lists user roles and high-level features (dashboards, GPA calculator, AI-chat, semester planning, data import).

##### Main components and their interactions
a. User Interface Layer (Browser)
– Role-based Pages (StudentDashboardPage, AdvisorPage, etc.)
– Shared Components (NavBar, ChatBox, DataTable, Charts, Forms)
– CSS Modules for styling
b. State & Business Logic Layer
– Zustand store (global.tsx)
– Custom Hooks: useAuths, useCRUDStudent, useNotificationHub, useChatApi, useSendAIMessenger, etc.
c. API Layer
– axiosCRUD wrapper + domain APIs (UserAPI/AuthAPI, AdvisorAPI, StudentAPI, SchoolAPI/*)
d. Real-time Services
– SignalR hubs (ChatHub, NotificationHub via useNotificationHub, useAdvisorChatHub)
e. External Services (Back-end)
– AISEA Back-End microservices (Auth, AcademicData, AI engines)
– Database (Postgres/Mongo/etc.)
– AI services (Gemini AI, Google Agent Dev Kit)
f. Deployment Infrastructure
– Docker container running Nginx serving static assets + reverse-proxy to APIs
– CI/CD (GitHub Actions) → DigitalOcean / Vercel

##### Architectural patterns & principles
- Feature-driven folder structure (group by role/domain)
- Separation of concerns: Presentation (components/pages) vs. Logic (hooks/store) vs. Data (api/)
- RESTful API client abstraction with centralized AxiosCRUD
- Real-time event handling via SignalR hubs
- JWT authentication with ProtectedRoute wrapper
- Containerized static serving + reverse proxy

##### Final checklist
[ ] All five user roles & their landing pages
[ ] Shared UI Component library
[ ] State store (Zustand) & Hooks layer
[ ] API client layer & domain APIs
[ ] SignalR real-time connections
[ ] External Back-end services & AI engines
[ ] Deployment (Docker + Nginx) and CI/CD pipeline

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "User Browser (React SPA)"
        direction TB
        UI["UI Layer"]:::layer
        BIZ["Business Logic Layer"]:::layer
        API["API Layer"]:::layer
        RT["Real-time Layer"]:::layer
    end

    subgraph "UI Layer"
        direction TB
        StudentPage["StudentDashboardPage"]:::ui
        AdvisorPage["AdvisorDashboardPage"]:::ui
        ManagerPage["ManagerHomePage"]:::ui
        StaffPage["StaffCurriculumPage"]:::ui
        AdminPage["AdminAccountManagementPage"]:::ui
        LoginPage["CommonLoginPage"]:::ui
        ForgetPage["CommonForgetPasswordPage"]:::ui

        ProtectedRoute["ProtectedRoute"]:::ui
        NavBar["GlobalNavBar"]:::ui
        Provider["ProviderSetup"]:::ui
        DataTable["CommonDataTable"]:::ui
        ExcelImportButton["CommonExcelImportButton"]:::ui
    end

    subgraph "Business Logic Layer"
        direction TB
        Store["GlobalZustandStore"]:::logic
        AuthHook["useAuths"]:::logic
        CRUDStudent["useCRUDStudent"]:::logic
        NotificationHook["useNotificationHub"]:::logic
        ChatApiHook["useChatApi"]:::logic
        AIMessenger["useSendAIMessenger"]:::logic
        AdvisorHubHook["useAdvisorChatHub"]:::logic
    end

    subgraph "API Layer"
        direction TB
        AxiosCRUD["AxiosCRUDWrapper"]:::api
        AuthAPI["AuthAPI"]:::api
        UserAPI["UserAPI"]:::api
        StudentAPI["StudentAPI"]:::api
        AdvisorChatAPI["AdvisorChatAPI"]:::api
        AiChatBox["AiChatBox"]:::api
        AdvisorAPI["AdvisorAPI"]:::api
        ManagerAPI["ManagerAPI"]:::api
        StaffAPI["StaffAPI"]:::api
        AuditLogAPI["auditlogAPI"]:::api
        SchoolAPIs["SchoolDomainAPIs"]:::api
    end

    subgraph "Real-time Layer"
        direction TB
        SignalRDebug["SignalRDebugComponent"]:::realtime
    end

    %% External services
    BackEnd["AISEA Back-End Microservices"]:::external
    Database["Database"]:::external
    AIServices["External AI Services"]:::external
    SignalRHub["SignalR Hub Endpoint"]:::external

    %% Deployment
    DockerNginx["Docker + Nginx"]:::infra
    CICDPipeline["GitHub Actions CI/CD"]:::infra

    %% Connections
    StudentPage -->|interacts| Store
    AdvisorPage -->|interacts| Store
    ManagerPage -->|interacts| Store
    StaffPage -->|interacts| Store
    AdminPage -->|interacts| Store
    LoginPage -->|calls| AuthHook
    ForgetPage -->|calls| AuthHook

    ProtectedRoute -->|guards| StudentPage
    ProtectedRoute -->|guards| AdvisorPage
    ProtectedRoute -->|guards| ManagerPage
    ProtectedRoute -->|guards| StaffPage
    ProtectedRoute -->|guards| AdminPage

    NavBar -->|renders| StudentPage
    NavBar -->|renders| AdvisorPage

    Provider -->|provides| Store
    Provider -->|provides| Router

    DataTable -->|used by| StudentPage
    ExcelImportButton -->|used by| StaffPage

    %% UI to Logic
    UI -->|state/events| Store
    UI -->|hooks| AuthHook
    UI -->|hooks| CRUDStudent
    UI -->|hooks| NotificationHook
    UI -->|hooks| ChatApiHook
    UI -->|hooks| AIMessenger
    UI -->|hooks| AdvisorHubHook

    %% Logic to API
    AuthHook -->|«REST»| AuthAPI
    CRUDStudent -->|«REST»| StudentAPI
    ChatApiHook -->|«REST»| AdvisorChatAPI
    AIMessenger -->|«REST»| AiChatBox

    %% Logic to Real-time
    NotificationHook -->|«SignalR»| SignalRHub
    AdvisorHubHook -->|«SignalR»| SignalRHub
    SignalRDebug -->|debugs| SignalRHub

    %% API to Back-end
    AuthAPI -->|«REST»| BackEnd
    UserAPI -->|«REST»| BackEnd
    StudentAPI -->|«REST»| BackEnd
    AdvisorChatAPI -->|«REST»| BackEnd
    AiChatBox -->|«REST»| BackEnd
    AdvisorAPI -->|«REST»| BackEnd
    ManagerAPI -->|«REST»| BackEnd
    StaffAPI -->|«REST»| BackEnd
    AuditLogAPI -->|«REST»| BackEnd
    SchoolAPIs -->|«REST»| BackEnd

    %% External Data
    BackEnd --> Database
    BackEnd --> AIServices

    %% Deployment connections
    Browser((Browser)) -->|serves| DockerNginx
    DockerNginx -->|deploys| UI
    CICDPipeline -->|build & deploy| DockerNginx

    %% Click Events
    click StudentPage "https://github.com/fu-capstone-su2025/front-end/blob/main/src/pages/student/dashboard.tsx"
    click AdvisorPage "https://github.com/fu-capstone-su2025/front-end/blob/main/src/pages/advisor/dashboard.tsx"
    click ManagerPage "https://github.com/fu-capstone-su2025/front-end/blob/main/src/pages/manager/home.tsx"
    click StaffPage "https://github.com/fu-capstone-su2025/front-end/blob/main/src/pages/staff/curriculum.tsx"
    click AdminPage "https://github.com/fu-capstone-su2025/front-end/blob/main/src/pages/admin/account.tsx"
    click LoginPage "https://github.com/fu-capstone-su2025/front-end/blob/main/src/pages/common/login.tsx"
    click ForgetPage "https://github.com/fu-capstone-su2025/front-end/blob/main/src/pages/common/forgetPassword.tsx"
    click ProtectedRoute "https://github.com/fu-capstone-su2025/front-end/blob/main/src/components/protectedRoute.tsx"
    click NavBar "https://github.com/fu-capstone-su2025/front-end/blob/main/src/components/navbar.tsx"
    click Provider "https://github.com/fu-capstone-su2025/front-end/blob/main/src/components/provider.tsx"
    click DataTable "https://github.com/fu-capstone-su2025/front-end/blob/main/src/components/common/dataTable.tsx"
    click ExcelImportButton "https://github.com/fu-capstone-su2025/front-end/blob/main/src/components/common/ExcelImportButton.tsx"
    click Store "https://github.com/fu-capstone-su2025/front-end/blob/main/src/hooks/global.tsx"
    click AuthHook "https://github.com/fu-capstone-su2025/front-end/blob/main/src/hooks/useAuths.ts"
    click CRUDStudent "https://github.com/fu-capstone-su2025/front-end/blob/main/src/hooks/useCRUDStudent.ts"
    click NotificationHook "https://github.com/fu-capstone-su2025/front-end/blob/main/src/hooks/useNotificationHub.ts"
    click ChatApiHook "https://github.com/fu-capstone-su2025/front-end/blob/main/src/hooks/useChatApi.ts"
    click AIMessenger "https://github.com/fu-capstone-su2025/front-end/blob/main/src/hooks/useSendAIMessenger.ts"
    click AdvisorHubHook "https://github.com/fu-capstone-su2025/front-end/blob/main/src/hooks/useAdvisorChatHub.ts"
    click AxiosCRUD "https://github.com/fu-capstone-su2025/front-end/blob/main/src/api/AxiosCRUD.ts"
    click AuthAPI "https://github.com/fu-capstone-su2025/front-end/blob/main/src/api/Account/AuthAPI.ts"
    click UserAPI "https://github.com/fu-capstone-su2025/front-end/blob/main/src/api/Account/UserAPI.ts"
    click StudentAPI "https://github.com/fu-capstone-su2025/front-end/blob/main/src/api/student/StudentAPI.ts"
    click AdvisorChatAPI "https://github.com/fu-capstone-su2025/front-end/blob/main/src/api/student/AdvisorChatAPI.ts"
    click AiChatBox "https://github.com/fu-capstone-su2025/front-end/blob/main/src/api/student/AiChatBox.ts"
    click AdvisorAPI "https://github.com/fu-capstone-su2025/front-end/blob/main/src/api/advisor/AdvisorAPI.ts"
    click ManagerAPI "https://github.com/fu-capstone-su2025/front-end/blob/main/src/api/manager/ManagerAPI.ts"
    click StaffAPI "https://github.com/fu-capstone-su2025/front-end/blob/main/src/api/staff/StaffAPI.ts"
    click AuditLogAPI "https://github.com/fu-capstone-su2025/front-end/blob/main/src/api/admin/auditlogAPI.ts"
    click SchoolAPIs "https://github.com/fu-capstone-su2025/front-end/tree/main/src/api/SchoolAPI/"
    click SignalRDebug "https://github.com/fu-capstone-su2025/front-end/blob/main/src/components/student/SignalRDebug.tsx"
    click DockerNginx "https://github.com/fu-capstone-su2025/front-end/tree/main/Dockerfile"
    click CICDPipeline "https://github.com/fu-capstone-su2025/front-end/blob/main/.github/workflows/digital_ocean_deploy.yml"

    %% Styles
    classDef ui fill:#E0F7FA,stroke:#006064,stroke-width:1px
    classDef logic fill:#E8F5E9,stroke:#1B5E20,stroke-width:1px
    classDef api fill:#FFF3E0,stroke:#E65100,stroke-width:1px
    classDef realtime fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1px
    classDef external fill:#ECEFF1,stroke:#37474F,stroke-width:1px
    classDef infra fill:#CFD8DC,stroke:#263238,stroke-width:1px
    classDef layer fill:none,stroke:#000,stroke-dasharray: 5 5,stroke-width:1px
```
