# fernandobono/example-voting-app architecture

> Architecture diagram of the GitHub repository fernandobono/example-voting-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fernandobono/example-voting-app
- Repository: https://github.com/fernandobono/example-voting-app

## Overview

##### Main Components
a. Vote Frontend
- A web app written in Python (Flask) under vote/app.py or optionally ASP.NET Core under vote/dotnet.
- Exposes an HTTP endpoint (port 5000) for users to cast votes.
b. Message Queue
- Redis (Linux) or NATS (Windows) container collects VoteCastEvent messages.
- Acts as a pub/sub broker between vote frontend and worker.
c. Worker(s)
- One or more background services consuming messages:
- .NET Core worker (worker/dotnet) or Java worker (worker/src/main/java).
- Reads VoteCastEvent from queue, persists to database.
d. Database
- PostgreSQL (Linux) or TiDB (Windows) container.
- Stores vote records.
e. Result Service
- Node.js web app (result/server.js) or ASP.NET Core SignalR app (result/dotnet).
- Subscribes to changes or polls DB, broadcasts real-time results to browser clients on port 5001 via WebSockets/SignalR.
f. Optional Support Services
- seed-data generator (seed-data folder) for demo vote data.
- healthchecks scripts for container health.
g. Orchestration Layers
- Docker Compose files (docker-compose.yml variants)
- Docker Swarm stack files (docker-stack.yml)
- Kubernetes YAML under k8s-specifications

##### Relationships & Data Flows
1. User → Vote Frontend (HTTP POST vote)
2. Vote Frontend → Message Queue (publish VoteCastEvent)
3. Worker → subscribes to Queue → Worker processes event → Worker → Database (INSERT vote)
4. Result Service → reads from Database (or subscribes to Worker via queue) → broadcasts updates → Browser Result UI (WebSocket/SignalR)
5. (Optional) seed-data → Message Queue → Worker → Database

##### Architectural Patterns & Principles
- Event-driven microservices: loose coupling via queue.
- CQRS-style separation: writes handled by vote+worker, reads by result service.
- Polyglot services: Python, .NET, Java, Node.js.
- Containerized deployment: Docker Compose, Swarm, Kubernetes.
- Real-time updates via WebSockets / SignalR.

##### Call Out Key Technologies & Frameworks
- Vote Frontend: Flask (Python) or ASP.NET Core MVC/Razor Pages
- Queue: Redis Pub/Sub or NATS
- Worker: .NET Core Generic Host or Java (Maven)
- DB: Postgres or TiDB
- Result UI: Node.js + socket.io or ASP.NET Core SignalR
- Orchestration: Docker Compose / Docker Swarm / Kubernetes

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Users/Browsers
    User((User)):::external
    BrowserResult((Browser)):::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        VoteFrontendFlask["Vote Frontend<br/>Flask (5000)"]:::frontend
        VoteFrontendDotnet["Vote Frontend<br/>ASP.NET Core (5000)"]:::frontend
    end

    %% Messaging Layer
    subgraph "Messaging Layer"
        direction TB
        MessageQueue["Message Queue<br/>Redis/NATS"]:::queue
    end

    %% Processing Layer
    subgraph "Processing Layer"
        direction TB
        WorkerJava["Worker Java"]:::processing
        WorkerDotnet["Worker .NET"]:::processing
        SeedData["Seed Data Generator"]:::processing
    end

    %% Storage Layer
    subgraph "Storage Layer"
        direction TB
        Database["Database<br/>PostgreSQL/TiDB"]:::database
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        ResultNode["Result Service<br/>Node.js/socket.io (5001)"]:::result
        ResultDotnet["Result Service<br/>ASP.NET Core SignalR (5001)"]:::result
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        DockerCompose["Docker Compose"]:::orchestration
        DockerSwarm["Docker Swarm"]:::orchestration
        Kubernetes["Kubernetes"]:::orchestration
    end

    %% Data Flows
    User -->|HTTP POST Vote| VoteFrontendFlask
    User -->|HTTP POST Vote| VoteFrontendDotnet

    VoteFrontendFlask -->|Publish VoteCastEvent| MessageQueue
    VoteFrontendDotnet -->|Publish VoteCastEvent| MessageQueue
    SeedData -->|Publish VoteCastEvent| MessageQueue

    MessageQueue -->|Subscribe VoteCastEvent| WorkerJava
    MessageQueue -->|Subscribe VoteCastEvent| WorkerDotnet

    WorkerJava -->|Insert Vote| Database
    WorkerDotnet -->|Insert Vote| Database

    Database -->|Query/Poll| ResultNode
    Database -->|Query/Poll| ResultDotnet

    ResultNode -->|Broadcast Results| BrowserResult
    ResultDotnet -->|Broadcast Results| BrowserResult

    %% Orchestration Connections
    DockerCompose --- VoteFrontendFlask
    DockerCompose --- WorkerJava
    DockerCompose --- Database
    DockerCompose --- ResultNode
    DockerCompose --- MessageQueue

    DockerSwarm --- VoteFrontendFlask
    DockerSwarm --- WorkerDotnet
    DockerSwarm --- Database
    DockerSwarm --- ResultDotnet
    DockerSwarm --- MessageQueue

    Kubernetes --- VoteFrontendFlask
    Kubernetes --- WorkerJava
    Kubernetes --- Database
    Kubernetes --- ResultNode
    Kubernetes --- MessageQueue

    %% Click Events
    click VoteFrontendFlask "https://github.com/fernandobono/example-voting-app/blob/master/vote/app.py"
    click VoteFrontendDotnet "https://github.com/fernandobono/example-voting-app/tree/master/vote/dotnet/"
    click MessageQueue "https://github.com/fernandobono/example-voting-app/blob/master/healthchecks/redis.sh"
    click WorkerJava "https://github.com/fernandobono/example-voting-app/blob/master/worker/src/main/java/worker/Worker.java"
    click WorkerDotnet "https://github.com/fernandobono/example-voting-app/blob/master/worker/dotnet/Worker/Workers/QueueWorker.cs"
    click Database "https://github.com/fernandobono/example-voting-app/blob/master/k8s-specifications/db-deployment.yaml"
    click ResultNode "https://github.com/fernandobono/example-voting-app/blob/master/result/server.js"
    click ResultDotnet "https://github.com/fernandobono/example-voting-app/blob/master/result/dotnet/Result/Hubs/ResultsHub.cs"
    click SeedData "https://github.com/fernandobono/example-voting-app/blob/master/seed-data/make-data.py"
    click DockerCompose "https://github.com/fernandobono/example-voting-app/blob/master/docker-compose.yml"

    %% Styles
    classDef frontend fill:#d0e7ff,stroke:#333,stroke-width:1px
    classDef queue fill:#ffe8b0,stroke:#333,stroke-width:1px
    classDef processing fill:#d0ffd8,stroke:#333,stroke-width:1px
    classDef database fill:#fff5b0,stroke:#333,stroke-width:1px
    classDef result fill:#ecd0ff,stroke:#333,stroke-width:1px
    classDef external fill:#ffffff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef orchestration fill:#f0f0f0,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
