How kuronosec/zk-voto-digital works
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: App.tsx App · castVote.ts Voting Hooks · PassportVerification.tsx Passport Flow · Dockerfile Deploy Assets
Components 21
UI shell
React pages, shared components, and presentation concerns.
- App · Root application composition and route-level orchestration.
src/App.tsx - Home · Entry page and onboarding surface.
src/pages/HomePage.tsx - Vote · Main voting flow for selecting and submitting a ballot.
src/pages/Vote.tsx - Results · Vote result viewing and status presentation.
src/pages/Results.tsx - Passport Vote · Voting path gated by passport-style credential verification.
src/pages/PassportVote.tsx - Validation · Credential and proof validation step before voting.
src/pages/VoteValidation.tsx - Request Firma · Identity or credential request flow for signature-based verification.
src/pages/RequestFirma.tsx - Admin GUI · Proposal administration and management interface.
src/pages/AdminGUI.tsx - Shared UI · Header, footer, hero, features, language selector, and voting widgets.
src/components
Wallet & identity
Wallet connectivity, passport verification, and ZK proof handling.
- Wallet Context · Application-level wallet connection state and provider boundary.
src/context/WalletContext.tsx - Wallet Hooks · Wallet connection and detection helpers used by the UI.
src/hooks/useWalletConnection.ts - Passport Flow · Passport verification, callback handling, and credential-backed onboarding.
src/components/PassportVerification.tsx - ZK Verify · Browser-side proof verification and credential display logic.
src/utils/verifyProof.ts - ZK Artifacts · Credential and verification key artifacts consumed by the frontend.
src/zkproof/credencial.json - Passport Service · 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 · Proposal creation, voting, result reads, credential fetches, and passport voting.
src/hooks/castVote.ts - Contract Config · Contract addresses and network selection for Polygon deployment.
src/constants/voteContract.ts - Vote ABI · Smart-contract ABI/artifact bundled with the frontend.
src/public/ZKFirmaDigitalVote.json
Delivery & deploy
Static assets, file serving, and deployment manifests.
- File Server · Express server for serving circuit-specific proof files to the browser.
src/file-server/index.js - Config & i18n · Runtime config, multilingual setup, and locale resources.
src/config.ts - Deploy Assets · Public assets and deployment manifests for container and Kubernetes rollout.
Dockerfile
Connections 24
- 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.