# kuronosec/zk-voto-digital architecture

> Architecture diagram of the GitHub repository kuronosec/zk-voto-digital, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kuronosec/zk-voto-digital
- Repository: https://github.com/kuronosec/zk-voto-digital

## Overview

1. **Top-level shape**
   - This repository is a **React + TypeScript single-page application** for “Zero-Knowledge Voto Digital”.
   - It is not just a UI: the app coordinates **wallet connection**, **zero-knowledge credential/proof handling**, and **Polygon smart-contract interactions**.
   - The repo also includes **local file-serving**, **Docker/Compose**, and **Kubernetes manifests** for deployment.

2. **Primary user-facing flows**
   - The app is organized around pages such as **HomePage**, **Vote**, **Results**, **PassportVote**, **VoteValidation**, **RequestFirma**, **AdminGUI**, and **MobileInstructions**.
   - These pages represent different stages of the user journey: onboarding/identity validation, voting, result viewing, and admin/proposal management.
   - Shared UI building blocks live under `src/components` and include header/footer/hero sections plus voting- and credential-specific widgets.

3. **Wallet and identity boundary**
   - Wallet connectivity is encapsulated in `src/context/WalletContext.tsx` and hooks/utilities like `useWalletConnection`, `walletConnection`, and `walletDetection`.
   - This is the main boundary between the browser app and the user’s crypto wallet environment, likely MetaMask-compatible based on the repo docs.
   - Contract addresses are configurable via environment variables, with fallbacks in `src/constants/voteContract.ts` and `src/constants/issuerContract.ts`, which makes the frontend portable across test/prod networks.

4. **Voting smart-contract interaction**
   - Blockchain actions are isolated into hooks such as `CreateProposal`, `castVote`, `getVoteResults`, and `passportVote`.
   - The app appears to support both **proposal administration** and **ballot casting**, with results retrieval as a separate read path.
   - Contract ABI/artifact data is shipped in the frontend bundle, including `src/public/ZKFirmaDigitalVote.json`, while network selection is centralized in `src/constants/networks.ts`.

5. **Zero-knowledge / credential subsystem**
   - The ZK layer is represented by `src/zkproof` artifacts (`credencial.json`, `vkey.json`) and proof verification utilities like `src/utils/verifyProof.ts`.
   - Components such as `CredentialDisplay`, `ValidationStatus`, `ListVerifiableCredentials`, and `VoteOptionsDisplay` indicate that credentials are rendered and validated in the browser before or during voting.
   - The architecture suggests a **client-driven proof workflow** where the frontend consumes circuit artifacts and proof inputs rather than exposing raw identity data.

6. **Firma Digital / passport-style verification flow**
   - The repo includes a dedicated identity-verification path via `PassportVerification`, `PassportCallback`, `passportService.ts`, and `docs/METAMASK_MOBILE_TESTING.md`.
   - This is a separate onboarding/verification boundary from the voting UI: users authenticate with a digital identity credential, then use the resulting verified state to participate in voting.
   - The naming indicates a credential-based, callback-oriented flow rather than a simple username/password login.

7. **Local file-server for proof assets**
   - `src/file-server/index.js` exists specifically because the README says the circuit-specific files are served to the React frontend through an Express server.
   - This creates a clear boundary: the browser app fetches **ZK circuit-related files** from a local HTTP service instead of bundling all proof artifacts directly into the React app.
   - That server is part of the proof/asset delivery path, not the main UI API layer.

8. **Shared utilities and configuration**
   - Common formatting and logic live in `src/utils` (`formatters`, `utils`, `walletConnection`, `walletDetection`), keeping UI components thinner.
   - `src/config.ts`, `src/constants`, and `src/services` concentrate environment-specific behavior and external service integration.
   - The presence of `i18n.tsx`, `src/locales`, and `src/public/locales` shows the UI is bilingual (English/Spanish), which matters for a citizen-facing voting system.

9. **Deployment and runtime boundaries**
   - The repo is prepared for multiple deployment modes: local development, containerized execution, and Kubernetes rollout.
   - `Dockerfile`, `compose/compose.yaml`, and the `kubernetes/*-web.yml` files indicate the frontend can be deployed as a web service behind an ingress.
   - `public/` and `src/public/` contain static assets and app manifest files, reinforcing that the app is delivered as a browser-hosted frontend.

10. **Overall data flow**
   - The core flow is: **user opens the SPA → connects wallet / verifies identity → loads proof/credential artifacts → validates credential or ZK proof → reads proposal data or submits vote transaction → queries results**.
   - Identity and proof validation happen at the edge of the browser, while authoritative voting state lives on Polygon smart contracts.
   - This separation is the central architectural idea: **sensitive identity data stays off-chain, while eligibility and voting actions are anchored on-chain**.

