# open-source-nep/openelectionnepal architecture

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

- Interactive diagram: https://gitdiagram.com/open-source-nep/openelectionnepal
- Repository: https://github.com/open-source-nep/openelectionnepal

## Overview

##### Project type and purpose
- OpenElection is a distributed, blockchain-inspired, election software suite.
- It uses .NET 7 (Central “master” service, Booth voting nodes, future Assigner), Angular (voting UI & results portal), Akka.NET (actor messaging), and PostgreSQL.

##### File structure
- Top-level solution “OpenElection.sln” contains:
- OpenElection.Central – core election coordinator (console/worker)
- OpenElection.Central.Domain & .Infrastructure – domain entities, repositories, EF migrations, Postgres context
- OpenElection.Booth – web API for casting votes and maintaining local blockchain ledger
- OpenElection.Portal – backend stub (stub console host? minimal) for portal service
- OpenElection.Microservice – Akka.NET message definitions and actor base classes
- openelection.booth.web – Angular UI for booths
- openelection.portal.web – Angular UI for public results portal
- kube/ YAML manifests for Kubernetes deployment

##### README for additional insights
- Four major apps: Central, Booth, Portal, Assigner (future)
- Execution order: PostgreSQL → Central → Booth (multi-instances) → Angular UIs
- Central assigns blockchain hashes, Booth nodes capture and locally store votes, Portal displays final tally & ledger download

##### Main components & interactions
a. Components:
- PostgreSQL Database (Central.Infrastructure/AppDbContext)
- Central Service cluster
- Akka.NET actors: BoothCoordinatorActor, VoteActor
- ElectionService, VoteService (domain)
- Exposes gRPC/HTTP API for vote submissions
- Booth Service cluster (one per physical booth)
- Exposes HTTP API (VoteController) to Angular booth UI
- Maintains local ledger (in-memory or file-based blockchain)
- Sends VoteRequestMessage → Central via Akka.NET remoting
- Angular Booth UI (openelection.booth.web)
- HTTP → Booth Service VoteController
- Angular Portal UI (openelection.portal.web)
- HTTP → Portal/backend stub → reads from Central’s DB (or exposes own API)
- Akka.NET remoting bus (TCP) connecting Central ↔ Booth (microservice folder defines messages)

b. Relationships & flows:
1. Voter (browser) → HTTP POST to Booth UI → HTTP POST to Booth Service
2. Booth Service → VoteRequestMessage → Central Service (Akka.NET remote)
3. Central Service processes request → writes hash & metadata to PostgreSQL
4. Central replies via VoteResponseMessage → Booth maintains local ledger
5. After election, Portal UI requests results → Backend reads from PostgreSQL → Angular displays & allows ledger download

c. Architectural patterns & principles:
- Microservice-style separation: Central vs. Booth vs. Portal
- Actor model (Akka.NET) for distributed messaging and fault tolerance
- Repository pattern (EF Core) in Central.Infrastructure
- Domain-Driven Design: Central.Domain separate from Infrastructure
- Angular client-server separation for UI

d. Key technologies/frameworks:
- .NET 7 Web API & Generic Host
- Akka.NET (HOCON configs: akka.hocon files)
- EF Core Migrations & PostgreSQL
- Angular CLI (Typescript SPAs)
- Kubernetes YAML for container orchestration

##### Diagramming recommendations
- Use rectangles for services (Central Service, Booth Service, Database, UIs).
- Browser → UI → Service → Actor Bus → Central → DB
- Central → Actor Bus → Booth → UI acknowledgment
- Portal UI → Portal Service → DB
- Blue for front-end (Angular UIs)
- Green for services (.NET hosts)
- Orange for messaging components (Akka.NET)
- Gray for persistent storage (PostgreSQL)

