# marco-sawiris/st.gorge-dashboard architecture

> Architecture diagram of the GitHub repository marco-sawiris/st.gorge-dashboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marco-sawiris/st.gorge-dashboard
- Repository: https://github.com/marco-sawiris/st.gorge-dashboard

## Overview

This is an Arabic-language student and attendance management application, with a web UI and Android wrapper. Staff use the dashboard to browse and filter students, record attendance and follow-ups, import attendance from PDFs, and synchronize changes with Google Sheets; offline changes are queued locally for later reconciliation. The server adds authenticated access and a Sheets relay. Assistant, charts, and notifications are additional product capabilities. The README is empty, so capability coverage comes from the tree and source index; links to unsampled features are omitted where their wiring is not evidenced.

Main entry points: [`src/App.tsx`](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/App.tsx) (Dashboard shell), [`src/context/AppContext.tsx`](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/context/AppContext.tsx) (Application state), [`server/routes/auth.ts`](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server/routes/auth.ts) (Authentication routes), [`server/db/index.ts`](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server/db/index.ts) (User and session store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Dashboard"]
  node_app["Dashboard shell<br/>[App.tsx]"]
  node_student_views["Student views<br/>[StudentCard.tsx]"]
  node_search["Search and filters"]
  node_charts["Dashboard charts"]
  node_followup_view["Follow-up log"]
end

subgraph group_records["Student Workflows"]
  node_assistant["Assistant engine<br/>[assistantEngine.ts]"]
  node_pdf_ui["Attendance import UI"]
  node_pdf_import["PDF import processing"]
  node_pdf_parser["PDF attendance parser"]
end

subgraph group_sync["Offline and Sync"]
  node_app_state["Application state<br/>[AppContext.tsx]"]
  node_local_store[("Local records and queue")]
  node_sheet_parser["Sheet data parser"]
  node_api_config["API configuration<br/>[apiConfig.ts]"]
end

subgraph group_server["Server and Integrations"]
  node_server_entry["HTTP server<br/>[server.ts]"]
  node_sheet_routes["Sheets routes<br/>[sheets.ts]"]
  node_health_routes["Health route<br/>[health.ts]"]
  node_sheets_service["Google Sheets service"]
  node_postgres[("PostgreSQL")]
end

subgraph group_security["Identity and Security"]
  node_auth_routes["Authentication routes<br/>[auth.ts]"]
  node_user_store[("User and session store<br/>[index.ts]")]
  node_auth_middleware["Token middleware<br/>[auth.ts]"]
  node_jwt["JWT security<br/>[jwt.ts]"]
  node_argon["Password hashing<br/>[argon2.ts]"]
end

node_staff(("Staff user"))
node_google_sheets[("Google Sheets")]

node_staff -->|"uses"| node_app
node_app -->|"renders"| node_student_views
node_app -->|"renders"| node_search
node_app -->|"renders"| node_charts
node_app -->|"renders"| node_followup_view
node_app -->|"reads state"| node_app_state
node_app -.->|"opens assistant"| node_assistant
node_app -->|"renders"| node_pdf_ui
node_pdf_ui -->|"uses"| node_pdf_parser
node_pdf_ui -->|"uses"| node_pdf_import
node_pdf_ui -->|"reads and writes"| node_local_store
node_pdf_import -->|"parses with"| node_pdf_parser
node_pdf_import -->|"uses"| node_local_store
node_app_state -->|"reads and writes"| node_local_store
node_app_state -->|"loads sheets"| node_sheet_parser
node_app_state -->|"uses"| node_pdf_import
node_app_state -->|"uses"| node_api_config
node_api_config -.->|"configures requests"| node_server_entry
node_server_entry -->|"registers"| node_auth_routes
node_server_entry -->|"registers"| node_sheet_routes
node_server_entry -->|"registers"| node_health_routes
node_auth_routes -->|"reads and writes"| node_user_store
node_auth_routes -->|"verifies password"| node_argon
node_auth_routes -->|"verifies tokens"| node_jwt
node_auth_routes -->|"uses"| node_auth_middleware
node_auth_middleware -->|"verifies tokens"| node_jwt
node_user_store -->|"hashes seeded passwords"| node_argon
node_user_store -->|"persists records"| node_postgres
node_sheet_routes -->|"protects routes"| node_auth_middleware
node_sheet_routes -->|"uses"| node_user_store
node_sheet_routes -->|"requests sheet data"| node_sheets_service
node_health_routes -->|"checks storage"| node_user_store
node_health_routes -->|"checks Sheets"| node_sheets_service
node_sheets_service -->|"parses rows"| node_sheet_parser
node_sheets_service -->|"reads and writes"| node_google_sheets

click node_app "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/App.tsx"
click node_student_views "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/components/cards/StudentCard.tsx"
click node_search "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/components/common/SearchFilterBar.tsx"
click node_charts "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/components/charts/DashboardChartsView.tsx"
click node_followup_view "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/components/followup/FollowupLogView.tsx"
click node_assistant "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/services/assistantEngine.ts"
click node_pdf_ui "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/components/modals/PdfAttendanceImportModal.tsx"
click node_pdf_import "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/services/pdfAttendanceImportService.ts"
click node_pdf_parser "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/services/pdfAttendanceParser.ts"
click node_app_state "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/context/AppContext.tsx"
click node_local_store "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/services/indexedDbService.ts"
click node_sheet_parser "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/services/googleSheetParser.ts"
click node_api_config "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/services/apiConfig.ts"
click node_server_entry "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server.ts"
click node_auth_routes "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server/routes/auth.ts"
click node_sheet_routes "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server/routes/sheets.ts"
click node_health_routes "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server/routes/health.ts"
click node_sheets_service "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server/services/googleSheetsService.ts"
click node_user_store "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server/db/index.ts"
click node_auth_middleware "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server/middleware/auth.ts"
click node_jwt "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server/security/jwt.ts"
click node_argon "https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server/security/argon2.ts"

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_app,node_student_views,node_search,node_charts,node_followup_view,node_staff toneBlue
class node_assistant,node_pdf_ui,node_pdf_import,node_pdf_parser,node_google_sheets toneAmber
class node_app_state,node_local_store,node_sheet_parser,node_api_config toneMint
class node_server_entry,node_sheet_routes,node_health_routes,node_sheets_service,node_postgres toneRose
class node_auth_routes,node_user_store,node_auth_middleware,node_jwt,node_argon toneIndigo
```

## Components

### Dashboard

- [Dashboard shell](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/App.tsx): `src/App.tsx`
- [Student views](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/components/cards/StudentCard.tsx): `src/components/cards/StudentCard.tsx`
- [Search and filters](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/components/common/SearchFilterBar.tsx): `src/components/common/SearchFilterBar.tsx`
- [Dashboard charts](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/components/charts/DashboardChartsView.tsx): `src/components/charts/DashboardChartsView.tsx`
- [Follow-up log](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/components/followup/FollowupLogView.tsx): `src/components/followup/FollowupLogView.tsx`

### Student Workflows

- [Assistant engine](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/services/assistantEngine.ts): `src/services/assistantEngine.ts`
- [Attendance import UI](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/components/modals/PdfAttendanceImportModal.tsx): `src/components/modals/PdfAttendanceImportModal.tsx`
- [PDF import processing](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/services/pdfAttendanceImportService.ts): `src/services/pdfAttendanceImportService.ts`
- [PDF attendance parser](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/services/pdfAttendanceParser.ts): `src/services/pdfAttendanceParser.ts`

### Offline and Sync

- [Application state](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/context/AppContext.tsx): `src/context/AppContext.tsx`
- [Local records and queue](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/services/indexedDbService.ts): `src/services/indexedDbService.ts`
- [Sheet data parser](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/services/googleSheetParser.ts): `src/services/googleSheetParser.ts`
- [API configuration](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/src/services/apiConfig.ts): `src/services/apiConfig.ts`

### Server and Integrations

- [HTTP server](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server.ts): `server.ts`
- [Sheets routes](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server/routes/sheets.ts): `server/routes/sheets.ts`
- [Health route](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server/routes/health.ts): `server/routes/health.ts`
- [Google Sheets service](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server/services/googleSheetsService.ts): `server/services/googleSheetsService.ts`
- **PostgreSQL**

### Identity and Security

- [Authentication routes](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server/routes/auth.ts): `server/routes/auth.ts`
- [User and session store](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server/db/index.ts): `server/db/index.ts`
- [Token middleware](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server/middleware/auth.ts): `server/middleware/auth.ts`
- [JWT security](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server/security/jwt.ts): `server/security/jwt.ts`
- [Password hashing](https://github.com/marco-sawiris/st.gorge-dashboard/blob/main/server/security/argon2.ts): `server/security/argon2.ts`

### Other components

- **Staff user**
- **Google Sheets**

## Connections

- Staff user → Dashboard shell: uses
- Dashboard shell → Student views: renders (evidence: `src/App.tsx`)
- Dashboard shell → Search and filters: renders (evidence: `src/App.tsx`)
- Dashboard shell → Dashboard charts: renders (evidence: `src/App.tsx`)
- Dashboard shell → Follow-up log: renders (evidence: `src/App.tsx`)
- Dashboard shell → Application state: reads state (evidence: `src/App.tsx`)
- Dashboard shell → Assistant engine: opens assistant
- Dashboard shell → Attendance import UI: renders (evidence: `src/App.tsx`)
- Attendance import UI → PDF attendance parser: uses (evidence: `src/components/modals/PdfAttendanceImportModal.tsx`)
- Attendance import UI → PDF import processing: uses (evidence: `src/components/modals/PdfAttendanceImportModal.tsx`)
- Attendance import UI → Local records and queue: reads and writes (evidence: `src/components/modals/PdfAttendanceImportModal.tsx`)
- PDF import processing → PDF attendance parser: parses with (evidence: `src/services/pdfAttendanceImportService.ts`)
- PDF import processing → Local records and queue: uses (evidence: `src/services/pdfAttendanceImportService.ts`)
- Application state → Local records and queue: reads and writes (evidence: `src/context/AppContext.tsx`)
- Application state → Sheet data parser: loads sheets (evidence: `src/context/AppContext.tsx`)
- Application state → PDF import processing: uses (evidence: `src/context/AppContext.tsx`)
- Application state → API configuration: uses (evidence: `src/context/AppContext.tsx`)
- API configuration → HTTP server: configures requests
- HTTP server → Authentication routes: registers (evidence: `server.ts`)
- HTTP server → Sheets routes: registers (evidence: `server.ts`)
- HTTP server → Health route: registers (evidence: `server.ts`)
- Authentication routes → User and session store: reads and writes (evidence: `server/routes/auth.ts`)
- Authentication routes → Password hashing: verifies password (evidence: `server/routes/auth.ts`)
- Authentication routes → JWT security: verifies tokens (evidence: `server/routes/auth.ts`)
- Authentication routes → Token middleware: uses (evidence: `server/routes/auth.ts`)
- Token middleware → JWT security: verifies tokens (evidence: `server/middleware/auth.ts`)
- User and session store → Password hashing: hashes seeded passwords (evidence: `server/db/index.ts`)
- User and session store → PostgreSQL: persists records (evidence: `server/db/index.ts`)
- Sheets routes → Token middleware: protects routes (evidence: `server/routes/sheets.ts`)
- Sheets routes → User and session store: uses (evidence: `server/routes/sheets.ts`)
- Sheets routes → Google Sheets service: requests sheet data (evidence: `server/routes/sheets.ts`)
- Health route → User and session store: checks storage (evidence: `server/routes/health.ts`)
- Health route → Google Sheets service: checks Sheets (evidence: `server/routes/health.ts`)
- Google Sheets service → Sheet data parser: parses rows (evidence: `server/services/googleSheetsService.ts`)
- Google Sheets service → Google Sheets: reads and writes (evidence: `server/services/googleSheetsService.ts`)
