amalbabu0/blockchain-based-voting-system

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.