# daltonic/votee architecture

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

- Interactive diagram: https://gitdiagram.com/daltonic/votee
- Repository: https://github.com/daltonic/votee

## Overview

##### Project type and purpose
- **Type**: Full-stack decentralized application (dApp).
- **Purpose**: Allow users to create polls, register candidates, and vote on the Solana blockchain via a React/Next.js frontend and an on-chain Anchor/Rust program.

##### File structure
- **Top-level directories**
- `src/app` – Next.js 13 “app” directory contains pages (`page.tsx`), layouts, global CSS, and React components.
- `anchor` – Anchor Solana program, migrations, IDL and type-binding generation, tests for the on-chain logic.
- `public`, `screenshots` – static assets.
- **Key patterns**
- **Frontend** follows a component-based React + Redux Toolkit structure, with services (`services/blockchain.service.tsx`) handling RPC calls.
- **Blockchain** uses Anchor: programs in `anchor/programs/votee/src`, migrations in `anchor/migrations`, and IDL/types in `anchor/target`.
- **Config & build files**
- `next.config.mjs`, `tsconfig.json`, Tailwind config, GitHub workflows for CI.
- `.env` for RPC URL and wallet configuration.

##### Extract additional insights from the README
- **Architecture**: Clear split between frontend (Next.js, React, Redux) and on-chain program (Anchor + Rust).
- **Tech stack**:
- Frontend: Next.js, React, Redux, TypeScript, Tailwind CSS.
- Blockchain: Solana Web3.js, @coral-xyz/anchor, Solana Wallet Adapter.
- Wallet: Phantom (via Wallet Adapter).
- **Workflow**:
1. Developer runs `solana-test-validator`.
2. Deploy Anchor program (`anchor/migrations/deploy.ts`).
3. Frontend uses IDL (`anchor/target/idl/votee.json`) & TypeScript bindings (`anchor/target/types/votee.ts`) to interact.

##### Main components and their relationships
a. **User & Wallet**
- User’s browser with Phantom wallet extension.
- Solana Wallet Adapter handles connection and signature requests.
b. **Frontend (Next.js)**
- React UI components (pages, modals)
- Redux store tracks global state (connected wallet, polls, candidates).
- `blockchain.service.tsx` sends transactions and reads chain state via RPC.
- Consumes Anchor IDL & types for type-safe on-chain calls.
c. **Solana Test Validator / Cluster**
- Local RPC node (`NEXT_PUBLIC_RPC_URL=http://127.0.0.1:8899`).
- Provides JSON-RPC and transaction execution.
d. **On-chain Anchor Program**
- Rust code: instructions for `initialize`, `create_poll`, `register_candidate`, `vote`.
- State accounts: Poll, Candidate, Counter, Voter, Registration.
- Anchor framework handles account serialization, security checks.
e. **DevOps / CI**
- GitHub Workflows for testing both frontend and Anchor program.

##### Architectural patterns & principles
- **Separation of Concerns**: UI vs. blockchain logic.
- **Component-based UI**: Reusable React components (Header, CandidateList).
- **State Management**: Redux Toolkit + React Query for caching blockchain reads.
- **Smart-contract interactions** using Anchor IDL and TypeScript bindings.
- **Local development loop**: Anchor migrations → program deployment → frontend testing.

