# amalbabu0/blockchain-based-voting-system architecture

> Architecture diagram of the GitHub repository amalbabu0/blockchain-based-voting-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amalbabu0/blockchain-based-voting-system
- Repository: https://github.com/amalbabu0/blockchain-based-voting-system

## Overview

1. **Repository shape**
   This is a single Django monolith, not a multi-service system. The main project is `voteP`, and the business app is `voteA`. The UI is server-rendered through Django templates, with static CSS/JS and uploaded media stored locally in the repo’s `static/` and `media/` folders.

2. **Core purpose**
   The application implements a **blockchain-based voting system**. The voting logic is split between normal Django persistence and a separate blockchain ledger layer, with the aim of making votes tamper-evident and auditable.

3. **Primary runtime boundary**
   HTTP requests enter through Django (`manage.py`, `voteP/urls.py`, `voteA/views.py`) and are rendered into templates in `templates/`. The app also exposes standard Django WSGI/ASGI entry points (`voteP/wsgi.py`, `voteP/asgi.py`), so the deployment boundary is the Django runtime rather than a separate API server.

4. **Presentation layer**
   The repository contains many role-specific pages: `admin_home`, `staff_home`, `student_home`, `candidate_home`, login/registration pages, election pages, vote pages, and results pages. This suggests a portal-style UI with different dashboards for different user types rather than a single generic interface.

5. **Role and workflow segmentation**
   The main user groups appear to be:
   - **Admin**: manages students, staff, candidates, election setup, and results
   - **Staff**: has its own home/dashboard and management-related views
   - **Student/Voter**: registers, logs in, votes, and views results
   - **Candidate**: registers, maintains a profile, and is surfaced in candidate listings and rankings  
   This role separation is a major architectural boundary in the app.

6. **Application/domain layer**
   `voteA/models.py` and the migration history show the domain is centered on entities such as **Student**, **Staff**, **Candidate** (later removed/merged in migrations), **Vote**, **VotingSession**, **TopCandidate**, **VoterRecord**, **Blog/Feed**, and admin/log entities. The migrations indicate the schema evolved heavily, which matters for the diagram because the database is not a simple fixed schema; it stores both voting and auxiliary content features.

7. **Persistence layer**
   The project uses **SQLite** (`db.sqlite3`) as the local relational database. Django ORM is the primary persistence mechanism for users, profiles, election metadata, votes, and related records. Uploaded images are stored separately under `media/student_images` and `media/blog_img`, indicating filesystem-backed media storage in addition to the database.

8. **Blockchain subsystem**
   There is a standalone `Blockchain.py` file plus a `blockchain.json` artifact. That strongly suggests the vote ledger is maintained outside the Django ORM in a custom blockchain implementation, with JSON-backed chain data. Architecturally, this is the key trust boundary: voting actions are likely written both to the Django database and to the blockchain ledger for integrity/traceability.

9. **Voting data flow**
   A typical vote flow likely looks like this:
   browser submits a vote through a Django template/view → the view validates the voter/session → the vote is recorded in Django models → the blockchain layer appends the vote transaction to the ledger → results pages read from the stored vote data and/or derived tallies.  
   The presence of `VotingSession`, `VoterRecord`, `TopCandidate`, and multiple results templates suggests the system separates raw voting records from computed summaries.

10. **Administration and moderation**
    The app includes management pages for students, staff, candidates, and election state, which indicates the admin dashboard is responsible for provisioning and controlling the election lifecycle. This is the central control plane for creating users, enabling voting, and reviewing results.

11. **Ancillary content subsystem**
    There are blog/feed-related models and templates (`blog.html`, `out_feed` migrations, `feed` model history). This appears to be a secondary content channel, likely used for announcements or communication around the election system. It is not the core voting path, but it shares the same Django app and database.

12. **Frontend assets**
    Static assets are plain CSS and JavaScript files under `static/assets/`, with no indication of a SPA framework. That means client-side behavior is supportive, while the main screen rendering and navigation are handled on the server through Django templates.

13. **Operational/tooling boundary**
    The project is designed to run locally with `python manage.py runserver`, migrations, and a Django superuser for admin access. The GitHub workflow file suggests some packaging/publishing automation, but the repository is primarily a Django application with local persistence and a custom blockchain ledger rather than cloud-native infrastructure.

