# mikhagirsang29/e-vote-stuco architecture

> Architecture diagram of the GitHub repository mikhagirsang29/e-vote-stuco, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mikhagirsang29/e-vote-stuco
- Repository: https://github.com/mikhagirsang29/e-vote-stuco

## Overview

VoteStuCo is a LAN student-council election portal. Students sign in, view candidates and election status, cast one vote while voting is open, and receive a receipt; a successful vote also triggers live result updates. Administrators manage election data and settings, review results, and verify receipts. The graph includes the database and shared authentication/receipt helpers as internal layers. Unsampled templates and admin capabilities are included where supported by the README or source index; links are limited to evidenced calls or documented behavior.

Main entry points: [`routes/client.py`](https://github.com/mikhagirsang29/e-vote-stuco/blob/main/routes/client.py) (Voter routes), [`routes/admin.py`](https://github.com/mikhagirsang29/e-vote-stuco/blob/main/routes/admin.py) (Admin routes), [`main.py`](https://github.com/mikhagirsang29/e-vote-stuco/blob/main/main.py) (FastAPI application), [`database.py`](https://github.com/mikhagirsang29/e-vote-stuco/blob/main/database.py) (Election database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_voting["Voter workflow"]
  node_client["Voter routes<br/>[client.py]"]
end

subgraph group_admin["Election administration"]
  node_admin_routes["Admin routes<br/>[admin.py]"]
end

subgraph group_realtime["Live results"]
  node_manager["WebSocket manager<br/>[admin.py]"]
  node_ws_client["HTMX WebSocket client<br/>[ws.js]"]
end

subgraph group_core["Application core"]
  node_auth["Identity and receipts<br/>[utilities.py]"]
  node_db[("Election database<br/>[database.py]")]
  node_app["FastAPI application<br/>[main.py]"]
  node_views["Page templates"]
end

node_student(("Student voter"))
node_browser(("Connected browsers"))

node_student -->|"uses portal"| node_client
node_client -->|"uses identity helpers"| node_auth
node_client -->|"reads and records votes"| node_db
node_client -->|"renders voter pages"| node_views
node_client -->|"broadcasts results"| node_manager
node_manager -->|"sends updates"| node_browser
node_browser -.->|"receives messages"| node_ws_client
node_admin_routes -->|"uses identity helpers"| node_auth
node_admin_routes -->|"manages election data"| node_db
node_admin_routes -->|"renders admin pages"| node_views
node_admin_routes -->|"hosts WebSocket manager"| node_manager
node_app -->|"registers router"| node_client
node_app -->|"registers router"| node_admin_routes
node_app -->|"seeds election state"| node_db

click node_client "https://github.com/mikhagirsang29/e-vote-stuco/blob/main/routes/client.py"
click node_auth "https://github.com/mikhagirsang29/e-vote-stuco/blob/main/utilities/utilities.py"
click node_admin_routes "https://github.com/mikhagirsang29/e-vote-stuco/blob/main/routes/admin.py"
click node_manager "https://github.com/mikhagirsang29/e-vote-stuco/blob/main/routes/admin.py"
click node_ws_client "https://github.com/mikhagirsang29/e-vote-stuco/blob/main/static/ws.js"
click node_db "https://github.com/mikhagirsang29/e-vote-stuco/blob/main/database.py"
click node_app "https://github.com/mikhagirsang29/e-vote-stuco/blob/main/main.py"
click node_views "https://github.com/mikhagirsang29/e-vote-stuco/tree/main/templates"

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_client,node_browser toneBlue
class node_admin_routes toneAmber
class node_manager,node_ws_client toneMint
class node_auth,node_db,node_app,node_views toneRose
class node_student toneIndigo
```

## Components

### Voter workflow

- [Voter routes](https://github.com/mikhagirsang29/e-vote-stuco/blob/main/routes/client.py): `routes/client.py`

### Election administration

- [Admin routes](https://github.com/mikhagirsang29/e-vote-stuco/blob/main/routes/admin.py): `routes/admin.py`

### Live results

- [WebSocket manager](https://github.com/mikhagirsang29/e-vote-stuco/blob/main/routes/admin.py): `routes/admin.py`
- [HTMX WebSocket client](https://github.com/mikhagirsang29/e-vote-stuco/blob/main/static/ws.js): `static/ws.js`

### Application core

- [Identity and receipts](https://github.com/mikhagirsang29/e-vote-stuco/blob/main/utilities/utilities.py): `utilities/utilities.py`
- [Election database](https://github.com/mikhagirsang29/e-vote-stuco/blob/main/database.py): `database.py`
- [FastAPI application](https://github.com/mikhagirsang29/e-vote-stuco/blob/main/main.py): `main.py`
- [Page templates](https://github.com/mikhagirsang29/e-vote-stuco/tree/main/templates): `templates`

### Other components

- **Student voter**
- **Connected browsers**

## Connections

- Student voter → Voter routes: uses portal (evidence: `README.md`)
- Voter routes → Identity and receipts: uses identity helpers (evidence: `routes/client.py`)
- Voter routes → Election database: reads and records votes (evidence: `routes/client.py`)
- Voter routes → Page templates: renders voter pages (evidence: `routes/client.py`)
- Voter routes → WebSocket manager: broadcasts results (evidence: `routes/client.py`)
- WebSocket manager → Connected browsers: sends updates (evidence: `routes/admin.py`)
- Connected browsers → HTMX WebSocket client: receives messages
- Admin routes → Identity and receipts: uses identity helpers (evidence: `routes/admin.py`)
- Admin routes → Election database: manages election data (evidence: `routes/admin.py`)
- Admin routes → Page templates: renders admin pages (evidence: `routes/admin.py`)
- Admin routes → WebSocket manager: hosts WebSocket manager (evidence: `routes/admin.py`)
- FastAPI application → Voter routes: registers router (evidence: `main.py`)
- FastAPI application → Admin routes: registers router (evidence: `main.py`)
- FastAPI application → Election database: seeds election state (evidence: `main.py`)