Main entry points: [`src/App.tsx`](https://github.com/kuronosec/zk-voto-digital/blob/main/src/App.tsx) (App), [`src/hooks/castVote.ts`](https://github.com/kuronosec/zk-voto-digital/blob/main/src/hooks/castVote.ts) (Voting Hooks), [`src/components/PassportVerification.tsx`](https://github.com/kuronosec/zk-voto-digital/blob/main/src/components/PassportVerification.tsx) (Passport Flow), [`Dockerfile`](https://github.com/kuronosec/zk-voto-digital/tree/main/Dockerfile) (Deploy Assets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI shell"]
  node_app["App<br/>React SPA shell<br/>[App.tsx]"]
  node_pages_home["Home<br/>landing page<br/>[HomePage.tsx]"]
  node_pages_vote["Vote<br/>ballot page<br/>[Vote.tsx]"]
  node_pages_results["Results<br/>[Results.tsx]"]
  node_pages_passportvote["Passport Vote<br/>verified voting page<br/>[PassportVote.tsx]"]
  node_pages_validation["Validation<br/>eligibility page<br/>[VoteValidation.tsx]"]
  node_pages_requestfirma["Request Firma<br/>issuer page<br/>[RequestFirma.tsx]"]
  node_pages_admingui["Admin GUI<br/>admin page<br/>[AdminGUI.tsx]"]
  node_components_shared["Shared UI<br/>presentation components"]
end

subgraph group_identity["Wallet & identity"]
  node_wallet_context["Wallet Context<br/>wallet boundary<br/>[WalletContext.tsx]"]
  node_wallet_hooks["Wallet Hooks<br/>connection hooks"]
  node_passport_flow["Passport Flow<br/>verification flow"]
  node_zk_verify["ZK Verify<br/>proof validation<br/>[verifyProof.ts]"]
  node_zk_assets[("ZK Artifacts<br/>circuit assets<br/>[credencial.json]")]
  node_service_passport["Passport Service<br/>backend service client<br/>[passportService.ts]"]
end

subgraph group_chain["Voting & chain"]
  node_voting_hooks["Voting Hooks<br/>contract actions<br/>[castVote.ts]"]
  node_contract_config["Contract Config<br/>network constants<br/>[voteContract.ts]"]
  node_contract_artifact[("Vote ABI<br/>contract artifact")]
end

subgraph group_delivery["Delivery & deploy"]
  node_file_server["File Server<br/>asset server<br/>[index.js]"]
  node_config_i18n["Config & i18n<br/>app configuration<br/>[config.ts]"]
  node_deploy_assets["Deploy Assets<br/>static/deploy files"]
end

node_app -->|"routes"| node_pages_home
node_app -->|"routes"| node_pages_vote
node_app -->|"routes"| node_pages_results
node_app -->|"routes"| node_pages_passportvote
node_app -->|"routes"| node_pages_validation
node_app -->|"routes"| node_pages_requestfirma
node_app -->|"routes"| node_pages_admingui
node_app -->|"uses"| node_components_shared
node_app -->|"wraps"| node_wallet_context
node_wallet_context -->|"depends on"| node_wallet_hooks
node_pages_requestfirma -->|"uses"| node_passport_flow
node_pages_passportvote -->|"uses"| node_passport_flow
node_pages_validation -->|"uses"| node_zk_verify
node_zk_verify -->|"consumes"| node_zk_assets
node_pages_vote -->|"uses"| node_voting_hooks
node_pages_results -->|"reads"| node_voting_hooks
node_pages_admingui -->|"uses"| node_voting_hooks
node_voting_hooks -->|"configures"| node_contract_config
node_voting_hooks -->|"calls"| node_contract_artifact
node_passport_flow -->|"integrates"| node_service_passport
node_file_server -->|"serves"| node_zk_assets
node_config_i18n -->|"localizes"| node_components_shared
node_deploy_assets -->|"ships"| node_app
node_deploy_assets -->|"ships"| node_file_server

click node_app "https://github.com/kuronosec/zk-voto-digital/blob/main/src/App.tsx"
click node_pages_home "https://github.com/kuronosec/zk-voto-digital/blob/main/src/pages/HomePage.tsx"
click node_pages_vote "https://github.com/kuronosec/zk-voto-digital/blob/main/src/pages/Vote.tsx"
click node_pages_results "https://github.com/kuronosec/zk-voto-digital/blob/main/src/pages/Results.tsx"
click node_pages_passportvote "https://github.com/kuronosec/zk-voto-digital/blob/main/src/pages/PassportVote.tsx"
click node_pages_validation "https://github.com/kuronosec/zk-voto-digital/blob/main/src/pages/VoteValidation.tsx"
click node_pages_requestfirma "https://github.com/kuronosec/zk-voto-digital/blob/main/src/pages/RequestFirma.tsx"
click node_pages_admingui "https://github.com/kuronosec/zk-voto-digital/blob/main/src/pages/AdminGUI.tsx"
click node_components_shared "https://github.com/kuronosec/zk-voto-digital/tree/main/src/components"
click node_wallet_context "https://github.com/kuronosec/zk-voto-digital/blob/main/src/context/WalletContext.tsx"
click node_wallet_hooks "https://github.com/kuronosec/zk-voto-digital/blob/main/src/hooks/useWalletConnection.ts"
click node_passport_flow "https://github.com/kuronosec/zk-voto-digital/blob/main/src/components/PassportVerification.tsx"
click node_zk_verify "https://github.com/kuronosec/zk-voto-digital/blob/main/src/utils/verifyProof.ts"
click node_zk_assets "https://github.com/kuronosec/zk-voto-digital/blob/main/src/zkproof/credencial.json"
click node_voting_hooks "https://github.com/kuronosec/zk-voto-digital/blob/main/src/hooks/castVote.ts"
click node_contract_config "https://github.com/kuronosec/zk-voto-digital/blob/main/src/constants/voteContract.ts"
click node_contract_artifact "https://github.com/kuronosec/zk-voto-digital/blob/main/src/public/ZKFirmaDigitalVote.json"
click node_service_passport "https://github.com/kuronosec/zk-voto-digital/blob/main/src/services/passportService.ts"
click node_file_server "https://github.com/kuronosec/zk-voto-digital/blob/main/src/file-server/index.js"
click node_config_i18n "https://github.com/kuronosec/zk-voto-digital/blob/main/src/config.ts"
click node_deploy_assets "https://github.com/kuronosec/zk-voto-digital/tree/main/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_pages_home,node_pages_vote,node_pages_results,node_pages_passportvote,node_pages_validation,node_pages_requestfirma,node_pages_admingui,node_components_shared toneBlue
class node_wallet_context,node_wallet_hooks,node_passport_flow,node_zk_verify,node_zk_assets,node_service_passport toneAmber
class node_voting_hooks,node_contract_config,node_contract_artifact toneMint
class node_file_server,node_config_i18n,node_deploy_assets toneRose
```

## Components

### UI shell

React pages, shared components, and presentation concerns.

- [App](https://github.com/kuronosec/zk-voto-digital/blob/main/src/App.tsx): React SPA shell · Root application composition and route-level orchestration. · `src/App.tsx`
- [Home](https://github.com/kuronosec/zk-voto-digital/blob/main/src/pages/HomePage.tsx): landing page · Entry page and onboarding surface. · `src/pages/HomePage.tsx`
- [Vote](https://github.com/kuronosec/zk-voto-digital/blob/main/src/pages/Vote.tsx): ballot page · Main voting flow for selecting and submitting a ballot. · `src/pages/Vote.tsx`
- [Results](https://github.com/kuronosec/zk-voto-digital/blob/main/src/pages/Results.tsx): results page · Vote result viewing and status presentation. · `src/pages/Results.tsx`
- [Passport Vote](https://github.com/kuronosec/zk-voto-digital/blob/main/src/pages/PassportVote.tsx): verified voting page · Voting path gated by passport-style credential verification. · `src/pages/PassportVote.tsx`
- [Validation](https://github.com/kuronosec/zk-voto-digital/blob/main/src/pages/VoteValidation.tsx): eligibility page · Credential and proof validation step before voting. · `src/pages/VoteValidation.tsx`
- [Request Firma](https://github.com/kuronosec/zk-voto-digital/blob/main/src/pages/RequestFirma.tsx): issuer page · Identity or credential request flow for signature-based verification. · `src/pages/RequestFirma.tsx`
- [Admin GUI](https://github.com/kuronosec/zk-voto-digital/blob/main/src/pages/AdminGUI.tsx): admin page · Proposal administration and management interface. · `src/pages/AdminGUI.tsx`
- [Shared UI](https://github.com/kuronosec/zk-voto-digital/tree/main/src/components): presentation components · Header, footer, hero, features, language selector, and voting widgets. · `src/components`

### Wallet & identity

Wallet connectivity, passport verification, and ZK proof handling.

- [Wallet Context](https://github.com/kuronosec/zk-voto-digital/blob/main/src/context/WalletContext.tsx): wallet boundary · Application-level wallet connection state and provider boundary. · `src/context/WalletContext.tsx`
- [Wallet Hooks](https://github.com/kuronosec/zk-voto-digital/blob/main/src/hooks/useWalletConnection.ts): connection hooks · Wallet connection and detection helpers used by the UI. · `src/hooks/useWalletConnection.ts`
- [Passport Flow](https://github.com/kuronosec/zk-voto-digital/blob/main/src/components/PassportVerification.tsx): verification flow · Passport verification, callback handling, and credential-backed onboarding. · `src/components/PassportVerification.tsx`
- [ZK Verify](https://github.com/kuronosec/zk-voto-digital/blob/main/src/utils/verifyProof.ts): proof validation · Browser-side proof verification and credential display logic. · `src/utils/verifyProof.ts`
- [ZK Artifacts](https://github.com/kuronosec/zk-voto-digital/blob/main/src/zkproof/credencial.json): circuit assets · Credential and verification key artifacts consumed by the frontend. · `src/zkproof/credencial.json`
- [Passport Service](https://github.com/kuronosec/zk-voto-digital/blob/main/src/services/passportService.ts): backend service client · Service integration for passport-related verification or callback processing. · `src/services/passportService.ts`

### Voting & chain

Proposal, vote, and results interactions with Polygon contracts.

- [Voting Hooks](https://github.com/kuronosec/zk-voto-digital/blob/main/src/hooks/castVote.ts): contract actions · Proposal creation, voting, result reads, credential fetches, and passport voting. · `src/hooks/castVote.ts`
- [Contract Config](https://github.com/kuronosec/zk-voto-digital/blob/main/src/constants/voteContract.ts): network constants · Contract addresses and network selection for Polygon deployment. · `src/constants/voteContract.ts`
- [Vote ABI](https://github.com/kuronosec/zk-voto-digital/blob/main/src/public/ZKFirmaDigitalVote.json): contract artifact · Smart-contract ABI/artifact bundled with the frontend. · `src/public/ZKFirmaDigitalVote.json`

### Delivery & deploy

Static assets, file serving, and deployment manifests.

- [File Server](https://github.com/kuronosec/zk-voto-digital/blob/main/src/file-server/index.js): asset server · Express server for serving circuit-specific proof files to the browser. · `src/file-server/index.js`
- [Config & i18n](https://github.com/kuronosec/zk-voto-digital/blob/main/src/config.ts): app configuration · Runtime config, multilingual setup, and locale resources. · `src/config.ts`
- [Deploy Assets](https://github.com/kuronosec/zk-voto-digital/tree/main/Dockerfile): static/deploy files · Public assets and deployment manifests for container and Kubernetes rollout. · `Dockerfile`

## Connections

- App → Home: routes · Root app renders the landing page and navigational flow.
- App → Vote: routes · App exposes the main voting page.
- App → Results: routes · App exposes results viewing.
- App → Passport Vote: routes · App exposes the verified voting path.
- App → Validation: routes · App exposes the credential validation step.
- App → Request Firma: routes · App exposes the identity request flow.
- App → Admin GUI: routes · App exposes admin functionality.
- App → Shared UI: uses · Route pages compose shared UI building blocks.
- App → Wallet Context: wraps · App is centered around wallet state and connection lifecycle.
- Wallet Context → Wallet Hooks: depends on · Wallet provider relies on connection and detection helpers.
- Request Firma → Passport Flow: uses · Request/verification page drives the passport onboarding flow.
- Passport Vote → Passport Flow: uses · Verified voting path depends on passport verification state.
- Validation → ZK Verify: uses · Validation page checks proofs and credential status in-browser.
- ZK Verify → ZK Artifacts: consumes · Verifier uses shipped circuit artifacts and proving key material.
- Vote → Voting Hooks: uses · Ballot page submits votes through contract hooks.
- Results → Voting Hooks: reads · Results page queries vote tallies through hooks.
- Admin GUI → Voting Hooks: uses · Admin page creates or manages proposals through contract actions.
- Voting Hooks → Contract Config: configures · Hooks resolve network and contract addresses from constants.
- Voting Hooks → Vote ABI: calls · Hooks interact with the smart-contract ABI/artifact.
- Passport Flow → Passport Service: integrates · Passport verification flow uses a dedicated service boundary.
- File Server → ZK Artifacts: serves · Local file server delivers proof-related files to the browser.
- Config & i18n → Shared UI: localizes · Shared UI is translated and configured through locale resources.
- Deploy Assets → App: ships · Deployment packaging serves the React application as a web app.
- Deploy Assets → File Server: ships · Container and manifest setup can include the proof file server.