##### Essential detail checklist
- Separate each component: Booth UI, Booth Service, Central Service, Portal UI, Database
- Actor model boundary (Akka.NET)
- Multiplicity for booth instances and Central (single or multiple)
- EF Core migration step for Central’s DB schema initialization

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["Voter Browser"]:::external

    subgraph "Frontend Layer"
        BoothUI["Booth UI (Angular)"]:::frontend
        PortalUI["Portal UI (Angular)"]:::frontend
    end

    Browser -->|HTTP POST Vote| BoothUI
    BoothUI -->|HTTP POST Vote| BoothService

    subgraph "Booth Service (.NET 7)" 
        BoothService["Booth Service"]:::service
        BoothServiceConfig(["appsettings.json\nakka.hocon"]):::note
    end

    BoothService -->|VoteRequestMessage| AkkaBus
    AkkaBus["Akka.NET Remoting"]:::message
    AkkaBus -->|VoteRequestMessage| CentralService

    subgraph "Central Service Cluster (.NET 7)"
        CentralService["Central Service"]:::service
        CentralConfig(["appsettings.json\nakka.hocon"]):::note

        subgraph "Actors (Akka.NET)"
            BoothCoordinatorActor["BoothCoordinatorActor"]:::service
            VoteActor["VoteActor"]:::service
        end

        subgraph "Domain Layer"
            Domain["OpenElection.Central.Domain"]:::service
        end

        subgraph "Infrastructure Layer"
            Infrastructure["OpenElection.Central.Infrastructure"]:::service
        end
    end

    CentralService -->|Write hash & metadata| PostgresDB
    PostgresDB["PostgreSQL Database"]:::storage
    Infrastructure -->|EF Migrations| PostgresDB

    CentralService -->|VoteResponseMessage| AkkaBus
    AkkaBus -->|VoteResponseMessage| BoothService

    PortalUI -->|HTTP GET Results| PortalService
    PortalService["Portal Service Stub"]:::service
    PortalService -->|Query DB| PostgresDB

    KubeManifests["Kubernetes Manifests"]:::service

    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef service fill:#d4edda,stroke:#155724,color:#155724;
    classDef message fill:#fff3cd,stroke:#856404,color:#856404,stroke-dasharray: 5 5;
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef note fill:#f1f1f1,stroke:#cccccc,color:#333333,stroke-dasharray: 2 2;

    click BoothUI "https://github.com/open-source-nep/openelectionnepal/tree/main/openelection.booth.web/"
    click PortalUI "https://github.com/open-source-nep/openelectionnepal/tree/main/openelection.portal.web/"
    click BoothService "https://github.com/open-source-nep/openelectionnepal/blob/main/OpenElection.Booth/Program.cs"
    click BoothService "https://github.com/open-source-nep/openelectionnepal/blob/main/OpenElection.Booth/Controllers/VoteController.cs"
    click BoothService "https://github.com/open-source-nep/openelectionnepal/blob/main/OpenElection.Booth/ApiModels/VoteRequestApiModel.cs"
    click BoothService "https://github.com/open-source-nep/openelectionnepal/blob/main/OpenElection.Booth/appsettings.json"
    click BoothService "https://github.com/open-source-nep/openelectionnepal/blob/main/OpenElection.Booth/akka.hocon"
    click CentralService "https://github.com/open-source-nep/openelectionnepal/blob/main/OpenElection.Central/Program.cs"
    click CentralService "https://github.com/open-source-nep/openelectionnepal/blob/main/OpenElection.Central/Worker.cs"
    click CentralService "https://github.com/open-source-nep/openelectionnepal/blob/main/OpenElection.Central/appsettings.json"
    click CentralService "https://github.com/open-source-nep/openelectionnepal/blob/main/OpenElection.Central/akka.hocon"
    click BoothCoordinatorActor "https://github.com/open-source-nep/openelectionnepal/blob/main/OpenElection.Central/Actors/BoothCoordinatorActor.cs"
    click VoteActor "https://github.com/open-source-nep/openelectionnepal/blob/main/OpenElection.Central/Actors/VoteActor.cs"
    click Domain "https://github.com/open-source-nep/openelectionnepal/tree/main/OpenElection.Central.Domain/"
    click Infrastructure "https://github.com/open-source-nep/openelectionnepal/tree/main/OpenElection.Central.Infrastructure/"
    click PostgresDB "https://github.com/open-source-nep/openelectionnepal/blob/main/OpenElection.Central.Infrastructure/AppDbContext.cs"
    click PostgresDB "https://github.com/open-source-nep/openelectionnepal/tree/main/OpenElection.Central.Infrastructure/Migrations/"
    click AkkaBus "https://github.com/open-source-nep/openelectionnepal/tree/main/OpenElection.Microservice/Messages/"
    click AkkaBus "https://github.com/open-source-nep/openelectionnepal/blob/main/OpenElection.Microservice/ReceiveActorBase.cs"
    click PortalService "https://github.com/open-source-nep/openelectionnepal/blob/main/OpenElection.Portal/Program.cs"
    click PortalService "https://github.com/open-source-nep/openelectionnepal/blob/main/OpenElection.Portal/appsettings.json"
    click KubeManifests "https://github.com/open-source-nep/openelectionnepal/blob/main/kube/portal.deployment.yaml"
```
