# e-voting-using-blockchain/off-chain-verification architecture

> Architecture diagram of the GitHub repository e-voting-using-blockchain/off-chain-verification, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/e-voting-using-blockchain/off-chain-verification
- Repository: https://github.com/e-voting-using-blockchain/off-chain-verification

## Overview

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`](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend) (Database), [`evoting_backend/evoting_backend/urls.py`](https://github.com/e-voting-using-blockchain/off-chain-verification/blob/main/evoting_backend/evoting_backend/urls.py) (Django API), [`evoting_frontend/src/services`](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_frontend/src/services) (API client), [`evoting_backend/elections`](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend/elections) (Elections)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_spa["SPA<br/>React/Vite app"]
  node_auth_ctx(("Auth context<br/>client state<br/>[AuthContext.jsx]"))
  node_api_client["API client<br/>service layer"]
  node_student_ui["Student UI<br/>role pages"]
  node_admin_ui["Admin UI<br/>role pages"]
  node_hod_ui["HOD UI<br/>role pages"]
  node_teacher_ui["Teacher UI<br/>role pages"]
  node_ui_components["Shared UI<br/>components"]
end

subgraph group_backend["Backend"]
  node_django_api["Django API<br/>REST backend<br/>[urls.py]"]
  node_accounts_app["Accounts<br/>auth and RBAC"]
  node_verification_app["Verification<br/>workflow engine"]
  node_elections_app["Elections<br/>voting domain"]
  node_dashboards_app["Dashboards<br/>read models"]
  node_notifications_app["Notifications<br/>alerts"]
  node_audit_app["Audit<br/>compliance log"]
  node_blockchain_app["Blockchain<br/>external trust layer"]
  node_blockchain_service["Chain service<br/>integration"]
  node_db[("Database<br/>relational persistence")]
  node_admin_console["Django admin<br/>ops interface<br/>[admin.py]"]
  node_mgmt_cmds["Commands<br/>maintenance jobs"]
  node_signals(("Signals<br/>event hooks<br/>[signals.py]"))
end

node_spa -->|"session"| node_auth_ctx
node_spa -->|"REST calls"| node_api_client
node_student_ui -->|"student flows"| node_api_client
node_admin_ui -->|"admin flows"| node_api_client
node_hod_ui -->|"HOD flows"| node_api_client
node_teacher_ui -->|"teacher flows"| node_api_client
node_api_client -->|"HTTP API"| node_django_api
node_django_api -->|"auth"| node_accounts_app
node_django_api -->|"verification"| node_verification_app
node_django_api -->|"elections"| node_elections_app
node_django_api -->|"dashboards"| node_dashboards_app
node_django_api -->|"notifications"| node_notifications_app
node_django_api -->|"audit"| node_audit_app
node_accounts_app -->|"store"| node_db
node_verification_app -->|"store"| node_db
node_elections_app -->|"store"| node_db
node_dashboards_app -->|"read"| node_db
node_notifications_app -->|"store"| node_db
node_audit_app -->|"store"| node_db
node_blockchain_app -->|"store"| node_db
node_elections_app -->|"verify hash"| node_blockchain_service
node_blockchain_service -->|"trust boundary"| node_blockchain_app
node_elections_app -->|"emit"| node_signals
node_verification_app -->|"emit"| node_signals
node_signals -->|"fan out"| node_notifications_app
node_signals -->|"fan out"| node_audit_app
node_admin_console -->|"manage"| node_db
node_mgmt_cmds -->|"maintenance"| node_db
node_admin_console -->|"ops"| node_accounts_app
node_admin_console -->|"ops"| node_elections_app

click node_spa "https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_frontend/src"
click node_auth_ctx "https://github.com/e-voting-using-blockchain/off-chain-verification/blob/main/evoting_frontend/src/context/AuthContext.jsx"
click node_api_client "https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_frontend/src/services"
click node_student_ui "https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_frontend/src/pages/student"
click node_admin_ui "https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_frontend/src/pages/admin"
click node_hod_ui "https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_frontend/src/pages/hod"
click node_teacher_ui "https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_frontend/src/pages/teacher"
click node_ui_components "https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_frontend/src/components"
click node_django_api "https://github.com/e-voting-using-blockchain/off-chain-verification/blob/main/evoting_backend/evoting_backend/urls.py"
click node_accounts_app "https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend/accounts"
click node_verification_app "https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend/verification"
click node_elections_app "https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend/elections"
click node_dashboards_app "https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend/dashboards"
click node_notifications_app "https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend/notifications"
click node_audit_app "https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend/audit"
click node_blockchain_app "https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend/blockchain"
click node_blockchain_service "https://github.com/e-voting-using-blockchain/off-chain-verification/blob/main/evoting_backend/elections/blockchain_service.py"
click node_db "https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend"
click node_admin_console "https://github.com/e-voting-using-blockchain/off-chain-verification/blob/main/evoting_backend/accounts/admin.py"
click node_mgmt_cmds "https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend/elections/management/commands"
click node_signals "https://github.com/e-voting-using-blockchain/off-chain-verification/blob/main/evoting_backend/notifications/signals.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_spa,node_auth_ctx,node_api_client,node_student_ui,node_admin_ui,node_hod_ui,node_teacher_ui,node_ui_components toneBlue
class node_django_api,node_accounts_app,node_verification_app,node_elections_app,node_dashboards_app,node_notifications_app,node_audit_app,node_blockchain_app,node_blockchain_service,node_db,node_admin_console,node_mgmt_cmds,node_signals toneAmber
```

