# boiyee/sunmint architecture

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

- Interactive diagram: https://gitdiagram.com/boiyee/sunmint
- Repository: https://github.com/boiyee/sunmint

## Overview

SUNMINT is a solar-certificate system: simulated or real meters produce signed five-minute readings, the verifier checks readings and hourly claims, and certificates can be matched to company load and retired with receipts. The web app exposes producer, matching, tracing, proof, and attack-demo views. The README documents the contract capabilities, but contract implementation files are not present in the supplied tree; those nodes therefore point only to the enclosing contracts/ directory. Some runtime links not shown in excerpts are marked dashed and unverified.

Main entry points: [`web/src/api.ts`](https://github.com/boiyee/sunmint/blob/main/web/src/api.ts) (API client), [`web/src/main.tsx`](https://github.com/boiyee/sunmint/blob/main/web/src/main.tsx) (Web routes), [`node/verifier/src/api.rs`](https://github.com/boiyee/sunmint/blob/main/node/verifier/src/api.rs) (Verifier HTTP API), [`node/verifier/src/main.rs`](https://github.com/boiyee/sunmint/blob/main/node/verifier/src/main.rs) (Claim processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_meter["Meter Simulation"]
  node_sim["Demo meters<br/>[main.rs]"]
end

subgraph group_verify["Verification Service"]
  node_verifier_api["Verifier HTTP API<br/>[api.rs]"]
  node_verifier_app["Claim processing<br/>[main.rs]"]
  node_attack_engine["Attack scenarios<br/>[attacks.rs]"]
  node_state_store[("Reading &amp; certificate store<br/>[store.rs]")]
  node_chain_adapter["Chain adapter<br/>[chain.rs]"]
end

subgraph group_chain["Certificates &amp; Market"]
  node_cert_contract["Certificate contract"]
  node_market_contract["Market &amp; retirement"]
  node_usd_token["Test USD token"]
end

subgraph group_web["Web Experience"]
  node_web_app["Web routes<br/>[main.tsx]"]
  node_web_api["API client<br/>[api.ts]"]
  node_landing["Landing<br/>[Landing.tsx]"]
  node_daylight["Daylight view<br/>[Daylight.tsx]"]
  node_rooftop["Rooftop view<br/>[Rooftop.tsx]"]
  node_match_view["Load matching<br/>[Match.tsx]"]
  node_trace_view["Certificate trace<br/>[Trace.tsx]"]
  node_proof_view["Proof view<br/>[Proof.tsx]"]
  node_break_view["Break it demo<br/>[BreakIt.tsx]"]
  node_ui["Shared UI<br/>[ui.tsx]"]
end

subgraph group_core["Shared Verification"]
  node_checks["Reading &amp; claim checks<br/>[checks.rs]"]
  node_merkle["Merkle commitments<br/>[merkle.rs]"]
  node_solar["Solar physics<br/>[solar.rs]"]
  node_signed_types["Signed message types<br/>[lib.rs]"]
end

node_meter_actor(("Meter operator"))
node_company(("Company"))

node_meter_actor -->|"simulates readings"| node_sim
node_sim -.->|"submits readings"| node_verifier_api
node_verifier_api -->|"checks readings"| node_checks
node_verifier_api -->|"records results"| node_state_store
node_verifier_api -->|"forwards claims"| node_verifier_app
node_verifier_api -->|"uses attacks"| node_attack_engine
node_verifier_app -->|"checks claims"| node_checks
node_verifier_app -->|"loads readings"| node_state_store
node_verifier_app -->|"records rejection"| node_state_store
node_verifier_app -->|"requests mint"| node_chain_adapter
node_checks -->|"uses tree"| node_merkle
node_checks -->|"checks sun physics"| node_solar
node_checks -->|"validates signatures"| node_signed_types
node_chain_adapter -->|"mints certificates"| node_cert_contract
node_company -->|"uses"| node_web_app
node_web_app -->|"routes to"| node_landing
node_web_app -->|"routes to"| node_daylight
node_web_app -->|"routes to"| node_rooftop
node_web_app -->|"routes to"| node_match_view
node_web_app -->|"routes to"| node_trace_view
node_web_app -->|"routes to"| node_proof_view
node_web_app -->|"routes to"| node_break_view
node_landing -->|"fetches data"| node_web_api
node_daylight -->|"fetches data"| node_web_api
node_rooftop -->|"fetches data"| node_web_api
node_match_view -->|"requests match"| node_web_api
node_trace_view -->|"fetches trace"| node_web_api
node_proof_view -->|"fetches proof"| node_web_api
node_break_view -->|"runs attacks"| node_web_api
node_web_api -.->|"calls HTTP API"| node_verifier_api
node_match_view -->|"matches load"| node_market_contract
node_market_contract -->|"retires certificates"| node_cert_contract
node_market_contract -->|"uses payment token"| node_usd_token
node_company -->|"buys and retires"| node_market_contract
node_web_api -.->|"requests retirement"| node_market_contract
node_ui -->|"loads config"| node_web_api

click node_sim "https://github.com/boiyee/sunmint/blob/main/node/simulator/src/main.rs"
click node_verifier_api "https://github.com/boiyee/sunmint/blob/main/node/verifier/src/api.rs"
click node_verifier_app "https://github.com/boiyee/sunmint/blob/main/node/verifier/src/main.rs"
click node_attack_engine "https://github.com/boiyee/sunmint/blob/main/node/verifier/src/attacks.rs"
click node_state_store "https://github.com/boiyee/sunmint/blob/main/node/verifier/src/store.rs"
click node_chain_adapter "https://github.com/boiyee/sunmint/blob/main/node/verifier/src/chain.rs"
click node_checks "https://github.com/boiyee/sunmint/blob/main/node/core/src/checks.rs"
click node_merkle "https://github.com/boiyee/sunmint/blob/main/node/core/src/merkle.rs"
click node_solar "https://github.com/boiyee/sunmint/blob/main/node/core/src/solar.rs"
click node_signed_types "https://github.com/boiyee/sunmint/blob/main/node/core/src/lib.rs"
click node_cert_contract "https://github.com/boiyee/sunmint/tree/main/contracts"
click node_market_contract "https://github.com/boiyee/sunmint/tree/main/contracts"
click node_usd_token "https://github.com/boiyee/sunmint/tree/main/contracts"
click node_web_app "https://github.com/boiyee/sunmint/blob/main/web/src/main.tsx"
click node_web_api "https://github.com/boiyee/sunmint/blob/main/web/src/api.ts"
click node_landing "https://github.com/boiyee/sunmint/blob/main/web/src/pages/Landing.tsx"
click node_daylight "https://github.com/boiyee/sunmint/blob/main/web/src/pages/Daylight.tsx"
click node_rooftop "https://github.com/boiyee/sunmint/blob/main/web/src/pages/Rooftop.tsx"
click node_match_view "https://github.com/boiyee/sunmint/blob/main/web/src/pages/Match.tsx"
click node_trace_view "https://github.com/boiyee/sunmint/blob/main/web/src/pages/Trace.tsx"
click node_proof_view "https://github.com/boiyee/sunmint/blob/main/web/src/pages/Proof.tsx"
click node_break_view "https://github.com/boiyee/sunmint/blob/main/web/src/pages/BreakIt.tsx"
click node_ui "https://github.com/boiyee/sunmint/blob/main/web/src/ui.tsx"

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_sim toneBlue
class node_verifier_api,node_verifier_app,node_attack_engine,node_state_store,node_chain_adapter toneAmber
class node_cert_contract,node_market_contract,node_usd_token toneMint
class node_web_app,node_web_api,node_landing,node_daylight,node_rooftop,node_match_view,node_trace_view,node_proof_view,node_break_view,node_ui toneRose
class node_checks,node_merkle,node_solar,node_signed_types,node_meter_actor,node_company toneIndigo
```

## Components

### Meter Simulation

- [Demo meters](https://github.com/boiyee/sunmint/blob/main/node/simulator/src/main.rs): `node/simulator/src/main.rs`

### Verification Service

- [Verifier HTTP API](https://github.com/boiyee/sunmint/blob/main/node/verifier/src/api.rs): `node/verifier/src/api.rs`
- [Claim processing](https://github.com/boiyee/sunmint/blob/main/node/verifier/src/main.rs): `node/verifier/src/main.rs`
- [Attack scenarios](https://github.com/boiyee/sunmint/blob/main/node/verifier/src/attacks.rs): `node/verifier/src/attacks.rs`
- [Reading & certificate store](https://github.com/boiyee/sunmint/blob/main/node/verifier/src/store.rs): `node/verifier/src/store.rs`
- [Chain adapter](https://github.com/boiyee/sunmint/blob/main/node/verifier/src/chain.rs): `node/verifier/src/chain.rs`

### Certificates & Market

- [Certificate contract](https://github.com/boiyee/sunmint/tree/main/contracts): `contracts`
- [Market & retirement](https://github.com/boiyee/sunmint/tree/main/contracts): `contracts`
- [Test USD token](https://github.com/boiyee/sunmint/tree/main/contracts): `contracts`

### Web Experience

- [Web routes](https://github.com/boiyee/sunmint/blob/main/web/src/main.tsx): `web/src/main.tsx`
- [API client](https://github.com/boiyee/sunmint/blob/main/web/src/api.ts): `web/src/api.ts`
- [Landing](https://github.com/boiyee/sunmint/blob/main/web/src/pages/Landing.tsx): `web/src/pages/Landing.tsx`
- [Daylight view](https://github.com/boiyee/sunmint/blob/main/web/src/pages/Daylight.tsx): `web/src/pages/Daylight.tsx`
- [Rooftop view](https://github.com/boiyee/sunmint/blob/main/web/src/pages/Rooftop.tsx): `web/src/pages/Rooftop.tsx`
- [Load matching](https://github.com/boiyee/sunmint/blob/main/web/src/pages/Match.tsx): `web/src/pages/Match.tsx`
- [Certificate trace](https://github.com/boiyee/sunmint/blob/main/web/src/pages/Trace.tsx): `web/src/pages/Trace.tsx`
- [Proof view](https://github.com/boiyee/sunmint/blob/main/web/src/pages/Proof.tsx): `web/src/pages/Proof.tsx`
- [Break it demo](https://github.com/boiyee/sunmint/blob/main/web/src/pages/BreakIt.tsx): `web/src/pages/BreakIt.tsx`
- [Shared UI](https://github.com/boiyee/sunmint/blob/main/web/src/ui.tsx): `web/src/ui.tsx`

### Shared Verification

- [Reading & claim checks](https://github.com/boiyee/sunmint/blob/main/node/core/src/checks.rs): `node/core/src/checks.rs`
- [Merkle commitments](https://github.com/boiyee/sunmint/blob/main/node/core/src/merkle.rs): `node/core/src/merkle.rs`
- [Solar physics](https://github.com/boiyee/sunmint/blob/main/node/core/src/solar.rs): `node/core/src/solar.rs`
- [Signed message types](https://github.com/boiyee/sunmint/blob/main/node/core/src/lib.rs): `node/core/src/lib.rs`

### Other components

- **Meter operator**
- **Company**

## Connections

- Meter operator → Demo meters: simulates readings (evidence: `README.md`)
- Demo meters → Verifier HTTP API: submits readings
- Verifier HTTP API → Reading & claim checks: checks readings (evidence: `node/verifier/src/api.rs`)
- Verifier HTTP API → Reading & certificate store: records results (evidence: `node/verifier/src/api.rs`)
- Verifier HTTP API → Claim processing: forwards claims (evidence: `node/verifier/src/api.rs`)
- Verifier HTTP API → Attack scenarios: uses attacks (evidence: `node/verifier/src/api.rs`)
- Claim processing → Reading & claim checks: checks claims (evidence: `node/verifier/src/main.rs`)
- Claim processing → Reading & certificate store: loads readings (evidence: `node/verifier/src/main.rs`)
- Claim processing → Reading & certificate store: records rejection (evidence: `node/verifier/src/main.rs`)
- Claim processing → Chain adapter: requests mint (evidence: `node/verifier/src/main.rs`)
- Reading & claim checks → Merkle commitments: uses tree (evidence: `node/core/src/checks.rs`)
- Reading & claim checks → Solar physics: checks sun physics (evidence: `node/core/src/checks.rs`)
- Reading & claim checks → Signed message types: validates signatures (evidence: `node/core/src/checks.rs`)
- Chain adapter → Certificate contract: mints certificates (evidence: `README.md`)
- Company → Web routes: uses (evidence: `README.md`)
- Web routes → Landing: routes to (evidence: `web/src/main.tsx`)
- Web routes → Daylight view: routes to (evidence: `web/src/main.tsx`)
- Web routes → Rooftop view: routes to (evidence: `web/src/main.tsx`)
- Web routes → Load matching: routes to (evidence: `web/src/main.tsx`)
- Web routes → Certificate trace: routes to (evidence: `web/src/main.tsx`)
- Web routes → Proof view: routes to (evidence: `web/src/main.tsx`)
- Web routes → Break it demo: routes to (evidence: `web/src/main.tsx`)
- Landing → API client: fetches data (evidence: `web/src/pages/Landing.tsx`)
- Daylight view → API client: fetches data (evidence: `web/src/pages/Daylight.tsx`)
- Rooftop view → API client: fetches data (evidence: `web/src/pages/Rooftop.tsx`)
- Load matching → API client: requests match (evidence: `web/src/pages/Match.tsx`)
- Certificate trace → API client: fetches trace (evidence: `web/src/pages/Trace.tsx`)
- Proof view → API client: fetches proof (evidence: `web/src/pages/Proof.tsx`)
- Break it demo → API client: runs attacks (evidence: `web/src/pages/BreakIt.tsx`)
- API client → Verifier HTTP API: calls HTTP API
- Load matching → Market & retirement: matches load (evidence: `README.md`)
- Market & retirement → Certificate contract: retires certificates (evidence: `README.md`)
- Market & retirement → Test USD token: uses payment token (evidence: `README.md`)
- Company → Market & retirement: buys and retires (evidence: `README.md`)
- API client → Market & retirement: requests retirement
- Shared UI → API client: loads config (evidence: `web/src/ui.tsx`)