##### Final checklist
[ ] Frontend stack (Next.js, React, Redux, Tailwind)
[ ] Wallet adapter & Phantom wallet
[ ] blockchain.service.tsx + IDL/types integration
[ ] Local Solana RPC/Test Validator
[ ] Anchor program with instructions & state accounts
[ ] Migrations/deploy pipeline

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    subgraph "Client (Frontend)" 
        direction TB
        NextApp["Next.js App\n(src/app)"]:::frontend
        subgraph "Pages & Layout"
            direction TB
            Home["Home Page\npage.tsx"]:::frontend
            CreatePoll["Create Poll Page\ncreate/page.tsx"]:::frontend
            PollDetail["Poll Details Page\npolls/[pollId]/page.tsx"]:::frontend
            Layout["Global Layout\nlayout.tsx"]:::frontend
            GlobalsCSS["Global CSS\nglobals.css"]:::frontend
        end
        subgraph "React UI Components"
            direction TB
            AppWallet["AppWalletProvider"]:::frontend
            Header["Header"]:::frontend
            CandidateList["CandidateList"]:::frontend
            RegCandidate["RegCandidate Modal"]:::frontend
        end
        subgraph "State Management\n(Redux Toolkit)"
            direction TB
            Store["Store Configuration\nstore/index.ts"]:::frontend
            Slices["Global Slices\nglobalSlices.ts"]:::frontend
            Actions["Global Actions\nglobalActions.ts"]:::frontend
            States["Global States\nglobalStates.ts"]:::frontend
        end
        Service["Blockchain Service\nblockchain.service.tsx"]:::frontend
        IDL_TS["IDL & TS Bindings\nvotee.json\nvotee.ts"]:::frontend
    end

    %% External Wallet
    Phantom["Phantom Wallet\n(Extension)"]:::external
    WalletAdapter["Solana Wallet Adapter"]:::external

    %% Blockchain Side
    subgraph "Blockchain & On-chain"
        direction TB
        RPC["Solana RPC Node\n(127.0.0.1:8899)"]:::blockchain
        TestValidator["Test Validator"]:::blockchain
        subgraph "Anchor Program"
            direction TB
            AnchorToml["Anchor.toml"]:::blockchain
            DeployScript["Migrations/Deploy\ndeploy.ts"]:::blockchain
            ProgramEntry["Program Entry\nindex.ts"]:::blockchain
            Exports["Votee Exports\nvotee-exports.ts"]:::blockchain
            subgraph "Program Logic"
                direction TB
                Lib["lib.rs"]:::blockchain
                Init["initialize.rs"]:::blockchain
                CreatePollIns["create_poll.rs"]:::blockchain
                RegCandIns["register_candidate.rs"]:::blockchain
                VoteIns["vote.rs"]:::blockchain
            end
            subgraph "State Accounts"
                direction TB
                PollAcc["Poll Account\npoll.rs"]:::blockchain
                CandAcc["Candidate Account\ncandidate.rs"]:::blockchain
                CounterAcc["Counter Account\ncounter.rs"]:::blockchain
                VoterAcc["Voter Account\nvoter.rs"]:::blockchain
                RegAcc["Registration Acc\nregisterations.rs"]:::blockchain
            end
            subgraph "Errors & Constants"
                direction TB
                Errors["errors.rs"]:::blockchain
                Consts["constants.rs"]:::blockchain
            end
        end
        subgraph "On-chain Tests"
            direction TB
            Tests["votee.spec.ts"]:::blockchain
        end
    end

    %% DevOps / CI
    subgraph "DevOps / CI" 
        direction TB
        CI_Anchor["Test Anchor Workflow"]:::devops
        CI_Web["Test Web Workflow"]:::devops
    end

    %% Connections - Client to Wallet
    NextApp -->|imports| Layout
    NextApp -->|uses| GlobalsCSS
    Layout -->|renders| Header
    Header -->|shows| CandidateList
    Header -->|invokes| RegCandidate
    NextApp -->|wraps| AppWallet
    AppWallet -->|connects| WalletAdapter
    WalletAdapter -->|interacts| Phantom

    %% Client to Blockchain
    Service -->|"RPC Calls"| RPC
    Service -->|"Uses IDL/Types"| IDL_TS

    Phantom -->|"signs transactions"| Service
    RPC -->|"forwards TX"| TestValidator
    TestValidator -->|"executes Program"| ProgramEntry

    %% Frontend builds and deploys
    DeployScript -->|deploys| ProgramEntry
    ProgramEntry -->|loads config| AnchorToml

    %% On-chain interactions
    ProgramEntry -->|calls| Lib
    Lib -->|uses| Init
    Lib -->|uses| CreatePollIns
    Lib -->|uses| RegCandIns
    Lib -->|uses| VoteIns
    Lib -->|manages| PollAcc
    Lib -->|manages| CandAcc
    Lib -->|manages| CounterAcc
    Lib -->|manages| VoterAcc
    Lib -->|manages| RegAcc
    Lib -->|uses| Errors
    Lib -->|uses| Consts

    %% CI connections
    CI_Anchor -->|runs tests| Tests
    CI_Anchor -->|runs deploy| DeployScript
    CI_Web -->|runs tests| NextApp

    %% Click Events
    click NextApp "https://github.com/daltonic/votee/tree/main/src/app"
    click Home "https://github.com/daltonic/votee/blob/main/src/app/page.tsx"
    click CreatePoll "https://github.com/daltonic/votee/blob/main/src/app/create/page.tsx"
    click PollDetail "https://github.com/daltonic/votee/blob/main/src/app/polls/[pollId]/page.tsx"
    click Layout "https://github.com/daltonic/votee/blob/main/src/app/layout.tsx"
    click GlobalsCSS "https://github.com/daltonic/votee/blob/main/src/app/globals.css"
    click AppWallet "https://github.com/daltonic/votee/blob/main/src/app/components/AppWalletProvider.tsx"
    click Header "https://github.com/daltonic/votee/blob/main/src/app/components/Header.tsx"
    click CandidateList "https://github.com/daltonic/votee/blob/main/src/app/components/CandidateList.tsx"
    click RegCandidate "https://github.com/daltonic/votee/blob/main/src/app/components/RegCandidate.tsx"
    click Store "https://github.com/daltonic/votee/blob/main/src/app/store/index.ts"
    click Slices "https://github.com/daltonic/votee/blob/main/src/app/store/globalSlices.ts"
    click Actions "https://github.com/daltonic/votee/blob/main/src/app/store/actions/globalActions.ts"
    click States "https://github.com/daltonic/votee/blob/main/src/app/store/states/globalStates.ts"
    click Service "https://github.com/daltonic/votee/blob/main/src/app/services/blockchain.service.tsx"
    click IDL_TS "https://github.com/daltonic/votee/blob/main/anchor/target/idl/votee.json"
    click IDL_TS "https://github.com/daltonic/votee/blob/main/anchor/target/types/votee.ts"
    click AnchorToml "https://github.com/daltonic/votee/blob/main/anchor/Anchor.toml"
    click DeployScript "https://github.com/daltonic/votee/blob/main/anchor/migrations/deploy.ts"
    click ProgramEntry "https://github.com/daltonic/votee/blob/main/anchor/src/index.ts"
    click Exports "https://github.com/daltonic/votee/blob/main/anchor/src/votee-exports.ts"
    click Lib "https://github.com/daltonic/votee/blob/main/anchor/programs/votee/src/lib.rs"
    click Init "https://github.com/daltonic/votee/blob/main/anchor/programs/votee/src/instructions/initialize.rs"
    click CreatePollIns "https://github.com/daltonic/votee/blob/main/anchor/programs/votee/src/instructions/create_poll.rs"
    click RegCandIns "https://github.com/daltonic/votee/blob/main/anchor/programs/votee/src/instructions/register_candidate.rs"
    click VoteIns "https://github.com/daltonic/votee/blob/main/anchor/programs/votee/src/instructions/vote.rs"
    click PollAcc "https://github.com/daltonic/votee/blob/main/anchor/programs/votee/src/state/poll.rs"
    click CandAcc "https://github.com/daltonic/votee/blob/main/anchor/programs/votee/src/state/candidate.rs"
    click CounterAcc "https://github.com/daltonic/votee/blob/main/anchor/programs/votee/src/state/counter.rs"
    click VoterAcc "https://github.com/daltonic/votee/blob/main/anchor/programs/votee/src/state/voter.rs"
    click RegAcc "https://github.com/daltonic/votee/blob/main/anchor/programs/votee/src/state/registerations.rs"
    click Tests "https://github.com/daltonic/votee/blob/main/anchor/tests/votee.spec.ts"
    click CI_Anchor "https://github.com/daltonic/votee/blob/main/.github/workflows/test-anchor.yml"
    click CI_Web "https://github.com/daltonic/votee/blob/main/.github/workflows/test-web.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6;
    classDef blockchain fill:#DFF2BF,stroke:#4F8A10;
    classDef devops fill:#F0F0F0,stroke:#999999;
    classDef external fill:#FFE4B5,stroke:#D2691E;
```
