# insanecoder789/offlineqr-attendance architecture

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

- Interactive diagram: https://gitdiagram.com/insanecoder789/offlineqr-attendance
- Repository: https://github.com/insanecoder789/offlineqr-attendance

## Overview

OfflineQR is an institution-focused, offline-first attendance system. Faculty open classroom sessions and present rotating signed QR codes; students scan in the registered app, retain signed proofs locally, and synchronize them when reachable. The backend verifies proofs and updates attendance records for faculty review. The README documents these product capabilities, identity and device governance, and a separate public editorial site with proposal-PDF generation. Source excerpts show backend routing and attendance verification; mobile internals and most portal implementations were not sampled, so those links reflect README-documented behavior.

Main entry points: [`backend/app/main.py`](https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/main.py) (FastAPI routes), [`faculty-portal/src/components/FacultyPortalShell.tsx`](https://github.com/insanecoder789/offlineqr-attendance/blob/main/faculty-portal/src/components/FacultyPortalShell.tsx) (Faculty workspace), [`backend/app/attendance_service.py`](https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/attendance_service.py) (Signed QR session), [`client/android/app/src/main/kotlin/com/offlineqr/attendance/MainActivity.kt`](https://github.com/insanecoder789/offlineqr-attendance/blob/main/client/android/app/src/main/kotlin/com/offlineqr/attendance/MainActivity.kt) (Student app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_classroom["Classroom attendance"]
  node_faculty_portal["Faculty workspace"]
  node_session_ops["Session operations"]
  node_rotating_qr["Signed QR session"]
  node_student_app["Student app<br/>[MainActivity.kt]"]
  node_proof_outbox[("Local proof outbox")]
  node_proof_verification["Proof verification"]
  node_attendance_records[("Attendance records")]
end

subgraph group_identity["Identity and governance"]
  node_identity_auth["Identity and sign-in"]
  node_device_governance["Device governance<br/>[device_service.py]"]
end

subgraph group_backend["Backend services"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_postgres[("PostgreSQL<br/>[db.py]")]
  node_redis[("Redis coordination<br/>[redis_service.py]")]
end

subgraph group_web["Web surfaces"]
  node_faculty_api["Portal API client<br/>[api.ts]"]
  node_admin_api["Admin API client<br/>[admin-api.ts]"]
  node_editorial_site["Editorial website<br/>[PublicPage.tsx]"]
  node_proposal["Proposal PDF endpoint<br/>[proposal-pdf.ts]"]
end

node_faculty(("Faculty"))
node_student(("Student"))
node_ict(("ICT administrator"))

node_faculty -->|"operates"| node_faculty_portal
node_faculty_portal -->|"uses"| node_api
node_faculty_portal -->|"starts sessions"| node_session_ops
node_session_ops -->|"issues challenge"| node_rotating_qr
node_faculty_portal -->|"displays QR"| node_rotating_qr
node_student -->|"uses"| node_student_app
node_rotating_qr -->|"is scanned by"| node_student_app
node_student_app -->|"stores proofs"| node_proof_outbox
node_proof_outbox -->|"syncs proofs"| node_api
node_api -->|"routes proofs"| node_proof_verification
node_proof_verification -->|"records results"| node_attendance_records
node_api -->|"publishes roster updates"| node_faculty_portal
node_api -->|"reads and writes"| node_postgres
node_api -->|"coordinates sessions"| node_redis
node_faculty_portal -.->|"requests workspace data"| node_faculty_api
node_faculty_api -.->|"calls"| node_api
node_ict -->|"governs devices"| node_admin_api
node_admin_api -.->|"calls"| node_api
node_api -->|"authenticates faculty"| node_identity_auth
node_api -->|"routes device actions"| node_device_governance
node_editorial_site -->|"submits proposal"| node_proposal

click node_faculty_portal "https://github.com/insanecoder789/offlineqr-attendance/blob/main/faculty-portal/src/components/FacultyPortalShell.tsx"
click node_session_ops "https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/attendance_service.py"
click node_rotating_qr "https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/attendance_service.py"
click node_student_app "https://github.com/insanecoder789/offlineqr-attendance/blob/main/client/android/app/src/main/kotlin/com/offlineqr/attendance/MainActivity.kt"
click node_proof_outbox "https://github.com/insanecoder789/offlineqr-attendance/tree/main/client/android"
click node_proof_verification "https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/attendance_service.py"
click node_attendance_records "https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/attendance_service.py"
click node_identity_auth "https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/faculty_identity_service.py"
click node_device_governance "https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/device_service.py"
click node_api "https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/main.py"
click node_postgres "https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/db.py"
click node_redis "https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/redis_service.py"
click node_faculty_api "https://github.com/insanecoder789/offlineqr-attendance/blob/main/faculty-portal/src/api.ts"
click node_admin_api "https://github.com/insanecoder789/offlineqr-attendance/blob/main/faculty-portal/src/admin-api.ts"
click node_editorial_site "https://github.com/insanecoder789/offlineqr-attendance/blob/main/faculty-portal/src/components/marketing/PublicPage.tsx"
click node_proposal "https://github.com/insanecoder789/offlineqr-attendance/blob/main/faculty-portal/src/lib/commercial/proposal-pdf.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_faculty_portal,node_session_ops,node_rotating_qr,node_student_app,node_proof_outbox,node_proof_verification,node_attendance_records toneBlue
class node_identity_auth,node_device_governance toneAmber
class node_api,node_postgres,node_redis toneMint
class node_faculty_api,node_admin_api,node_editorial_site,node_proposal toneRose
class node_faculty,node_student,node_ict toneIndigo
```

## Components

### Classroom attendance

- [Faculty workspace](https://github.com/insanecoder789/offlineqr-attendance/blob/main/faculty-portal/src/components/FacultyPortalShell.tsx): `faculty-portal/src/components/FacultyPortalShell.tsx`
- [Session operations](https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/attendance_service.py): `backend/app/attendance_service.py`
- [Signed QR session](https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/attendance_service.py): `backend/app/attendance_service.py`
- [Student app](https://github.com/insanecoder789/offlineqr-attendance/blob/main/client/android/app/src/main/kotlin/com/offlineqr/attendance/MainActivity.kt): `client/android/app/src/main/kotlin/com/offlineqr/attendance/MainActivity.kt`
- [Local proof outbox](https://github.com/insanecoder789/offlineqr-attendance/tree/main/client/android): `client/android`
- [Proof verification](https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/attendance_service.py): `backend/app/attendance_service.py`
- [Attendance records](https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/attendance_service.py): `backend/app/attendance_service.py`

### Identity and governance

- [Identity and sign-in](https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/faculty_identity_service.py): `backend/app/faculty_identity_service.py`
- [Device governance](https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/device_service.py): `backend/app/device_service.py`

### Backend services

- [FastAPI routes](https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/main.py): `backend/app/main.py`
- [PostgreSQL](https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/db.py): `backend/app/db.py`
- [Redis coordination](https://github.com/insanecoder789/offlineqr-attendance/blob/main/backend/app/redis_service.py): `backend/app/redis_service.py`

### Web surfaces

- [Portal API client](https://github.com/insanecoder789/offlineqr-attendance/blob/main/faculty-portal/src/api.ts): `faculty-portal/src/api.ts`
- [Admin API client](https://github.com/insanecoder789/offlineqr-attendance/blob/main/faculty-portal/src/admin-api.ts): `faculty-portal/src/admin-api.ts`
- [Editorial website](https://github.com/insanecoder789/offlineqr-attendance/blob/main/faculty-portal/src/components/marketing/PublicPage.tsx): `faculty-portal/src/components/marketing/PublicPage.tsx`
- [Proposal PDF endpoint](https://github.com/insanecoder789/offlineqr-attendance/blob/main/faculty-portal/src/lib/commercial/proposal-pdf.ts): `faculty-portal/src/lib/commercial/proposal-pdf.ts`

### Other components

- **Faculty**
- **Student**
- **ICT administrator**

## Connections

- Faculty → Faculty workspace: operates (evidence: `README.md`)
- Faculty workspace → FastAPI routes: uses (evidence: `README.md`)
- Faculty workspace → Session operations: starts sessions (evidence: `README.md`)
- Session operations → Signed QR session: issues challenge (evidence: `README.md`)
- Faculty workspace → Signed QR session: displays QR (evidence: `README.md`)
- Student → Student app: uses (evidence: `README.md`)
- Signed QR session → Student app: is scanned by (evidence: `README.md`)
- Student app → Local proof outbox: stores proofs (evidence: `README.md`)
- Local proof outbox → FastAPI routes: syncs proofs (evidence: `README.md`)
- FastAPI routes → Proof verification: routes proofs (evidence: `backend/app/main.py`)
- Proof verification → Attendance records: records results (evidence: `backend/app/attendance_service.py`)
- FastAPI routes → Faculty workspace: publishes roster updates (evidence: `README.md`)
- FastAPI routes → PostgreSQL: reads and writes (evidence: `backend/app/db.py`)
- FastAPI routes → Redis coordination: coordinates sessions (evidence: `backend/app/redis_service.py`)
- Faculty workspace → Portal API client: requests workspace data
- Portal API client → FastAPI routes: calls
- ICT administrator → Admin API client: governs devices (evidence: `README.md`)
- Admin API client → FastAPI routes: calls
- FastAPI routes → Identity and sign-in: authenticates faculty (evidence: `backend/app/main.py`)
- FastAPI routes → Device governance: routes device actions (evidence: `backend/app/main.py`)
- Editorial website → Proposal PDF endpoint: submits proposal (evidence: `README.md`)
