# hseha/omnivote architecture

> Architecture diagram of the GitHub repository hseha/omnivote, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hseha/omnivote
- Repository: https://github.com/hseha/omnivote

## Overview

OmniVote is a school SSG election system: students enroll and vote by secret ballot, while election staff administer candidates and election phases and publish results. The React console and Flutter student app use the Laravel API, which the README identifies as authoritative for rules; the clients deliberately use different authentication transports. The Flutter Dart sources are not in the supplied tree, so its node uses the existing app directory and its internal flow is not expanded. Backend relationships beyond the excerpts are included only where the README or source index supports them.

Main entry points: [`backend-laravel/routes/api.php`](https://github.com/hseha/omnivote/blob/main/backend-laravel/routes/api.php) (API routes), [`backend-laravel/app/Models`](https://github.com/hseha/omnivote/tree/main/backend-laravel/app/Models) (Election records), [`admin-react/src/App.jsx`](https://github.com/hseha/omnivote/blob/main/admin-react/src/App.jsx) (Admin console), [`backend-laravel/app/Http/Controllers/AdminUserController.php`](https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/AdminUserController.php) (User administration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User applications"]
  node_admin_app["Admin console<br/>[App.jsx]"]
  node_admin_screens["Admin screens"]
  node_admin_auth["Console auth<br/>[AuthContext.jsx]"]
  node_admin_api["Console API client<br/>[api.js]"]
  node_student_app["Student app"]
end

subgraph group_api["API and access"]
  node_api_routes["API routes<br/>[api.php]"]
  node_admin_auth_api["Admin authentication"]
  node_student_access["Student access"]
end

subgraph group_election["Election operations"]
  node_registration["Enrollment and imports"]
  node_candidacy["Candidate management"]
  node_election_config["Election setup"]
  node_ballot["Ballot and voting"]
  node_results["Results and archive"]
  node_announcements["Announcements"]
  node_user_admin["User administration"]
end

subgraph group_shared["Shared services"]
  node_domain_models[("Election records")]
  node_notifications["Notifications<br/>[Notifier.php]"]
end

node_committee(("Election staff"))
node_students(("Students"))
node_mail["Email service"]

node_committee -->|"administers"| node_admin_app
node_admin_app -->|"switches views"| node_admin_screens
node_admin_app -->|"provides auth"| node_admin_auth
node_admin_auth -->|"sets handlers"| node_admin_api
node_admin_api -->|"sends requests"| node_api_routes
node_students -->|"uses"| node_student_app
node_student_app -->|"sends requests"| node_api_routes
node_api_routes -->|"routes to"| node_admin_auth_api
node_api_routes -->|"routes to"| node_student_access
node_api_routes -->|"routes to"| node_registration
node_api_routes -->|"routes to"| node_candidacy
node_api_routes -->|"routes to"| node_election_config
node_api_routes -->|"routes to"| node_ballot
node_api_routes -->|"routes to"| node_results
node_api_routes -->|"routes to"| node_announcements
node_api_routes -->|"routes to"| node_user_admin
node_admin_auth_api -->|"uses accounts"| node_domain_models
node_registration -->|"uses student records"| node_domain_models
node_candidacy -->|"uses candidates"| node_domain_models
node_results -->|"reads election data"| node_domain_models
node_user_admin -->|"manages accounts"| node_domain_models
node_user_admin -->|"notifies admins"| node_notifications
node_notifications -->|"sends email"| node_mail

click node_admin_app "https://github.com/hseha/omnivote/blob/main/admin-react/src/App.jsx"
click node_admin_screens "https://github.com/hseha/omnivote/tree/main/admin-react/src"
click node_admin_auth "https://github.com/hseha/omnivote/blob/main/admin-react/src/lib/AuthContext.jsx"
click node_admin_api "https://github.com/hseha/omnivote/blob/main/admin-react/src/lib/api.js"
click node_student_app "https://github.com/hseha/omnivote/tree/main/user-flutter"
click node_api_routes "https://github.com/hseha/omnivote/blob/main/backend-laravel/routes/api.php"
click node_admin_auth_api "https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/AdminAuthController.php"
click node_student_access "https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/StudentAuthController.php"
click node_registration "https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/RegistrarImportController.php"
click node_candidacy "https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/AdminCandidateController.php"
click node_election_config "https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/ElectionController.php"
click node_ballot "https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/BallotController.php"
click node_results "https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/ResultsController.php"
click node_announcements "https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/AnnouncementController.php"
click node_user_admin "https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/AdminUserController.php"
click node_domain_models "https://github.com/hseha/omnivote/tree/main/backend-laravel/app/Models"
click node_notifications "https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Support/Notifier.php"

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_admin_app,node_admin_screens,node_admin_auth,node_admin_api,node_student_app toneBlue
class node_api_routes,node_admin_auth_api,node_student_access toneAmber
class node_registration,node_candidacy,node_election_config,node_ballot,node_results,node_announcements,node_user_admin toneMint
class node_domain_models,node_notifications toneRose
class node_committee,node_students,node_mail toneIndigo
```

## Components

### User applications

- [Admin console](https://github.com/hseha/omnivote/blob/main/admin-react/src/App.jsx): `admin-react/src/App.jsx`
- [Admin screens](https://github.com/hseha/omnivote/tree/main/admin-react/src): `admin-react/src`
- [Console auth](https://github.com/hseha/omnivote/blob/main/admin-react/src/lib/AuthContext.jsx): `admin-react/src/lib/AuthContext.jsx`
- [Console API client](https://github.com/hseha/omnivote/blob/main/admin-react/src/lib/api.js): `admin-react/src/lib/api.js`
- [Student app](https://github.com/hseha/omnivote/tree/main/user-flutter): `user-flutter`

### API and access

- [API routes](https://github.com/hseha/omnivote/blob/main/backend-laravel/routes/api.php): `backend-laravel/routes/api.php`
- [Admin authentication](https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/AdminAuthController.php): `backend-laravel/app/Http/Controllers/AdminAuthController.php`
- [Student access](https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/StudentAuthController.php): `backend-laravel/app/Http/Controllers/StudentAuthController.php`

### Election operations

- [Enrollment and imports](https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/RegistrarImportController.php): `backend-laravel/app/Http/Controllers/RegistrarImportController.php`
- [Candidate management](https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/AdminCandidateController.php): `backend-laravel/app/Http/Controllers/AdminCandidateController.php`
- [Election setup](https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/ElectionController.php): `backend-laravel/app/Http/Controllers/ElectionController.php`
- [Ballot and voting](https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/BallotController.php): `backend-laravel/app/Http/Controllers/BallotController.php`
- [Results and archive](https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/ResultsController.php): `backend-laravel/app/Http/Controllers/ResultsController.php`
- [Announcements](https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/AnnouncementController.php): `backend-laravel/app/Http/Controllers/AnnouncementController.php`
- [User administration](https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Http/Controllers/AdminUserController.php): `backend-laravel/app/Http/Controllers/AdminUserController.php`

### Shared services

- [Election records](https://github.com/hseha/omnivote/tree/main/backend-laravel/app/Models): `backend-laravel/app/Models`
- [Notifications](https://github.com/hseha/omnivote/blob/main/backend-laravel/app/Support/Notifier.php): `backend-laravel/app/Support/Notifier.php`

### Other components

- **Election staff**
- **Students**
- **Email service**

## Connections

- Election staff → Admin console: administers (evidence: `README.md`)
- Admin console → Admin screens: switches views (evidence: `admin-react/src/App.jsx`)
- Admin console → Console auth: provides auth (evidence: `admin-react/src/App.jsx`)
- Console auth → Console API client: sets handlers (evidence: `admin-react/src/lib/AuthContext.jsx`)
- Console API client → API routes: sends requests (evidence: `README.md`)
- Students → Student app: uses (evidence: `README.md`)
- Student app → API routes: sends requests (evidence: `README.md`)
- API routes → Admin authentication: routes to (evidence: `backend-laravel/routes/api.php`)
- API routes → Student access: routes to (evidence: `backend-laravel/routes/api.php`)
- API routes → Enrollment and imports: routes to (evidence: `backend-laravel/routes/api.php`)
- API routes → Candidate management: routes to (evidence: `backend-laravel/routes/api.php`)
- API routes → Election setup: routes to (evidence: `backend-laravel/routes/api.php`)
- API routes → Ballot and voting: routes to (evidence: `backend-laravel/routes/api.php`)
- API routes → Results and archive: routes to (evidence: `backend-laravel/routes/api.php`)
- API routes → Announcements: routes to (evidence: `backend-laravel/routes/api.php`)
- API routes → User administration: routes to (evidence: `backend-laravel/routes/api.php`)
- Admin authentication → Election records: uses accounts (evidence: `backend-laravel/app/Http/Controllers/AdminAuthController.php`)
- Enrollment and imports → Election records: uses student records (evidence: `backend-laravel/app/Http/Controllers/RegistrarImportController.php`)
- Candidate management → Election records: uses candidates (evidence: `backend-laravel/app/Http/Controllers/AdminCandidateController.php`)
- Results and archive → Election records: reads election data (evidence: `backend-laravel/app/Http/Controllers/ResultsController.php`)
- User administration → Election records: manages accounts (evidence: `backend-laravel/app/Http/Controllers/AdminUserController.php`)
- User administration → Notifications: notifies admins (evidence: `backend-laravel/app/Http/Controllers/AdminUserController.php`)
- Notifications → Email service: sends email (evidence: `backend-laravel/app/Support/Notifier.php`)