# achyutranaut/voltmesh architecture

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

- Interactive diagram: https://gitdiagram.com/achyutranaut/voltmesh
- Repository: https://github.com/achyutranaut/voltmesh

## Overview

VoltMesh is an energy-exchange application spanning a web terminal and services for metering, market clearing, and attestations. The user-facing flow presents meter data, matching, verification, settlement, and certificates through operational views and a staged pipeline; backend components support ingestion, clearing, and epoch construction. The 3D exchange engine is an explanatory interface, not evidence of a live transaction pipeline. Connections reflect imports and calls shown in excerpts or the SOURCE INDEX; unsampled service wiring and external integrations are not inferred.

Main entry points: [`apps/web/src/App.tsx`](https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/App.tsx) (Application shell), [`services/ingest-gateway/src/app.ts`](https://github.com/achyutranaut/voltmesh/blob/main/services/ingest-gateway/src/app.ts) (Attestation endpoint), [`packages/attestation/src/canonical.ts`](https://github.com/achyutranaut/voltmesh/blob/main/packages/attestation/src/canonical.ts) (Attestation primitives), [`packages/types/src/index.ts`](https://github.com/achyutranaut/voltmesh/blob/main/packages/types/src/index.ts) (Shared domain types)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["Application shell<br/>[App.tsx]"]
  node_pipeline["Pipeline state"]
  node_wallet["Wallet context<br/>[WalletContext.tsx]"]
  node_marketview["Market terminal"]
  node_meters["Meter views"]
  node_oracleview["Oracle epochs"]
  node_merkletree["Merkle proofs"]
  node_settlement["Settlement view<br/>[SettlementView.tsx]"]
  node_certificates["Certificates"]
  node_energyengine["Exchange engine"]
  node_scene["3D scene"]
  node_station["Station definitions"]
  node_enginecontrols["Engine controls"]
end

subgraph group_ingest["Meter ingestion"]
  node_ingestapp["Attestation endpoint<br/>[app.ts]"]
  node_validator["Attestation validator<br/>[validator.ts]"]
  node_storage["Reading storage<br/>[storage.ts]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_market["Market services"]
  node_api["Exchange API<br/>[app.ts]"]
  node_matcher["Order matcher<br/>[matcher.ts]"]
  node_epochbuilder["Epoch builder<br/>[builder.ts]"]
end

subgraph group_domain["Domain packages"]
  node_clearing["Clearing logic<br/>[clearing.ts]"]
  node_attestation["Attestation primitives<br/>[canonical.ts]"]
  node_types["Shared domain types<br/>[index.ts]"]
end

subgraph group_simulation["Simulation"]
  node_simulator["Meter simulator<br/>[simulator.ts]"]
end

node_user(("Participant"))

node_user -->|"uses"| node_webapp
node_webapp -->|"uses state"| node_pipeline
node_webapp -->|"uses context"| node_wallet
node_webapp -->|"renders"| node_marketview
node_webapp -->|"renders"| node_meters
node_webapp -->|"renders"| node_oracleview
node_webapp -->|"renders"| node_merkletree
node_webapp -->|"renders"| node_settlement
node_webapp -->|"renders"| node_certificates
node_webapp -->|"renders"| node_energyengine
node_energyengine -->|"initializes"| node_scene
node_scene -->|"uses definitions"| node_station
node_energyengine -->|"renders controls"| node_enginecontrols
node_user -.->|"submits readings"| node_ingestapp
node_ingestapp -->|"validates"| node_validator
node_ingestapp -->|"stores and reads"| node_storage
node_storage -->|"queries"| node_postgres
node_api -->|"calls"| node_clearing
node_api -->|"uses primitives"| node_attestation
node_matcher -->|"uses clearing"| node_clearing
node_epochbuilder -->|"uses primitives"| node_attestation
node_ingestapp -->|"hashes readings"| node_attestation
node_ingestapp -->|"uses types"| node_types
node_api -->|"uses types"| node_types
node_clearing -->|"uses primitives"| node_attestation
node_matcher -->|"uses types"| node_types
node_epochbuilder -->|"uses types"| node_types
node_simulator -->|"uses types"| node_types
node_simulator -->|"uses primitives"| node_attestation
node_webapp -->|"simulates readings"| node_simulator

click node_webapp "https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/App.tsx"
click node_pipeline "https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/context/PipelineContext.tsx"
click node_wallet "https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/context/WalletContext.tsx"
click node_marketview "https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/market/MarketTerminalView.tsx"
click node_meters "https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/energy/EnergyMetersView.tsx"
click node_oracleview "https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/oracle/OracleEpochsView.tsx"
click node_merkletree "https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/oracle/CanonicalMerkleTree.tsx"
click node_settlement "https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/settlement/SettlementView.tsx"
click node_certificates "https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/certificates/CertificatesView.tsx"
click node_energyengine "https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/energy-exchange-engine/EnergyExchangeEngine.tsx"
click node_scene "https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/energy-exchange-engine/EnergyEngineScene.tsx"
click node_station "https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/energy-exchange-engine/EnergyEngineStation.tsx"
click node_enginecontrols "https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/energy-exchange-engine/EnergyEngineControls.tsx"
click node_ingestapp "https://github.com/achyutranaut/voltmesh/blob/main/services/ingest-gateway/src/app.ts"
click node_validator "https://github.com/achyutranaut/voltmesh/blob/main/services/ingest-gateway/src/validator.ts"
click node_storage "https://github.com/achyutranaut/voltmesh/blob/main/services/ingest-gateway/src/storage.ts"
click node_api "https://github.com/achyutranaut/voltmesh/blob/main/services/api/src/app.ts"
click node_matcher "https://github.com/achyutranaut/voltmesh/blob/main/services/matcher/src/matcher.ts"
click node_epochbuilder "https://github.com/achyutranaut/voltmesh/blob/main/services/epoch-builder/src/builder.ts"
click node_clearing "https://github.com/achyutranaut/voltmesh/blob/main/packages/clearing/src/clearing.ts"
click node_attestation "https://github.com/achyutranaut/voltmesh/blob/main/packages/attestation/src/canonical.ts"
click node_types "https://github.com/achyutranaut/voltmesh/blob/main/packages/types/src/index.ts"
click node_simulator "https://github.com/achyutranaut/voltmesh/blob/main/simulators/meter-sim/src/simulator.ts"

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_webapp,node_pipeline,node_wallet,node_marketview,node_meters,node_oracleview,node_merkletree,node_settlement,node_certificates,node_energyengine,node_scene,node_station,node_enginecontrols toneBlue
class node_ingestapp,node_validator,node_storage,node_postgres toneAmber
class node_api,node_matcher,node_epochbuilder toneMint
class node_clearing,node_attestation,node_types toneRose
class node_simulator,node_user toneIndigo
```

## Components

### Web application

- [Application shell](https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Pipeline state](https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/context/PipelineContext.tsx): `apps/web/src/context/PipelineContext.tsx`
- [Wallet context](https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/context/WalletContext.tsx): `apps/web/src/context/WalletContext.tsx`
- [Market terminal](https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/market/MarketTerminalView.tsx): `apps/web/src/components/market/MarketTerminalView.tsx`
- [Meter views](https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/energy/EnergyMetersView.tsx): `apps/web/src/components/energy/EnergyMetersView.tsx`
- [Oracle epochs](https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/oracle/OracleEpochsView.tsx): `apps/web/src/components/oracle/OracleEpochsView.tsx`
- [Merkle proofs](https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/oracle/CanonicalMerkleTree.tsx): `apps/web/src/components/oracle/CanonicalMerkleTree.tsx`
- [Settlement view](https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/settlement/SettlementView.tsx): `apps/web/src/components/settlement/SettlementView.tsx`
- [Certificates](https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/certificates/CertificatesView.tsx): `apps/web/src/components/certificates/CertificatesView.tsx`
- [Exchange engine](https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/energy-exchange-engine/EnergyExchangeEngine.tsx): `apps/web/src/components/energy-exchange-engine/EnergyExchangeEngine.tsx`
- [3D scene](https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/energy-exchange-engine/EnergyEngineScene.tsx): `apps/web/src/components/energy-exchange-engine/EnergyEngineScene.tsx`
- [Station definitions](https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/energy-exchange-engine/EnergyEngineStation.tsx): `apps/web/src/components/energy-exchange-engine/EnergyEngineStation.tsx`
- [Engine controls](https://github.com/achyutranaut/voltmesh/blob/main/apps/web/src/components/energy-exchange-engine/EnergyEngineControls.tsx): `apps/web/src/components/energy-exchange-engine/EnergyEngineControls.tsx`

### Meter ingestion

- [Attestation endpoint](https://github.com/achyutranaut/voltmesh/blob/main/services/ingest-gateway/src/app.ts): `services/ingest-gateway/src/app.ts`
- [Attestation validator](https://github.com/achyutranaut/voltmesh/blob/main/services/ingest-gateway/src/validator.ts): `services/ingest-gateway/src/validator.ts`
- [Reading storage](https://github.com/achyutranaut/voltmesh/blob/main/services/ingest-gateway/src/storage.ts): `services/ingest-gateway/src/storage.ts`
- **PostgreSQL**

### Market services

- [Exchange API](https://github.com/achyutranaut/voltmesh/blob/main/services/api/src/app.ts): `services/api/src/app.ts`
- [Order matcher](https://github.com/achyutranaut/voltmesh/blob/main/services/matcher/src/matcher.ts): `services/matcher/src/matcher.ts`
- [Epoch builder](https://github.com/achyutranaut/voltmesh/blob/main/services/epoch-builder/src/builder.ts): `services/epoch-builder/src/builder.ts`

### Domain packages

- [Clearing logic](https://github.com/achyutranaut/voltmesh/blob/main/packages/clearing/src/clearing.ts): `packages/clearing/src/clearing.ts`
- [Attestation primitives](https://github.com/achyutranaut/voltmesh/blob/main/packages/attestation/src/canonical.ts): `packages/attestation/src/canonical.ts`
- [Shared domain types](https://github.com/achyutranaut/voltmesh/blob/main/packages/types/src/index.ts): `packages/types/src/index.ts`

### Simulation

- [Meter simulator](https://github.com/achyutranaut/voltmesh/blob/main/simulators/meter-sim/src/simulator.ts): `simulators/meter-sim/src/simulator.ts`

### Other components

- **Participant**

## Connections

- Participant → Application shell: uses (evidence: `apps/web/src/App.tsx`)
- Application shell → Pipeline state: uses state (evidence: `apps/web/src/App.tsx`)
- Application shell → Wallet context: uses context (evidence: `apps/web/src/main.tsx`)
- Application shell → Market terminal: renders (evidence: `apps/web/src/App.tsx`)
- Application shell → Meter views: renders (evidence: `apps/web/src/App.tsx`)
- Application shell → Oracle epochs: renders (evidence: `apps/web/src/App.tsx`)
- Application shell → Merkle proofs: renders (evidence: `apps/web/src/App.tsx`)
- Application shell → Settlement view: renders (evidence: `apps/web/src/App.tsx`)
- Application shell → Certificates: renders (evidence: `apps/web/src/App.tsx`)
- Application shell → Exchange engine: renders
- Exchange engine → 3D scene: initializes (evidence: `apps/web/src/components/energy-exchange-engine/EnergyExchangeEngine.tsx`)
- 3D scene → Station definitions: uses definitions (evidence: `apps/web/src/components/energy-exchange-engine/EnergyEngineScene.tsx`)
- Exchange engine → Engine controls: renders controls (evidence: `apps/web/src/components/energy-exchange-engine/EnergyExchangeEngine.tsx`)
- Participant → Attestation endpoint: submits readings
- Attestation endpoint → Attestation validator: validates (evidence: `services/ingest-gateway/src/app.ts`)
- Attestation endpoint → Reading storage: stores and reads (evidence: `services/ingest-gateway/src/app.ts`)
- Reading storage → PostgreSQL: queries (evidence: `services/ingest-gateway/src/storage.ts`)
- Exchange API → Clearing logic: calls (evidence: `services/api/src/app.ts`)
- Exchange API → Attestation primitives: uses primitives (evidence: `services/api/src/app.ts`)
- Order matcher → Clearing logic: uses clearing (evidence: `services/matcher/src/matcher.ts`)
- Epoch builder → Attestation primitives: uses primitives (evidence: `services/epoch-builder/src/builder.ts`)
- Attestation endpoint → Attestation primitives: hashes readings (evidence: `services/ingest-gateway/src/app.ts`)
- Attestation endpoint → Shared domain types: uses types (evidence: `services/ingest-gateway/src/app.ts`)
- Exchange API → Shared domain types: uses types (evidence: `services/api/src/app.ts`)
- Clearing logic → Attestation primitives: uses primitives (evidence: `packages/clearing/src/clearing.ts`)
- Order matcher → Shared domain types: uses types (evidence: `services/matcher/src/matcher.ts`)
- Epoch builder → Shared domain types: uses types (evidence: `services/epoch-builder/src/builder.ts`)
- Meter simulator → Shared domain types: uses types (evidence: `simulators/meter-sim/src/simulator.ts`)
- Meter simulator → Attestation primitives: uses primitives (evidence: `simulators/meter-sim/src/simulator.ts`)
- Application shell → Meter simulator: simulates readings (evidence: `apps/web/src/App.tsx`)
