# omkuthe/zkp-attendance architecture

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

- Interactive diagram: https://gitdiagram.com/omkuthe/zkp-attendance
- Repository: https://github.com/omkuthe/zkp-attendance

## Overview

#### Purpose and Entry Points
This is an internship attendance system with role-specific administration, management, and student workflows. Attendance/session participation appears to be validated through a zero-knowledge proximity proof. The backend API starts at `backend/app/main.py`; the Vite/React client starts at `frontend/src/main.jsx` and composes the application in `frontend/src/App.jsx`.

#### Backend API and Role Boundaries
FastAPI-style route modules separate concerns by actor and workflow:
- Authentication and identity: `backend/app/api/auth.py`
- Administrative management: `backend/app/api/admin.py`
- Manager/internship operations: `backend/app/api/manager.py`
- Student-facing operations: `backend/app/api/student.py`
- Attendance session lifecycle: `backend/app/api/session.py`

These route layers are the primary authorization and request-handling boundary between the browser and persistent application state.

#### Persistence and Domain Model
`backend/app/database.py` owns database connectivity/session setup, while `backend/app/models.py` defines persisted domain entities and `backend/app/schemas.py` defines API payload contracts. The apparent core domain is users with distinct roles, companies/internships, sessions, attendance, and holidays, reflected in the frontend’s corresponding management surfaces.

Backend configuration is centralized in `backend/app/config.py`. Password or credential processing is isolated in `backend/app/utils/hasher.py`.

#### Zero-Knowledge Attendance Verification
The proof-verification boundary is `backend/app/zk_verifier.py`, invoked server-side to validate submitted proximity proofs rather than accepting location/proximity claims directly. The circuit source is `backend/zk/circuits/proximity.circom`; proving artifacts include `backend/zk/zkey/proximity_final.zkey` and `backend/zk/zkey/verification_key.json`.

A Node helper, `backend/verify_helper.js`, likely bridges Python API logic to the JavaScript zk tooling. This creates a mixed Python/Node runtime dependency for proof verification.

#### Frontend Application and Authentication State
The React UI stores and distributes login/session identity through `frontend/src/context/AuthContext.jsx`. Route access is controlled by `frontend/src/components/Auth/ProtectedRoute.jsx`, with login implemented in `frontend/src/components/Auth/Login.jsx`.

HTTP integration is centralized around `frontend/src/services/api.js`, with domain-facing clients in `frontend/src/services/auth.js`, `frontend/src/services/admin.js`, and `frontend/src/services/session.js`. This service layer is the frontend/backend contract boundary.

#### Role-Specific Product Flows
Administrators manage operational master data and monitor activity through `frontend/src/components/Admin/AdminDashboard.jsx`, `frontend/src/components/Admin/InternshipManagement.jsx`, and `frontend/src/components/Admin/SessionMonitor.jsx`.

Managers oversee internships and assigned students through `frontend/src/components/Manager/ManagerDashboard.jsx`, `frontend/src/components/Manager/InternshipDetails.jsx`, and `frontend/src/components/Manager/StudentTimeline.jsx`.

Students join attendance sessions and review records through `frontend/src/components/Student/JoinSession.jsx`, `frontend/src/components/Student/StudentAttendance.jsx`, and `frontend/src/components/Student/StudentHistory.jsx`.

#### Browser-Side Proof Generation
The client ships proving assets under `frontend/public/circuits/`, specifically `proximity.wasm` and `proximity_final.zkey`. `frontend/src/services/zkProofService.js` likely generates a proof locally, submits it through the session API, and leaves server-side verification to the backend. This design keeps witness/proof generation in the browser while retaining acceptance authority on the API server.

