# beatrizlaranjinha/kaonashi architecture

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

- Interactive diagram: https://gitdiagram.com/beatrizlaranjinha/kaonashi
- Repository: https://github.com/beatrizlaranjinha/kaonashi

## Overview

Kaonashi is an encrypted, decade-based movie voting system. Voters select a movie in the frontend, which forms an encrypted one-hot vote and zero-knowledge proofs, then submits it through the API to the Solana program. The program validates voter eligibility and proofs and updates encrypted tallies; the chairperson manages ballots and election state. Results are decrypted off-chain and a winner is recorded on-chain. The graph includes documented capabilities whose detailed implementation was not sampled; those links are limited to the documented integration points.

Main entry points: [`kaonashi_frontend/src/api/client.rs`](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi_frontend/src/api/client.rs) (API client), [`kaonashi-api/src/handler.rs`](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-api/src/handler.rs) (Election handlers), [`kaonashi-smart-contract/programs/projeto-kaonashi/src/lib.rs`](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-smart-contract/programs/projeto-kaonashi/src/lib.rs) (Election instructions), [`kaonashi_frontend/src/app.rs`](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi_frontend/src/app.rs) (App and navigation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Voting frontend"]
  node_app["App and navigation<br/>[app.rs]"]
  node_vote_ui["Movie ballot<br/>[vote.rs]"]
  node_admin_ui["Election controls<br/>[chairperson.rs]"]
  node_results_ui["Results and ties<br/>[results.rs]"]
  node_api_client["API client<br/>[client.rs]"]
end

subgraph group_api["API coordination"]
  node_api_server["HTTP routes<br/>[main.rs]"]
  node_api_handlers["Election handlers<br/>[handler.rs]"]
  node_auth["Authentication checks<br/>[auth.rs]"]
  node_vote_state[("Vote and receipt state<br/>[keeping_votes.rs]")]
  node_blockchain_client["Chain operations<br/>[blockchain.rs]"]
end

subgraph group_crypto["Vote cryptography"]
  node_vote_crypto["Vote encryption<br/>[vote_crypto.rs]"]
  node_zk_proofs["Vote proofs<br/>[zk_vote.rs]"]
  node_wallet_sign["Wallet signatures"]
end

subgraph group_program["Solana election program"]
  node_program["Election instructions<br/>[lib.rs]"]
  node_program_crypto["Ciphertext validation<br/>[crypto.rs]"]
  node_program_proofs["Proof verification<br/>[proofs.rs]"]
  node_program_rollups["Rollup accounting<br/>[rollups.rs]"]
  node_election_state[("Ballots and voters<br/>[election.rs]")]
end

subgraph group_offchain["Off-chain processing"]
  node_batching["Vote batching<br/>[batches.rs]"]
  node_merkle["Merkle receipts<br/>[merkle.rs]"]
  node_zk_client["Off-chain crypto and rollups<br/>[crypto.rs]"]
  node_zk_solana_client["Program client<br/>[solana_client.rs]"]
end

node_voter(("Voter"))
node_chairperson(("Chairperson"))
node_solana[("Solana validator")]

node_voter -->|"uses"| node_app
node_chairperson -->|"uses"| node_app
node_app -->|"opens ballot"| node_vote_ui
node_app -->|"opens controls"| node_admin_ui
node_app -->|"opens results"| node_results_ui
node_vote_ui -->|"submits vote"| node_api_client
node_api_client -->|"encrypts selection"| node_vote_crypto
node_api_client -->|"generates proofs"| node_zk_proofs
node_api_client -->|"signs requests"| node_wallet_sign
node_api_client -->|"calls routes"| node_api_server
node_admin_ui -->|"requests election actions"| node_api_client
node_results_ui -->|"requests results"| node_api_client
node_api_server -->|"dispatches requests"| node_api_handlers
node_api_handlers -->|"checks signatures"| node_auth
node_api_handlers -->|"stores receipts"| node_vote_state
node_api_handlers -->|"manages batches"| node_batching
node_api_handlers -->|"requests chain operations"| node_blockchain_client
node_blockchain_client -->|"reads and writes"| node_solana
node_blockchain_client -->|"invokes instructions"| node_program
node_program -->|"validates ciphertexts"| node_program_crypto
node_program -->|"verifies proofs"| node_program_proofs
node_program -->|"updates rollups"| node_program_rollups
node_program -->|"updates election state"| node_election_state
node_batching -->|"builds proofs"| node_merkle
node_batching -.->|"prepares rollups"| node_zk_client
node_zk_client -.->|"submits rollups"| node_zk_solana_client
node_zk_solana_client -.->|"reads and writes"| node_solana

click node_app "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi_frontend/src/app.rs"
click node_vote_ui "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi_frontend/src/pages/vote.rs"
click node_admin_ui "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi_frontend/src/pages/chairperson.rs"
click node_results_ui "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi_frontend/src/pages/results.rs"
click node_api_client "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi_frontend/src/api/client.rs"
click node_vote_crypto "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi_frontend/src/crypto/vote_crypto.rs"
click node_zk_proofs "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi_frontend/src/crypto/zk_vote.rs"
click node_wallet_sign "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi_frontend/src/crypto/wallet_signature.rs"
click node_api_server "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-api/src/bin/main.rs"
click node_api_handlers "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-api/src/handler.rs"
click node_auth "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-api/src/auth.rs"
click node_vote_state "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-api/src/keeping_votes.rs"
click node_blockchain_client "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-api/src/blockchain.rs"
click node_program "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-smart-contract/programs/projeto-kaonashi/src/lib.rs"
click node_program_crypto "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-smart-contract/programs/projeto-kaonashi/src/crypto.rs"
click node_program_proofs "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-smart-contract/programs/projeto-kaonashi/src/proofs.rs"
click node_program_rollups "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-smart-contract/programs/projeto-kaonashi/src/rollups.rs"
click node_election_state "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-smart-contract/programs/projeto-kaonashi/src/election.rs"
click node_batching "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-api/src/batches.rs"
click node_merkle "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-api/src/merkle.rs"
click node_zk_client "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-smart-contract/zk-client/src/crypto.rs"
click node_zk_solana_client "https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-smart-contract/zk-client/src/solana_client.rs"

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_vote_ui,node_admin_ui,node_results_ui,node_api_client toneBlue
class node_api_server,node_api_handlers,node_auth,node_vote_state,node_blockchain_client,node_solana toneAmber
class node_vote_crypto,node_zk_proofs,node_wallet_sign toneMint
class node_program,node_program_crypto,node_program_proofs,node_program_rollups,node_election_state toneRose
class node_batching,node_merkle,node_zk_client,node_zk_solana_client,node_voter,node_chairperson toneIndigo
```

## Components

### Voting frontend

- [App and navigation](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi_frontend/src/app.rs): `kaonashi_frontend/src/app.rs`
- [Movie ballot](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi_frontend/src/pages/vote.rs): `kaonashi_frontend/src/pages/vote.rs`
- [Election controls](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi_frontend/src/pages/chairperson.rs): `kaonashi_frontend/src/pages/chairperson.rs`
- [Results and ties](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi_frontend/src/pages/results.rs): `kaonashi_frontend/src/pages/results.rs`
- [API client](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi_frontend/src/api/client.rs): `kaonashi_frontend/src/api/client.rs`

### API coordination

- [HTTP routes](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-api/src/bin/main.rs): `kaonashi-api/src/bin/main.rs`
- [Election handlers](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-api/src/handler.rs): `kaonashi-api/src/handler.rs`
- [Authentication checks](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-api/src/auth.rs): `kaonashi-api/src/auth.rs`
- [Vote and receipt state](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-api/src/keeping_votes.rs): `kaonashi-api/src/keeping_votes.rs`
- [Chain operations](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-api/src/blockchain.rs): `kaonashi-api/src/blockchain.rs`

### Vote cryptography

- [Vote encryption](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi_frontend/src/crypto/vote_crypto.rs): `kaonashi_frontend/src/crypto/vote_crypto.rs`
- [Vote proofs](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi_frontend/src/crypto/zk_vote.rs): `kaonashi_frontend/src/crypto/zk_vote.rs`
- [Wallet signatures](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi_frontend/src/crypto/wallet_signature.rs): `kaonashi_frontend/src/crypto/wallet_signature.rs`

### Solana election program

- [Election instructions](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-smart-contract/programs/projeto-kaonashi/src/lib.rs): `kaonashi-smart-contract/programs/projeto-kaonashi/src/lib.rs`
- [Ciphertext validation](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-smart-contract/programs/projeto-kaonashi/src/crypto.rs): `kaonashi-smart-contract/programs/projeto-kaonashi/src/crypto.rs`
- [Proof verification](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-smart-contract/programs/projeto-kaonashi/src/proofs.rs): `kaonashi-smart-contract/programs/projeto-kaonashi/src/proofs.rs`
- [Rollup accounting](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-smart-contract/programs/projeto-kaonashi/src/rollups.rs): `kaonashi-smart-contract/programs/projeto-kaonashi/src/rollups.rs`
- [Ballots and voters](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-smart-contract/programs/projeto-kaonashi/src/election.rs): `kaonashi-smart-contract/programs/projeto-kaonashi/src/election.rs`

### Off-chain processing

- [Vote batching](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-api/src/batches.rs): `kaonashi-api/src/batches.rs`
- [Merkle receipts](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-api/src/merkle.rs): `kaonashi-api/src/merkle.rs`
- [Off-chain crypto and rollups](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-smart-contract/zk-client/src/crypto.rs): `kaonashi-smart-contract/zk-client/src/crypto.rs`
- [Program client](https://github.com/beatrizlaranjinha/kaonashi/blob/main/kaonashi-smart-contract/zk-client/src/solana_client.rs): `kaonashi-smart-contract/zk-client/src/solana_client.rs`

### Other components

- **Voter**
- **Chairperson**
- **Solana validator**

## Connections

- Voter → App and navigation: uses
- Chairperson → App and navigation: uses
- App and navigation → Movie ballot: opens ballot
- App and navigation → Election controls: opens controls
- App and navigation → Results and ties: opens results
- Movie ballot → API client: submits vote
- API client → Vote encryption: encrypts selection
- API client → Vote proofs: generates proofs
- API client → Wallet signatures: signs requests
- API client → HTTP routes: calls routes
- Election controls → API client: requests election actions
- Results and ties → API client: requests results
- HTTP routes → Election handlers: dispatches requests
- Election handlers → Authentication checks: checks signatures
- Election handlers → Vote and receipt state: stores receipts
- Election handlers → Vote batching: manages batches
- Election handlers → Chain operations: requests chain operations
- Chain operations → Solana validator: reads and writes
- Chain operations → Election instructions: invokes instructions
- Election instructions → Ciphertext validation: validates ciphertexts
- Election instructions → Proof verification: verifies proofs
- Election instructions → Rollup accounting: updates rollups
- Election instructions → Ballots and voters: updates election state
- Vote batching → Merkle receipts: builds proofs
- Vote batching → Off-chain crypto and rollups: prepares rollups
- Off-chain crypto and rollups → Program client: submits rollups
- Program client → Solana validator: reads and writes