How kiesraad/abacus works
Project type and purpose
• This is a full-stack, stand-alone election results calculator (“Abacus”) consisting of:
• A Rust-based backend binary exposing a REST/OpenAPI HTTP API, performing authentication, data entry, tallying, seat apportionment, PDF generation, EML import/export and ZIP download.
• A TypeScript/React SPA frontend, served locally, consuming that API.
• A relational database (via SQLx and migrations) to persist elections, users, sessions, audit logs, polling-station data, etc.
High-level file-structure analysis
• Top‐level “backend/” and “frontend/” folders indicate the two main components.
• Backend uses Cargo, SQLx, .env, migrations, bin entrypoints, OpenAPI generator, and a template‐based PDF/TeX engine under templates/.
• Frontend is a Vite/React app with API client code under src/api/, feature modules under src/features/, component library, styles, testing harnesses (Vitest, Playwright).
• CI/CD (GitHub Actions), Docker, docker-compose, lefthook and scripts for codegen (OpenAPI, PO files, translations).
Key README insights
• The backend is a single executable serving HTTP over a local network.
• The frontend is a browser-based React app.
• The system is designed for local, offline use alongside paper ballots.
• Security: four-eyes principle, signed files, audit trail.
• External formats: EML (election-markup), PDF reports, ZIP bundles.
Main components
a. Frontend (Browser/React SPA)
• Routes & UI components
• ApiClient layer
• State & feature modules (data entry, apportionment, reports)
b. Backend (Rust HTTP server)
• HTTP API (OpenAPI endpoints)
• Authentication & session middleware
• Service layers: Election, DataEntry, Apportionment, AuditLog, CommitteeSession, Investigations, Reporting
• PDF generation (TeX templates + XeTeX)
• EML import/export (XML parser modules)
• ZIP creation
c. Database
• Tables: elections, polling_stations, users, sessions, audit_log, results, etc.
• SQLx migrations & query cache
d. CLI tools (bins)
• abacus (main server)
• gen-openapi (produces openapi.json)
• gen-test-election (fixture generator)
e. External assets/formats
• EML files (imported via airgap)
• PDF templates & fonts
• ZIP archives for download
Relationships & interactions
• Browser ↔ (HTTPS) → Backend API
• Backend API → Database (via SQLx)
• Backend Service layers invoke PDF generator, XML parser, ZIP module
• CLI gen-openapi reads server routes → openapi.json → drives frontend ApiClient codegen
• GitHub Actions/Docker build the backend binary and frontend bundles, then compose via docker-compose
Architectural patterns & design principles
• Layered architecture (API controllers → service modules → repository/SQLx → DB)
• Domain-driven modularization in backend (src/{authentication,election,data_entry,...})
• Feature-based modules in frontend (src/features/{...}) with React Context for state
• OpenAPI-first contract between backend and frontend
• Four-eyes audit logging, EML airgap enforcement middleware
• Template-driven PDF generation
Detail
• Major backend domains (authentication, election, data_entry, apportionment, audit_log, reporting).
• Migrations folder feeding into the DB schema.
• Template engine reading from templates/ and producing PDFs.
• Frontend’s feature modules and the shared ApiProvider context.