Main entry points: [`frontend/src/App.jsx`](https://github.com/omkuthe/zkp-attendance/blob/main/frontend/src/App.jsx) (Application shell), [`frontend/src/services/zkProofService.js`](https://github.com/omkuthe/zkp-attendance/blob/main/frontend/src/services/zkProofService.js) (Browser proof generation), [`frontend/src/services/api.js`](https://github.com/omkuthe/zkp-attendance/blob/main/frontend/src/services/api.js) (API client), [`frontend/src/context/AuthContext.jsx`](https://github.com/omkuthe/zkp-attendance/blob/main/frontend/src/context/AuthContext.jsx) (Auth state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React client"]
  node_client_entry["Client entry<br/>Vite entry<br/>[main.jsx]"]
  node_app["Application shell<br/>React app<br/>[App.jsx]"]
  node_auth_context["Auth state<br/>React context<br/>[AuthContext.jsx]"]
  node_protected_routes["Route protection<br/>React guard<br/>[ProtectedRoute.jsx]"]
  node_role_workflows["Role workflows<br/>React views"]
  node_api_client["API client<br/>HTTP integration<br/>[api.js]"]
  node_proof_generator{{"Browser proof generation<br/>ZK service<br/>[zkProofService.js]"}}
  node_client_proving_assets["Client proving assets<br/>WASM and zkey"]
end

subgraph group_api["Backend API"]
  node_backend_entry["API entry<br/>FastAPI app<br/>[main.py]"]
  node_route_modules["Role and session routes<br/>API routes"]
  node_schemas["Payload contracts<br/>API schemas<br/>[schemas.py]"]
  node_credential_hasher["Credential processing<br/>Security utility<br/>[hasher.py]"]
  node_session_routes["Session lifecycle<br/>Session API<br/>[session.py]"]
end

subgraph group_data["Persistence"]
  node_database[("Database sessions<br/>Database setup<br/>[database.py]")]
  node_domain_models[("Attendance domain<br/>Persisted models<br/>[models.py]")]
end

subgraph group_zk["Zero-knowledge verification"]
  node_zk_verifier{{"Proof verifier<br/>Python verification boundary<br/>[zk_verifier.py]"}}
  node_node_helper["Node ZK helper<br/>Node bridge<br/>[verify_helper.js]"]
  node_server_proving_artifacts["Verification artifacts<br/>Circuit and keys<br/>[proximity.circom]"]
end

node_client_entry -->|"mounts"| node_app
node_app -->|"uses"| node_auth_context
node_app -->|"guards routes with"| node_protected_routes
node_protected_routes -->|"permits"| node_role_workflows
node_auth_context -->|"authenticates via"| node_api_client
node_role_workflows -->|"calls"| node_api_client
node_role_workflows -->|"joins sessions with"| node_proof_generator
node_proof_generator -->|"loads"| node_client_proving_assets
node_proof_generator -->|"submits proof to"| node_session_routes
node_api_client -->|"HTTP requests"| node_backend_entry
node_backend_entry -->|"registers"| node_route_modules
node_route_modules -->|"validates with"| node_schemas
node_route_modules -->|"uses for credentials"| node_credential_hasher
node_route_modules -->|"reads and writes"| node_domain_models
node_session_routes -->|"verifies proof with"| node_zk_verifier
node_zk_verifier -->|"invokes"| node_node_helper
node_node_helper -->|"uses"| node_server_proving_artifacts
node_domain_models -->|"persists through"| node_database

click node_client_entry "https://github.com/omkuthe/zkp-attendance/blob/main/frontend/src/main.jsx"
click node_app "https://github.com/omkuthe/zkp-attendance/blob/main/frontend/src/App.jsx"
click node_auth_context "https://github.com/omkuthe/zkp-attendance/blob/main/frontend/src/context/AuthContext.jsx"
click node_protected_routes "https://github.com/omkuthe/zkp-attendance/blob/main/frontend/src/components/Auth/ProtectedRoute.jsx"
click node_api_client "https://github.com/omkuthe/zkp-attendance/blob/main/frontend/src/services/api.js"
click node_proof_generator "https://github.com/omkuthe/zkp-attendance/blob/main/frontend/src/services/zkProofService.js"
click node_backend_entry "https://github.com/omkuthe/zkp-attendance/blob/main/backend/app/main.py"
click node_schemas "https://github.com/omkuthe/zkp-attendance/blob/main/backend/app/schemas.py"
click node_credential_hasher "https://github.com/omkuthe/zkp-attendance/blob/main/backend/app/utils/hasher.py"
click node_database "https://github.com/omkuthe/zkp-attendance/blob/main/backend/app/database.py"
click node_domain_models "https://github.com/omkuthe/zkp-attendance/blob/main/backend/app/models.py"
click node_session_routes "https://github.com/omkuthe/zkp-attendance/blob/main/backend/app/api/session.py"
click node_zk_verifier "https://github.com/omkuthe/zkp-attendance/blob/main/backend/app/zk_verifier.py"
click node_node_helper "https://github.com/omkuthe/zkp-attendance/blob/main/backend/verify_helper.js"
click node_server_proving_artifacts "https://github.com/omkuthe/zkp-attendance/blob/main/backend/zk/circuits/proximity.circom"

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_client_entry,node_app,node_auth_context,node_protected_routes,node_role_workflows,node_api_client,node_proof_generator,node_client_proving_assets toneBlue
class node_backend_entry,node_route_modules,node_schemas,node_credential_hasher,node_session_routes toneAmber
class node_database,node_domain_models toneMint
class node_zk_verifier,node_node_helper,node_server_proving_artifacts toneRose
```

## Components

### React client

- [Client entry](https://github.com/omkuthe/zkp-attendance/blob/main/frontend/src/main.jsx): Vite entry · `frontend/src/main.jsx`
- [Application shell](https://github.com/omkuthe/zkp-attendance/blob/main/frontend/src/App.jsx): React app · Composes role-specific product workflows. · `frontend/src/App.jsx`
- [Auth state](https://github.com/omkuthe/zkp-attendance/blob/main/frontend/src/context/AuthContext.jsx): React context · `frontend/src/context/AuthContext.jsx`
- [Route protection](https://github.com/omkuthe/zkp-attendance/blob/main/frontend/src/components/Auth/ProtectedRoute.jsx): React guard · `frontend/src/components/Auth/ProtectedRoute.jsx`
- **Role workflows**: React views · Admin, manager, and student attendance interfaces.
- [API client](https://github.com/omkuthe/zkp-attendance/blob/main/frontend/src/services/api.js): HTTP integration · Shared transport and domain-facing API clients. · `frontend/src/services/api.js`
- [Browser proof generation](https://github.com/omkuthe/zkp-attendance/blob/main/frontend/src/services/zkProofService.js): ZK service · Creates proximity proofs before session submission. · `frontend/src/services/zkProofService.js`
- **Client proving assets**: WASM and zkey · Browser-side circuit artifacts.

### Backend API

- [API entry](https://github.com/omkuthe/zkp-attendance/blob/main/backend/app/main.py): FastAPI app · `backend/app/main.py`
- **Role and session routes**: API routes · Auth, admin, manager, student, and session request boundary.
- [Payload contracts](https://github.com/omkuthe/zkp-attendance/blob/main/backend/app/schemas.py): API schemas · `backend/app/schemas.py`
- [Credential processing](https://github.com/omkuthe/zkp-attendance/blob/main/backend/app/utils/hasher.py): Security utility · `backend/app/utils/hasher.py`
- [Session lifecycle](https://github.com/omkuthe/zkp-attendance/blob/main/backend/app/api/session.py): Session API · Accepts attendance-session participation submissions. · `backend/app/api/session.py`

### Persistence

- [Database sessions](https://github.com/omkuthe/zkp-attendance/blob/main/backend/app/database.py): Database setup · `backend/app/database.py`
- [Attendance domain](https://github.com/omkuthe/zkp-attendance/blob/main/backend/app/models.py): Persisted models · Users, roles, internships, sessions, attendance, and holidays. · `backend/app/models.py`

### Zero-knowledge verification

- [Proof verifier](https://github.com/omkuthe/zkp-attendance/blob/main/backend/app/zk_verifier.py): Python verification boundary · Server authority for submitted proximity proofs. · `backend/app/zk_verifier.py`
- [Node ZK helper](https://github.com/omkuthe/zkp-attendance/blob/main/backend/verify_helper.js): Node bridge · Bridges Python verification to JavaScript ZK tooling. · `backend/verify_helper.js`
- [Verification artifacts](https://github.com/omkuthe/zkp-attendance/blob/main/backend/zk/circuits/proximity.circom): Circuit and keys · Circuit source, proving key, and verification key. · `backend/zk/circuits/proximity.circom`

## Connections

- Client entry → Application shell: mounts
- Application shell → Auth state: uses
- Application shell → Route protection: guards routes with
- Route protection → Role workflows: permits
- Auth state → API client: authenticates via
- Role workflows → API client: calls
- Role workflows → Browser proof generation: joins sessions with
- Browser proof generation → Client proving assets: loads
- Browser proof generation → Session lifecycle: submits proof to
- API client → API entry: HTTP requests
- API entry → Role and session routes: registers
- Role and session routes → Payload contracts: validates with
- Role and session routes → Credential processing: uses for credentials
- Role and session routes → Attendance domain: reads and writes
- Session lifecycle → Proof verifier: verifies proof with
- Proof verifier → Node ZK helper: invokes
- Node ZK helper → Verification artifacts: uses
- Attendance domain → Database sessions: persists through