14. **What to show in an architecture diagram**
    The most important boxes are:
    - Browser / user roles
    - Django views/controllers
    - Django ORM + SQLite database
    - Filesystem media/static assets
    - Custom blockchain module + `blockchain.json`
    - Django templates for role-specific dashboards  
    The key arrows are request/response between browser and Django, read/write between Django and SQLite, and vote append/verify between Django and the blockchain ledger.

Main entry points: [`voteA/views.py`](https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteA/views.py) (Views), [`voteP/urls.py`](https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteP/urls.py) (URL router), [`voteA/models.py`](https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteA/models.py) (Models), [`Blockchain.py`](https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/Blockchain.py) (Blockchain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Django runtime"]
  node_manage["manage.py<br/>entrypoint<br/>[manage.py]"]
  node_urls["URL router<br/>routing<br/>[urls.py]"]
  node_views["Views<br/>request handlers<br/>[views.py]"]
  node_templates["Templates<br/>server UI"]
  node_wsgi["WSGI<br/>deployment entrypoint<br/>[wsgi.py]"]
  node_asgi["ASGI<br/>deployment entrypoint<br/>[asgi.py]"]
end

subgraph group_domain["Vote domain"]
  node_models[("Models<br/>orm schema<br/>[models.py]")]
  node_migrations["Migrations<br/>schema history"]
  node_db[("SQLite DB<br/>relational store<br/>[db.sqlite3]")]
  node_admin["Admin ops<br/>control panel<br/>[admin.py]"]
  node_vote_flow{{"Vote flow<br/>workflow<br/>[models.py]"}}
  node_blog["Feed & blog<br/>content<br/>[models.py]"]
end

subgraph group_trust["Ledger trust"]
  node_blockchain{{"Blockchain<br/>ledger module<br/>[Blockchain.py]"}}
  node_chain_data["Ledger file<br/>json ledger<br/>[blockchain.json]"]
end

subgraph group_assets["Assets"]
  node_static_css["Stylesheets<br/>static assets<br/>[style.css]"]
  node_static_js["Scripts<br/>static assets<br/>[main.js]"]
  node_static_img["Static media<br/>static assets"]
  node_media_student["Student uploads<br/>uploaded media"]
  node_media_blog["Blog uploads<br/>uploaded media"]
end

node_manage -->|"loads routes"| node_urls
node_wsgi -->|"serves app"| node_urls
node_asgi -->|"serves app"| node_urls
node_urls -->|"dispatches"| node_views
node_views -->|"renders"| node_templates
node_views -->|"reads/writes"| node_models
node_models -->|"persists"| node_db
node_models -->|"evolves"| node_migrations
node_views -->|"manages"| node_admin
node_views -->|"records votes"| node_vote_flow
node_vote_flow -->|"stores"| node_db
node_views -->|"appends vote"| node_blockchain
node_blockchain -->|"serializes"| node_chain_data
node_views -->|"publishes"| node_blog
node_templates -->|"uses"| node_static_css
node_templates -->|"uses"| node_static_js
node_templates -->|"uses"| node_static_img
node_views -->|"uploads"| node_media_student
node_views -->|"uploads"| node_media_blog

click node_manage "https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/manage.py"
click node_urls "https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteP/urls.py"
click node_views "https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteA/views.py"
click node_models "https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteA/models.py"
click node_db "https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/db.sqlite3"
click node_admin "https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteA/admin.py"
click node_vote_flow "https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteA/models.py"
click node_blog "https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteA/models.py"
click node_wsgi "https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteP/wsgi.py"
click node_asgi "https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteP/asgi.py"
click node_blockchain "https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/Blockchain.py"
click node_chain_data "https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/blockchain.json"
click node_static_css "https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/static/assets/css/style.css"
click node_static_js "https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/static/assets/js/main.js"
click node_static_img "https://github.com/amalbabu0/blockchain-based-voting-system/tree/master/static/assets/img"
click node_media_student "https://github.com/amalbabu0/blockchain-based-voting-system/tree/master/media/student_images"
click node_media_blog "https://github.com/amalbabu0/blockchain-based-voting-system/tree/master/media/blog_img"

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_manage,node_urls,node_views,node_templates,node_wsgi,node_asgi toneBlue
class node_models,node_migrations,node_db,node_admin,node_vote_flow,node_blog toneAmber
class node_blockchain,node_chain_data toneMint
class node_static_css,node_static_js,node_static_img,node_media_student,node_media_blog toneRose
```

## Components

### Django runtime

HTTP entrypoints, URL routing, views, and server-rendered pages.

- [manage.py](https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/manage.py): entrypoint · Django command entrypoint for running the app and migrations. · `manage.py`
- [URL router](https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteP/urls.py): routing · Project-level URL configuration that dispatches requests into the app. · `voteP/urls.py`
- [Views](https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteA/views.py): request handlers · Main controller layer for role dashboards, voting, admin actions, and results. · `voteA/views.py`
- **Templates**: server UI · Role-specific server-rendered pages for login, dashboards, voting, management, and results.
- [WSGI](https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteP/wsgi.py): deployment entrypoint · Standard Django web entrypoint for synchronous deployment. · `voteP/wsgi.py`
- [ASGI](https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteP/asgi.py): deployment entrypoint · Standard Django async-capable entrypoint. · `voteP/asgi.py`

### Vote domain

Core voting models, election state, and administrative workflows.

- [Models](https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteA/models.py): orm schema · Django ORM domain models for students, staff, votes, sessions, records, blogs, and summaries. · `voteA/models.py`
- **Migrations**: schema history · Long migration chain showing evolving voting and content schema.
- [SQLite DB](https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/db.sqlite3): relational store · Local database backing users, election data, votes, and auxiliary content. · `db.sqlite3`
- [Admin ops](https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteA/admin.py): control panel · Provisioning and moderation workflows for students, staff, candidates, and election state. · `voteA/admin.py`
- [Vote flow](https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteA/models.py): workflow · Voting session and record handling, plus derived candidate tallies and results. · `voteA/models.py`
- [Feed & blog](https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/voteA/models.py): content · Ancillary announcement and feed-style content subsystem sharing the same app and database. · `voteA/models.py`

### Ledger trust

Custom blockchain ledger used to make votes auditable.

- [Blockchain](https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/Blockchain.py): ledger module · Custom blockchain implementation used to append and verify vote transactions. · `Blockchain.py`
- [Ledger file](https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/blockchain.json): json ledger · JSON-backed chain artifact storing blockchain state on disk. · `blockchain.json`

### Assets

Static files and uploaded media stored on disk.

- [Stylesheets](https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/static/assets/css/style.css): static assets · Server-served CSS used by the portal UI. · `static/assets/css/style.css`
- [Scripts](https://github.com/amalbabu0/blockchain-based-voting-system/blob/master/static/assets/js/main.js): static assets · Client-side behavior support for the rendered pages. · `static/assets/js/main.js`
- [Static media](https://github.com/amalbabu0/blockchain-based-voting-system/tree/master/static/assets/img): static assets · Bundled images and other fixed assets referenced by templates. · `static/assets/img`
- [Student uploads](https://github.com/amalbabu0/blockchain-based-voting-system/tree/master/media/student_images): uploaded media · Filesystem-backed student profile images. · `media/student_images`
- [Blog uploads](https://github.com/amalbabu0/blockchain-based-voting-system/tree/master/media/blog_img): uploaded media · Filesystem-backed blog and feed images. · `media/blog_img`

## Connections

- manage.py → URL router: loads routes · Django management/runtime starts the project and resolves URL dispatch.
- WSGI → URL router: serves app · WSGI deployment hands requests into the project URL configuration.
- ASGI → URL router: serves app · ASGI deployment hands requests into the project URL configuration.
- URL router → Views: dispatches · Routes map browser requests to view handlers.
- Views → Templates: renders · Views return server-rendered portal pages for the different roles.
- Views → Models: reads/writes · Request handlers persist and query election and user domain state through the ORM.
- Models → SQLite DB: persists · Django ORM stores the application schema in SQLite.
- Models → Migrations: evolves · Migrations describe the changing domain schema over time.
- Views → Admin ops: manages · Admin-facing views provision users and control the election lifecycle.
- Views → Vote flow: records votes · Voting views validate sessions and store vote records and tallies.
- Vote flow → SQLite DB: stores · Vote records, sessions, and summaries are backed by the relational database.
- Views → Blockchain: appends vote · Voting actions are mirrored into the ledger layer for auditability.
- Blockchain → Ledger file: serializes · The custom ledger persists chain state in a JSON artifact.
- Views → Feed & blog: publishes · Announcement and feed pages are served from the same Django app.
- Templates → Stylesheets: uses · Pages load shared styling from static CSS assets.
- Templates → Scripts: uses · Pages load supporting browser behavior from JavaScript assets.
- Templates → Static media: uses · Templates reference bundled static imagery.
- Views → Student uploads: uploads · Student profile flows store images on the filesystem.
- Views → Blog uploads: uploads · Blog/feed flows store uploaded images on the filesystem.