## Components

### Frontend

React/Vite SPA organized by role and shared components

- [SPA](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_frontend/src): React/Vite app · Browser-based single-page application for all roles · `evoting_frontend/src`
- [Auth context](https://github.com/e-voting-using-blockchain/off-chain-verification/blob/main/evoting_frontend/src/context/AuthContext.jsx): client state · Holds session, login, and role awareness on the client · `evoting_frontend/src/context/AuthContext.jsx`
- [API client](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_frontend/src/services): service layer · Shared REST service modules used by pages and components · `evoting_frontend/src/services`
- [Student UI](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_frontend/src/pages/student): role pages · Student dashboard, voting, wallet, and verification screens · `evoting_frontend/src/pages/student`
- [Admin UI](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_frontend/src/pages/admin): role pages · Admin dashboard and management screens for global operations · `evoting_frontend/src/pages/admin`
- [HOD UI](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_frontend/src/pages/hod): role pages · HOD dashboard and approval/department management screens · `evoting_frontend/src/pages/hod`
- [Teacher UI](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_frontend/src/pages/teacher): role pages · Teacher dashboard and verification/election management screens · `evoting_frontend/src/pages/teacher`
- [Shared UI](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_frontend/src/components): components · Reusable layout, modal, dashboard, and student components · `evoting_frontend/src/components`

### Backend

Django REST monolith with domain apps, admin, and operational commands

- [Django API](https://github.com/e-voting-using-blockchain/off-chain-verification/blob/main/evoting_backend/evoting_backend/urls.py): REST backend · Core backend entrypoint exposing the application API · `evoting_backend/evoting_backend/urls.py`
- [Accounts](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend/accounts): auth and RBAC · Authentication, roles, verification flags, deletions, and HOD invitations · `evoting_backend/accounts`
- [Verification](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend/verification): workflow engine · Student and faculty verification, profiles, requests, appeals, and document access · `evoting_backend/verification`
- [Elections](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend/elections): voting domain · Departments, classes, elections, candidates, vote records, and view requests · `evoting_backend/elections`
- [Dashboards](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend/dashboards): read models · Backend aggregation layer for role-specific dashboard data · `evoting_backend/dashboards`
- [Notifications](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend/notifications): alerts · User notifications and signal-driven side effects · `evoting_backend/notifications`
- [Audit](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend/audit): compliance log · Sensitive action logging for view, approve, and reject events · `evoting_backend/audit`
- [Blockchain](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend/blockchain): external trust layer · On-chain identity-hash verification boundary · `evoting_backend/blockchain`
- [Chain service](https://github.com/e-voting-using-blockchain/off-chain-verification/blob/main/evoting_backend/elections/blockchain_service.py): integration · Backend helper used by elections to talk to the blockchain layer · `evoting_backend/elections/blockchain_service.py`
- [Database](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend): relational persistence · Shared relational store used by Django apps; SQLite in development and PostgreSQL in production · `evoting_backend`
- [Django admin](https://github.com/e-voting-using-blockchain/off-chain-verification/blob/main/evoting_backend/accounts/admin.py): ops interface · Operational management interface for backend models · `evoting_backend/accounts/admin.py`
- [Commands](https://github.com/e-voting-using-blockchain/off-chain-verification/tree/main/evoting_backend/elections/management/commands): maintenance jobs · Data population and request-expiration maintenance commands · `evoting_backend/elections/management/commands`
- [Signals](https://github.com/e-voting-using-blockchain/off-chain-verification/blob/main/evoting_backend/notifications/signals.py): event hooks · Internal event boundary for notification and election side effects · `evoting_backend/notifications/signals.py`

## Connections

- 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
