How e-voting-using-blockchain/off-chain-verification works
1. Overall shape
- This repository is a two-tier system: a Django REST backend (evoting_backend) and a React/Vite frontend (evoting_frontend).
- The backend is a modular monolith split into Django apps; the frontend is a single-page application organized by role-specific pages and reusable components.
- The main runtime boundary is browser/UI → REST API → database, with a secondary boundary to a blockchain integration for identity-hash verification.
2. Backend as the system of record
- Django + DRF expose the application API, while the Django admin is also used for operational management.
- Persistent state is stored in a relational database, using SQLite for development and PostgreSQL in production per the README.
- Each backend app owns a distinct slice of the domain and has its own models, serializers, views, URLs, and migrations.
3. Identity, roles, and access control
- The accounts app is the authentication and RBAC core.
- It manages user records, roles, verification status, deletion flags, and HOD invitations.
- This app is the foundation for login, role-based authorization, and gating access to the rest of the system.
4. Verification workflow is a major business subsystem
- The verification app handles student/faculty identity verification, profile data, document access requests, account verification requests, and appeals.
- It is where pending/approved/rejected states live, so it acts as the workflow engine for onboarding users before they can fully participate.
- This subsystem is tightly coupled to roles in accounts and to downstream election eligibility.
5. Election and participation domain
- The elections app manages the core voting model: departments, classes, elections, candidates, vote records, and department view requests.
- It also includes timing and lifecycle concerns such as nomination periods, election dates, and expiring requests through a management command.
- This app is the central domain for operational election setup and participation tracking.
6. Blockchain integration is a narrow external boundary
- Blockchain-related code is isolated into a dedicated blockchain app plus elections/blockchain_service.py.
- The README indicates the purpose is to store a student identity hash on-chain, so the blockchain is used as a verification adjunct rather than the primary datastore.
- Architecturally, this is an external trust/immutability layer connected from the election/verification flow.
7. Audit logging and traceability
- The audit app records sensitive actions such as viewing, approving, and rejecting.
- This is a cross-cutting concern: it likely receives events from other apps rather than owning a primary user-facing workflow.
- For an architecture diagram, treat it as a compliance/observability subsystem fed by business actions across the backend.
8. Notifications and signal-driven side effects
- The notifications app provides user-facing notifications and is wired through Django signals.
- Signals also appear in elections and notifications, which suggests asynchronous or event-style reactions to domain changes.
- This creates an internal event boundary: domain mutations in one app trigger follow-on actions in another without direct coupling in the request handler.
9. Dashboards are role-specific read models
- The dashboards app exists as a backend layer for dashboard data presentation.
- On the frontend, separate dashboard pages exist for admin, HOD, teacher, and student roles.
- Conceptually, dashboards aggregate data from accounts, verification, elections, notifications, and audit for role-specific views.
10. Frontend structure mirrors the roles
- The React app is organized by role and feature: admin, student, teacher, HOD, auth, shared components, and modal dialogs.
- src/services contains the API client layer, so the frontend does not talk directly to backend internals; it consumes REST endpoints through service modules.
- AuthContext is the main client-side state boundary for login/session/role awareness.
11. Client-side feature groups
- Student features cover elections, wallet/linking, verification status, vote history, and candidate invitations.
- Teacher and HOD features cover approval queues, class/dept management, and election administration.
- Admin features cover global management of departments, faculty, HODs, elections, and approvals.
12. Operational and lifecycle tooling
- The backend includes management commands for bootstrapping data (populate_data) and expiring stale requests (expire_requests).
- There are also scripts for debugging HOD/department sync and database reset helpers.
- This indicates the system is not purely request-driven; it has maintenance workflows that operate on the same domain models.
13. Primary data flow to diagram
- User action in the browser goes through the React service layer to a Django API endpoint.
- The backend authenticates/authorizes the request, mutates relational state, may emit signals, may write audit entries, may create notifications, and may call the blockchain service.
- The response then drives role-specific UI updates in the SPA.
14. Key architecture boundaries
- Presentation boundary: React pages/components vs. Django API.
- Domain boundary: accounts, verification, elections, audit, notifications, blockchain, dashboards.
- External trust boundary: blockchain network/service.
- Persistence boundary: relational database plus blockchain-backed verification data.
15. How to draw it
- At the center, place the Django backend as the hub with the six main apps around it.
- Connect the frontend SPA to backend REST endpoints.
- Connect elections/verification to blockchain as an external service.
- Connect all sensitive actions to audit and notification side effects.
- Show the database as shared persistence across the backend apps, with Django admin and management commands as operational interfaces.
Main entry points: evoting_backend Database · urls.py Django API · services API client · elections Elections
Components 21
Frontend
React/Vite SPA organized by role and shared components
- SPA · Browser-based single-page application for all roles
evoting_frontend/src - Auth context · Holds session, login, and role awareness on the client
evoting_frontend/src/context/AuthContext.jsx - API client · Shared REST service modules used by pages and components
evoting_frontend/src/services - Student UI · Student dashboard, voting, wallet, and verification screens
evoting_frontend/src/pages/student - Admin UI · Admin dashboard and management screens for global operations
evoting_frontend/src/pages/admin - HOD UI · HOD dashboard and approval/department management screens
evoting_frontend/src/pages/hod - Teacher UI · Teacher dashboard and verification/election management screens
evoting_frontend/src/pages/teacher - Shared UI · Reusable layout, modal, dashboard, and student components
evoting_frontend/src/components
Backend
Django REST monolith with domain apps, admin, and operational commands
- Django API · Core backend entrypoint exposing the application API
evoting_backend/evoting_backend/urls.py - Accounts · Authentication, roles, verification flags, deletions, and HOD invitations
evoting_backend/accounts - Verification · Student and faculty verification, profiles, requests, appeals, and document access
evoting_backend/verification - Elections · Departments, classes, elections, candidates, vote records, and view requests
evoting_backend/elections - Dashboards · Backend aggregation layer for role-specific dashboard data
evoting_backend/dashboards - Notifications · User notifications and signal-driven side effects
evoting_backend/notifications - Audit · Sensitive action logging for view, approve, and reject events
evoting_backend/audit - Blockchain · On-chain identity-hash verification boundary
evoting_backend/blockchain - Chain service · Backend helper used by elections to talk to the blockchain layer
evoting_backend/elections/blockchain_service.py - Database · Shared relational store used by Django apps; SQLite in development and PostgreSQL in production
evoting_backend - Django admin · Operational management interface for backend models
evoting_backend/accounts/admin.py - Commands · Data population and request-expiration maintenance commands
evoting_backend/elections/management/commands - Signals · Internal event boundary for notification and election side effects
evoting_backend/notifications/signals.py
Connections 30
- SPA → Auth context: session · UI uses client auth state to track login and role
- SPA → API client: REST calls · Pages and components consume backend endpoints through service modules
- Student UI → API client: student flows · Student pages use the service layer for election and verification actions
- Admin UI → API client: admin flows · Admin pages use the service layer for management actions
- HOD UI → API client: HOD flows · HOD pages use the service layer for approvals and department actions
- Teacher UI → API client: teacher flows · Teacher pages use the service layer for verification and election actions
- API client → Django API: HTTP API · Frontend services communicate with the Django REST backend
- Django API → Accounts: auth · Routes for login, roles, invitations, and permission checks
- Django API → Verification: verification · Routes for profile verification, requests, and appeals
- Django API → Elections: elections · Routes for election setup, candidates, votes, and requests
- Django API → Dashboards: dashboards · Routes that assemble role-specific dashboard data
- Django API → Notifications: notifications · Routes for fetching and managing notifications
- Django API → Audit: audit · Routes for reviewing sensitive action logs
- Accounts → Database: store · Persists users, roles, verification state, and invitations
- Verification → Database: store · Persists profiles, requests, appeals, and document state
- Elections → Database: store · Persists elections, departments, classes, candidates, and votes
- Dashboards → Database: read · Reads across domain tables to build dashboard views
- Notifications → Database: store · Persists user notification records
- Audit → Database: store · Persists audit log entries
- Blockchain → Database: store · Stores blockchain-side metadata needed by the backend
- Elections → Chain service: verify hash · Election and verification flow can call the blockchain helper
- Chain service → Blockchain: trust boundary · Integration crosses into the blockchain-specific subsystem
- Elections → Signals: emit · Domain mutations can trigger internal signals
- Verification → Signals: emit · Verification state changes can trigger internal signals
- Signals → Notifications: fan out · Signals drive notification creation and updates
- Signals → Audit: fan out · Signals can also produce audit entries for sensitive actions
- Django admin → Database: manage · Operational admin interacts with the same persisted models
- Commands → Database: maintenance · Commands populate data and expire stale requests in persistence
- Django admin → Accounts: ops · Admin interface is especially important for account and role management
- Django admin → Elections: ops · Admin interface manages elections, departments, and classes