# kiesraad/abacus architecture

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

- Interactive diagram: https://gitdiagram.com/kiesraad/abacus
- Repository: https://github.com/kiesraad/abacus

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        Browser["Browser / React SPA"]:::frontend
        subgraph "Frontend App"
            direction TB
            ApiClient["ApiClient"]:::frontend
            ApiProvider["ApiProvider"]:::frontend
            useApiClient["useApiClient Hook"]:::frontend
            subgraph "Feature Modules"
                direction TB
                DataEntryFE["Data Entry"]:::frontend
                ApportionmentFE["Apportionment"]:::frontend
                ElectionManagementFE["Election Management"]:::frontend
                ElectionOverviewFE["Election Overview"]:::frontend
                ElectionStatusFE["Election Status"]:::frontend
                LogsFE["Logs"]:::frontend
            end
            Components["UI Components Library"]:::frontend
            Routes["Routes & Layouts"]:::frontend
            subgraph "Codegen"
                direction TB
                OpenAPISpecFE["openapi.json"]:::ext
                GenTS["TS Types Generator"]:::frontend
            end
        end
    end

    %% Backend Layer
    subgraph "Backend"
        direction TB
        subgraph "CLI Tools"
            direction TB
            AbacusBin["abacus (main server)"]:::backend
            GenOpenAPIBin["gen-openapi"]:::backend
            GenTestElectionBin["gen-test-election"]:::backend
        end
        subgraph "HTTP API Layer"
            direction TB
            AuthAPI["Authentication API"]:::backend
            ElectionAPI["Election API"]:::backend
            DataEntryAPI["Data Entry API"]:::backend
            ApportionmentAPI["Apportionment API"]:::backend
            AuditLogAPI["Audit Log API"]:::backend
            CommitteeSessionAPI["Committee Session API"]:::backend
            ReportingAPI["Reporting API"]:::backend
            DocumentAPI["Document API"]:::backend
            Middleware["Auth & Airgap Middleware"]:::backend
        end
        subgraph "Domain Services"
            direction TB
            AuthService["Authentication Service"]:::backend
            ElectionService["Election Service"]:::backend
            DataEntryService["Data Entry Service"]:::backend
            ApportionmentService["Apportionment Service"]:::backend
            AuditLogService["AuditLog Service"]:::backend
            CommitteeSessionService["CommitteeSession Service"]:::backend
            ReportingService["Reporting Service"]:::backend
        end
        subgraph "Persistence & DB"
            direction TB
            SQLxMigrations["Migrations"]:::backend
            SQLxCache[".sqlx Query Cache"]:::backend
            Fixtures["Fixtures"]:::backend
            DB["Database"]:::db
        end
        subgraph "Utilities"
            direction TB
            PDFGen["PDF Generation"]:::backend
            Templates["TeX Templates"]:::backend
            EMLParser["EML Parser"]:::backend
            Airgap["Airgap Detection"]:::backend
            ZIPMod["ZIP Creation"]:::backend
        end
    end

    %% CI/CD & Docker
    subgraph "CI/CD & Infra"
        direction TB
        Dockerfile["Dockerfile & docker-compose"]:::ext
        CICD["GitHub Actions"]:::ext
    end

    %% Connections
    Browser -->|"HTTPS"| ApiClient
    ApiClient -->|"provides client"| ApiProvider
    ApiProvider -->|"hook"| useApiClient
    useApiClient --> DataEntryFE
    useApiClient --> ApportionmentFE
    useApiClient --> ElectionManagementFE
    useApiClient --> ElectionOverviewFE
    useApiClient --> ElectionStatusFE
    useApiClient --> LogsFE
    Browser -->|"renders UI"| Components
    Browser -->|"routes"| Routes

    GenOpenAPIBin -->|"codegen"| OpenAPISpecFE
    OpenAPISpecFE -->|"drives"| GenTS
    GenTS --> ApiClient

    Browser -->|"HTTP"| AuthAPI
    Browser --> AuthAPI

    %% HTTP → Services → DB
    AuthAPI -->|"calls"| AuthService
    ElectionAPI --> ElectionService
    DataEntryAPI --> DataEntryService
    ApportionmentAPI --> ApportionmentService
    AuditLogAPI --> AuditLogService
    CommitteeSessionAPI --> CommitteeSessionService
    ReportingAPI --> ReportingService
    DocumentAPI --> ReportingService

    AuthService -->|"SQL"| SQLxMigrations
    ElectionService --> SQLxMigrations
    DataEntryService --> SQLxMigrations
    ApportionmentService --> SQLxMigrations
    AuditLogService --> SQLxMigrations
    CommitteeSessionService --> SQLxMigrations
    ReportingService --> SQLxMigrations
    SQLxMigrations --> DB
    SQLxCache --> DB
    Fixtures --> DB

    %% Utilities usage
    ReportingService --> PDFGen
    PDFGen --> Templates
    DataEntryService --> EMLParser
    EMLParser --> Airgap
    ReportingService --> ZIPMod

    %% CI/CD & Docker
    Dockerfile --> AbacusBin
    Dockerfile --> GenTS
    CICD --> Dockerfile
    CICD --> GenOpenAPIBin

    %% Click Events Frontend
    click Browser "https://github.com/kiesraad/abacus/tree/main/frontend/"
    click ApiClient "https://github.com/kiesraad/abacus/blob/main/frontend/src/api/ApiClient.ts"
    click ApiProvider "https://github.com/kiesraad/abacus/blob/main/frontend/src/api/ApiProvider.tsx"
    click useApiClient "https://github.com/kiesraad/abacus/blob/main/frontend/src/api/useApiClient.ts"
    click DataEntryFE "https://github.com/kiesraad/abacus/tree/main/frontend/src/features/data_entry/"
    click ApportionmentFE "https://github.com/kiesraad/abacus/tree/main/frontend/src/features/apportionment/"
    click ElectionManagementFE "https://github.com/kiesraad/abacus/tree/main/frontend/src/features/election_management/"
    click ElectionOverviewFE "https://github.com/kiesraad/abacus/tree/main/frontend/src/features/election_overview/"
    click ElectionStatusFE "https://github.com/kiesraad/abacus/tree/main/frontend/src/features/election_status/"
    click LogsFE "https://github.com/kiesraad/abacus/tree/main/frontend/src/features/logs/"
    click Components "https://github.com/kiesraad/abacus/tree/main/frontend/src/components/"
    click Routes "https://github.com/kiesraad/abacus/blob/main/frontend/src/app/routes.tsx"
    click Routes "https://github.com/kiesraad/abacus/blob/main/frontend/src/app/RootLayout.tsx"
    click GenTS "https://github.com/kiesraad/abacus/blob/main/frontend/scripts/gen_openapi.ts"
    click OpenAPISpecFE "https://github.com/kiesraad/abacus/tree/main/frontend/scripts/openapi/"
    click GenTS "https://github.com/kiesraad/abacus/blob/main/frontend/src/types/generated/openapi.ts"

    %% Click Events Backend
    click AbacusBin "https://github.com/kiesraad/abacus/blob/main/backend/src/bin/abacus.rs"
    click GenOpenAPIBin "https://github.com/kiesraad/abacus/blob/main/backend/src/bin/gen-openapi.rs"
    click GenTestElectionBin "https://github.com/kiesraad/abacus/blob/main/backend/src/bin/gen-test-election.rs"
    click AuthAPI "https://github.com/kiesraad/abacus/blob/main/backend/src/authentication/api.rs"
    click ElectionAPI "https://github.com/kiesraad/abacus/blob/main/backend/src/election/api.rs"
    click DataEntryAPI "https://github.com/kiesraad/abacus/blob/main/backend/src/data_entry/api.rs"
    click ApportionmentAPI "https://github.com/kiesraad/abacus/blob/main/backend/src/apportionment/api.rs"
    click AuditLogAPI "https://github.com/kiesraad/abacus/blob/main/backend/src/audit_log/api.rs"
    click CommitteeSessionAPI "https://github.com/kiesraad/abacus/blob/main/backend/src/committee_session/api.rs"
    click ReportingAPI "https://github.com/kiesraad/abacus/blob/main/backend/src/report/api.rs"
    click DocumentAPI "https://github.com/kiesraad/abacus/blob/main/backend/src/document/api.rs"
    click Middleware "https://github.com/kiesraad/abacus/blob/main/backend/src/authentication/middleware.rs"
    click EMLParser "https://github.com/kiesraad/abacus/tree/main/backend/src/eml/"
    click Airgap "https://github.com/kiesraad/abacus/tree/main/backend/src/airgap/"
    click AuditLogService "https://github.com/kiesraad/abacus/blob/main/backend/src/audit_log/service.rs"
    click ElectionService "https://github.com/kiesraad/abacus/blob/main/backend/src/election/repository.rs"
    click DataEntryService "https://github.com/kiesraad/abacus/blob/main/backend/src/data_entry/repository.rs"
    click CommitteeSessionService "https://github.com/kiesraad/abacus/blob/main/backend/src/committee_session/repository.rs"
    click PDFGen "https://github.com/kiesraad/abacus/tree/main/backend/src/pdf_gen/"
    click Templates "https://github.com/kiesraad/abacus/tree/main/backend/templates/"
    click ZIPMod "https://github.com/kiesraad/abacus/blob/main/backend/src/zip/mod.rs"
    click SQLxMigrations "https://github.com/kiesraad/abacus/tree/main/backend/migrations/"
    click SQLxCache "https://github.com/kiesraad/abacus/tree/main/backend/.sqlx/"
    click Fixtures "https://github.com/kiesraad/abacus/tree/main/backend/fixtures/"
    click DB "https://github.com/kiesraad/abacus/tree/main/backend/"
    click Dockerfile "https://github.com/kiesraad/abacus/blob/main/docker-compose.yml"
    click CICD "https://github.com/kiesraad/abacus/blob/main/.github/workflows/build-lint-test.yml"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#0288D1,stroke-width:1px
    classDef backend fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px
    classDef db fill:#FFF3E0,stroke:#FB8C00,stroke-width:1px
    classDef ext fill:#ECEFF1,stroke:#607D8B,stroke-width:1px
```
