How open-source-nep/openelectionnepal works
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