omkuthe/zkp-attendance

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.