# imperio-cse/attendtrax architecture

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

- Interactive diagram: https://gitdiagram.com/imperio-cse/attendtrax
- Repository: https://github.com/imperio-cse/attendtrax

## Overview

AttendTrax is a role-based attendance management system. Admins maintain classes, students, subjects and faculty, and can import records; faculty select a class, subject and hour, submit attendance once for a slot, and view class reports; students view their profile and attendance summary. The browser pages use a shared API client to reach a FastAPI backend, which enforces roles and delegates attendance and records to Google Sheets. The README documents spreadsheet initialization and class-register formatting; their detailed runtime relationships are not fully shown in the excerpts.

Main entry points: [`backend/main.py`](https://github.com/imperio-cse/attendtrax/blob/main/backend/main.py) (FastAPI app), [`backend/sheets.py`](https://github.com/imperio-cse/attendtrax/blob/main/backend/sheets.py) (Sheets data operations), [`frontend/api.js`](https://github.com/imperio-cse/attendtrax/blob/main/frontend/api.js) (API client), [`frontend/index.html`](https://github.com/imperio-cse/attendtrax/blob/main/frontend/index.html) (Login page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_login_ui["Login page<br/>[index.html]"]
  node_admin_ui["Admin dashboard<br/>[admin.html]"]
  node_faculty_ui["Faculty dashboard<br/>[faculty.html]"]
  node_student_ui["Student dashboard<br/>[student.html]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API and security"]
  node_app["FastAPI app<br/>[main.py]"]
  node_auth_routes["Login and passwords<br/>[auth_router.py]"]
  node_auth_logic["JWT and hashing<br/>[auth.py]"]
  node_auth_guards["Role guards<br/>[dependencies.py]"]
  node_settings["Backend settings<br/>[config.py]"]
end

subgraph group_attendance["Attendance workflows"]
  node_faculty_routes["Attendance endpoints<br/>[faculty_router.py]"]
  node_student_routes["Student endpoints<br/>[student_router.py]"]
end

subgraph group_records["Records and reporting"]
  node_admin_routes["Admin management<br/>[admin_router.py]"]
  node_sheet_ops["Sheets data operations<br/>[sheets.py]"]
  node_google_sheets[("Google Sheets")]
end

subgraph group_sheets_setup["Sheets setup"]
  node_sheet_initializer["Sheet initializer<br/>[setup_sheets.py]"]
  node_register_builder["Daily register builder"]
end

node_admin_actor(("Administrator"))
node_faculty_actor(("Faculty"))
node_student_actor(("Student"))

node_admin_actor -->|"signs in"| node_login_ui
node_faculty_actor -->|"signs in"| node_login_ui
node_student_actor -->|"signs in"| node_login_ui
node_login_ui -.->|"uses"| node_api_client
node_admin_ui -.->|"uses"| node_api_client
node_faculty_ui -.->|"uses"| node_api_client
node_student_ui -.->|"uses"| node_api_client
node_api_client -->|"sends API requests"| node_app
node_app -->|"registers"| node_auth_routes
node_app -->|"registers"| node_faculty_routes
node_app -->|"registers"| node_student_routes
node_app -->|"registers"| node_admin_routes
node_app -->|"loads"| node_settings
node_app -->|"warms cache"| node_sheet_ops
node_auth_routes -->|"verifies and signs"| node_auth_logic
node_auth_routes -->|"looks up and updates users"| node_sheet_ops
node_auth_guards -->|"decodes token"| node_auth_logic
node_auth_guards -->|"looks up user"| node_sheet_ops
node_auth_guards -->|"checks admin"| node_settings
node_admin_routes -->|"manages records and imports"| node_sheet_ops
node_faculty_routes -->|"checks and saves attendance"| node_sheet_ops
node_student_routes -->|"reads profile and summary"| node_sheet_ops
node_sheet_ops -->|"reads and writes"| node_google_sheets
node_sheet_initializer -->|"initializes spreadsheets"| node_google_sheets
node_register_builder -->|"reads attendance data"| node_sheet_ops
node_register_builder -->|"formats class registers"| node_google_sheets

click node_login_ui "https://github.com/imperio-cse/attendtrax/blob/main/frontend/index.html"
click node_admin_ui "https://github.com/imperio-cse/attendtrax/blob/main/frontend/admin.html"
click node_faculty_ui "https://github.com/imperio-cse/attendtrax/blob/main/frontend/faculty.html"
click node_student_ui "https://github.com/imperio-cse/attendtrax/blob/main/frontend/student.html"
click node_api_client "https://github.com/imperio-cse/attendtrax/blob/main/frontend/api.js"
click node_app "https://github.com/imperio-cse/attendtrax/blob/main/backend/main.py"
click node_auth_routes "https://github.com/imperio-cse/attendtrax/blob/main/backend/routers/auth_router.py"
click node_auth_logic "https://github.com/imperio-cse/attendtrax/blob/main/backend/auth.py"
click node_auth_guards "https://github.com/imperio-cse/attendtrax/blob/main/backend/dependencies.py"
click node_settings "https://github.com/imperio-cse/attendtrax/blob/main/backend/config.py"
click node_admin_routes "https://github.com/imperio-cse/attendtrax/blob/main/backend/routers/admin_router.py"
click node_faculty_routes "https://github.com/imperio-cse/attendtrax/blob/main/backend/routers/faculty_router.py"
click node_student_routes "https://github.com/imperio-cse/attendtrax/blob/main/backend/routers/student_router.py"
click node_sheet_ops "https://github.com/imperio-cse/attendtrax/blob/main/backend/sheets.py"
click node_sheet_initializer "https://github.com/imperio-cse/attendtrax/blob/main/backend/setup_sheets.py"
click node_register_builder "https://github.com/imperio-cse/attendtrax/blob/main/backend/setup_daily_registers.py"

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_login_ui,node_admin_ui,node_faculty_ui,node_student_ui,node_api_client toneBlue
class node_app,node_auth_routes,node_auth_logic,node_auth_guards,node_settings toneAmber
class node_faculty_routes,node_student_routes toneMint
class node_admin_routes,node_sheet_ops,node_google_sheets toneRose
class node_sheet_initializer,node_register_builder,node_admin_actor,node_faculty_actor,node_student_actor toneIndigo
```

## Components

### Web interface

- [Login page](https://github.com/imperio-cse/attendtrax/blob/main/frontend/index.html): `frontend/index.html`
- [Admin dashboard](https://github.com/imperio-cse/attendtrax/blob/main/frontend/admin.html): `frontend/admin.html`
- [Faculty dashboard](https://github.com/imperio-cse/attendtrax/blob/main/frontend/faculty.html): `frontend/faculty.html`
- [Student dashboard](https://github.com/imperio-cse/attendtrax/blob/main/frontend/student.html): `frontend/student.html`
- [API client](https://github.com/imperio-cse/attendtrax/blob/main/frontend/api.js): `frontend/api.js`

### API and security

- [FastAPI app](https://github.com/imperio-cse/attendtrax/blob/main/backend/main.py): `backend/main.py`
- [Login and passwords](https://github.com/imperio-cse/attendtrax/blob/main/backend/routers/auth_router.py): `backend/routers/auth_router.py`
- [JWT and hashing](https://github.com/imperio-cse/attendtrax/blob/main/backend/auth.py): `backend/auth.py`
- [Role guards](https://github.com/imperio-cse/attendtrax/blob/main/backend/dependencies.py): `backend/dependencies.py`
- [Backend settings](https://github.com/imperio-cse/attendtrax/blob/main/backend/config.py): `backend/config.py`

### Attendance workflows

- [Attendance endpoints](https://github.com/imperio-cse/attendtrax/blob/main/backend/routers/faculty_router.py): `backend/routers/faculty_router.py`
- [Student endpoints](https://github.com/imperio-cse/attendtrax/blob/main/backend/routers/student_router.py): `backend/routers/student_router.py`

### Records and reporting

- [Admin management](https://github.com/imperio-cse/attendtrax/blob/main/backend/routers/admin_router.py): `backend/routers/admin_router.py`
- [Sheets data operations](https://github.com/imperio-cse/attendtrax/blob/main/backend/sheets.py): `backend/sheets.py`
- **Google Sheets**

### Sheets setup

- [Sheet initializer](https://github.com/imperio-cse/attendtrax/blob/main/backend/setup_sheets.py): `backend/setup_sheets.py`
- [Daily register builder](https://github.com/imperio-cse/attendtrax/blob/main/backend/setup_daily_registers.py): `backend/setup_daily_registers.py`

### Other components

- **Administrator**
- **Faculty**
- **Student**

## Connections

- Administrator → Login page: signs in (evidence: `README.md`)
- Faculty → Login page: signs in (evidence: `README.md`)
- Student → Login page: signs in (evidence: `README.md`)
- Login page → API client: uses
- Admin dashboard → API client: uses
- Faculty dashboard → API client: uses
- Student dashboard → API client: uses
- API client → FastAPI app: sends API requests (evidence: `README.md`)
- FastAPI app → Login and passwords: registers (evidence: `backend/main.py`)
- FastAPI app → Attendance endpoints: registers (evidence: `backend/main.py`)
- FastAPI app → Student endpoints: registers (evidence: `backend/main.py`)
- FastAPI app → Admin management: registers (evidence: `backend/main.py`)
- FastAPI app → Backend settings: loads (evidence: `backend/main.py`)
- FastAPI app → Sheets data operations: warms cache (evidence: `backend/main.py`)
- Login and passwords → JWT and hashing: verifies and signs (evidence: `backend/routers/auth_router.py`)
- Login and passwords → Sheets data operations: looks up and updates users (evidence: `backend/routers/auth_router.py`)
- Role guards → JWT and hashing: decodes token (evidence: `backend/dependencies.py`)
- Role guards → Sheets data operations: looks up user (evidence: `backend/dependencies.py`)
- Role guards → Backend settings: checks admin (evidence: `backend/dependencies.py`)
- Admin management → Sheets data operations: manages records and imports (evidence: `backend/routers/admin_router.py`)
- Attendance endpoints → Sheets data operations: checks and saves attendance (evidence: `backend/routers/faculty_router.py`)
- Student endpoints → Sheets data operations: reads profile and summary (evidence: `backend/routers/student_router.py`)
- Sheets data operations → Google Sheets: reads and writes (evidence: `README.md`)
- Sheet initializer → Google Sheets: initializes spreadsheets (evidence: `backend/setup_sheets.py`)
- Daily register builder → Sheets data operations: reads attendance data (evidence: `backend/setup_daily_registers.py`)
- Daily register builder → Google Sheets: formats class registers (evidence: `backend/setup_daily_registers.py`)
