# waldirborbajr/govote architecture

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

- Interactive diagram: https://gitdiagram.com/waldirborbajr/govote
- Repository: https://github.com/waldirborbajr/govote

## Overview

GoVote is a secure voting service with JSON endpoints and a server-rendered voter/admin interface. Voters request and verify passcodes (including a separate Telegram-bot integration), browse active polls, cast votes, and view results; administrators manage polls and accounts. Poll logic validates and records votes against SQLite, with optional Redis caching and a Redis-stream worker for vote processing. The README documents these capabilities; some wiring and handler internals were not sampled, so uncertain relationships are omitted.

Main entry points: [`internal/api/handlers.go`](https://github.com/waldirborbajr/govote/blob/main/internal/api/handlers.go) (Voting JSON API), [`internal/server/router.go`](https://github.com/waldirborbajr/govote/blob/main/internal/server/router.go) (HTTP router), [`internal/storage/storage.go`](https://github.com/waldirborbajr/govote/blob/main/internal/storage/storage.go) (SQLite database), [`internal/api/telegram.go`](https://github.com/waldirborbajr/govote/blob/main/internal/api/telegram.go) (Telegram code API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["HTTP entrypoints"]
  node_router["HTTP router<br/>[router.go]"]
end

subgraph group_voting["Voting workflows"]
  node_json_api["Voting JSON API<br/>[handlers.go]"]
  node_telegram["Telegram code API<br/>[telegram.go]"]
  node_voter_ui["Voter interface<br/>[handlers.go]"]
  node_poll_logic["Poll and vote logic<br/>[poll.go]"]
  node_templates["HTML templates<br/>[page_templ.go]"]
end

subgraph group_admin["Administration"]
  node_admin_handlers["Admin handlers<br/>[handlers.go]"]
end

subgraph group_platform["Shared services"]
  node_security["Passcodes and tokens<br/>[security.go]"]
  node_validation["Input validation<br/>[validate.go]"]
  node_notifications["WhatsApp notices<br/>[notify.go]"]
  node_web_helpers["Web and session helpers<br/>[session.go]"]
  node_models["Domain models<br/>[models.go]"]
end

subgraph group_runtime["Runtime state"]
  node_database[("SQLite database<br/>[storage.go]")]
  node_redis[("Redis cache and stream<br/>[redis.go]")]
  node_vote_worker["Vote worker<br/>[vote_worker.go]"]
end

node_client(("Voter or bot"))
node_operator(("Administrator"))

node_client -->|"sends requests"| node_router
node_operator -->|"manages polls"| node_router
node_router -->|"routes API"| node_json_api
node_router -->|"routes Telegram"| node_telegram
node_router -->|"routes UI"| node_voter_ui
node_router -->|"routes admin"| node_admin_handlers
node_json_api -->|"reads and writes"| node_database
node_json_api -->|"validates votes"| node_poll_logic
node_json_api -->|"caches polls"| node_redis
node_json_api -->|"issues tokens"| node_security
node_json_api -->|"builds passcode link"| node_notifications
node_telegram -->|"stores passcode"| node_database
node_telegram -->|"generates passcode"| node_security
node_telegram -->|"checks request"| node_validation
node_voter_ui -->|"reads voter and poll data"| node_database
node_voter_ui -->|"renders pages"| node_templates
node_voter_ui -->|"checks input"| node_validation
node_admin_handlers -->|"manages accounts"| node_database
node_admin_handlers -->|"authenticates admins"| node_web_helpers
node_admin_handlers -->|"builds login link"| node_notifications
node_poll_logic -->|"records votes and results"| node_database
node_poll_logic -->|"uses poll models"| node_models
node_vote_worker -->|"consumes vote stream"| node_redis
node_vote_worker -->|"records queued vote"| node_poll_logic
node_web_helpers -->|"validates token"| node_security
node_web_helpers -->|"loads admin"| node_database

click node_router "https://github.com/waldirborbajr/govote/blob/main/internal/server/router.go"
click node_json_api "https://github.com/waldirborbajr/govote/blob/main/internal/api/handlers.go"
click node_telegram "https://github.com/waldirborbajr/govote/blob/main/internal/api/telegram.go"
click node_voter_ui "https://github.com/waldirborbajr/govote/blob/main/internal/ui/handlers.go"
click node_admin_handlers "https://github.com/waldirborbajr/govote/blob/main/internal/admin/handlers.go"
click node_poll_logic "https://github.com/waldirborbajr/govote/blob/main/internal/poll/poll.go"
click node_templates "https://github.com/waldirborbajr/govote/blob/main/internal/views/page_templ.go"
click node_database "https://github.com/waldirborbajr/govote/blob/main/internal/storage/storage.go"
click node_redis "https://github.com/waldirborbajr/govote/blob/main/internal/cache/redis.go"
click node_vote_worker "https://github.com/waldirborbajr/govote/blob/main/internal/worker/vote_worker.go"
click node_security "https://github.com/waldirborbajr/govote/blob/main/internal/security/security.go"
click node_validation "https://github.com/waldirborbajr/govote/blob/main/internal/validate/validate.go"
click node_notifications "https://github.com/waldirborbajr/govote/blob/main/internal/notify/notify.go"
click node_web_helpers "https://github.com/waldirborbajr/govote/blob/main/internal/web/session.go"
click node_models "https://github.com/waldirborbajr/govote/blob/main/internal/models/models.go"

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_router toneBlue
class node_json_api,node_telegram,node_voter_ui,node_poll_logic,node_templates toneAmber
class node_admin_handlers toneMint
class node_security,node_validation,node_notifications,node_web_helpers,node_models toneRose
class node_database,node_redis,node_vote_worker,node_client,node_operator toneIndigo
```

## Components

### HTTP entrypoints

- [HTTP router](https://github.com/waldirborbajr/govote/blob/main/internal/server/router.go): `internal/server/router.go`

### Voting workflows

- [Voting JSON API](https://github.com/waldirborbajr/govote/blob/main/internal/api/handlers.go): `internal/api/handlers.go`
- [Telegram code API](https://github.com/waldirborbajr/govote/blob/main/internal/api/telegram.go): `internal/api/telegram.go`
- [Voter interface](https://github.com/waldirborbajr/govote/blob/main/internal/ui/handlers.go): `internal/ui/handlers.go`
- [Poll and vote logic](https://github.com/waldirborbajr/govote/blob/main/internal/poll/poll.go): `internal/poll/poll.go`
- [HTML templates](https://github.com/waldirborbajr/govote/blob/main/internal/views/page_templ.go): `internal/views/page_templ.go`

### Administration

- [Admin handlers](https://github.com/waldirborbajr/govote/blob/main/internal/admin/handlers.go): `internal/admin/handlers.go`

### Shared services

- [Passcodes and tokens](https://github.com/waldirborbajr/govote/blob/main/internal/security/security.go): `internal/security/security.go`
- [Input validation](https://github.com/waldirborbajr/govote/blob/main/internal/validate/validate.go): `internal/validate/validate.go`
- [WhatsApp notices](https://github.com/waldirborbajr/govote/blob/main/internal/notify/notify.go): `internal/notify/notify.go`
- [Web and session helpers](https://github.com/waldirborbajr/govote/blob/main/internal/web/session.go): `internal/web/session.go`
- [Domain models](https://github.com/waldirborbajr/govote/blob/main/internal/models/models.go): `internal/models/models.go`

### Runtime state

- [SQLite database](https://github.com/waldirborbajr/govote/blob/main/internal/storage/storage.go): `internal/storage/storage.go`
- [Redis cache and stream](https://github.com/waldirborbajr/govote/blob/main/internal/cache/redis.go): `internal/cache/redis.go`
- [Vote worker](https://github.com/waldirborbajr/govote/blob/main/internal/worker/vote_worker.go): `internal/worker/vote_worker.go`

### Other components

- **Voter or bot**
- **Administrator**

## Connections

- Voter or bot → HTTP router: sends requests (evidence: `README.md`)
- Administrator → HTTP router: manages polls (evidence: `README.md`)
- HTTP router → Voting JSON API: routes API (evidence: `internal/server/router.go`)
- HTTP router → Telegram code API: routes Telegram (evidence: `internal/api/telegram.go`)
- HTTP router → Voter interface: routes UI (evidence: `internal/server/router.go`)
- HTTP router → Admin handlers: routes admin (evidence: `internal/server/router.go`)
- Voting JSON API → SQLite database: reads and writes (evidence: `internal/api/handlers.go`)
- Voting JSON API → Poll and vote logic: validates votes (evidence: `internal/api/handlers.go`)
- Voting JSON API → Redis cache and stream: caches polls (evidence: `internal/api/handlers.go`)
- Voting JSON API → Passcodes and tokens: issues tokens (evidence: `internal/api/handlers.go`)
- Voting JSON API → WhatsApp notices: builds passcode link (evidence: `internal/api/handlers.go`)
- Telegram code API → SQLite database: stores passcode (evidence: `internal/api/telegram.go`)
- Telegram code API → Passcodes and tokens: generates passcode (evidence: `internal/api/telegram.go`)
- Telegram code API → Input validation: checks request (evidence: `internal/api/telegram.go`)
- Voter interface → SQLite database: reads voter and poll data (evidence: `internal/ui/handlers.go`)
- Voter interface → HTML templates: renders pages (evidence: `internal/ui/handlers.go`)
- Voter interface → Input validation: checks input (evidence: `internal/ui/handlers.go`)
- Admin handlers → SQLite database: manages accounts (evidence: `internal/admin/handlers.go`)
- Admin handlers → Web and session helpers: authenticates admins (evidence: `internal/admin/handlers.go`)
- Admin handlers → WhatsApp notices: builds login link (evidence: `internal/admin/handlers.go`)
- Poll and vote logic → SQLite database: records votes and results (evidence: `internal/poll/poll.go`)
- Poll and vote logic → Domain models: uses poll models (evidence: `internal/poll/poll.go`)
- Vote worker → Redis cache and stream: consumes vote stream (evidence: `internal/worker/vote_worker.go`)
- Vote worker → Poll and vote logic: records queued vote (evidence: `internal/worker/vote_worker.go`)
- Web and session helpers → Passcodes and tokens: validates token (evidence: `internal/web/session.go`)
- Web and session helpers → SQLite database: loads admin (evidence: `internal/web/session.go`)
