# jaikanth-r/verifiable-state-layer architecture

> Architecture diagram of the GitHub repository jaikanth-r/verifiable-state-layer, 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/jaikanth-r/verifiable-state-layer
- Repository: https://github.com/jaikanth-r/verifiable-state-layer

## Overview

VSL is an integrity layer for versioned application state: users create records and evidence events, the API derives chained state hashes and persists them, batches evidence into Merkle commitments, anchors roots to Fabric, and supports later independent verification and audit. The graph also preserves the Overview, tenant/role access, and participant capabilities documented by the README. Arrows use sampled source references or README statements; some unsampled route-to-service details are omitted rather than inferred.

Main entry points: [`apps/api/src/server.ts`](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/api/src/server.ts) (Fastify API), [`apps/api/src/config/database.ts`](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/api/src/config/database.ts) (PostgreSQL), [`apps/web/src/main.tsx`](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/web/src/main.tsx) (Web app), [`apps/web/src/api.ts`](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/web/src/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web workspaces"]
  node_webapp["Web app<br/>[main.tsx]"]
  node_records["Records workspace<br/>[RecordsView.tsx]"]
  node_overview["Overview workspace<br/>[DashboardView.tsx]"]
  node_verifyview["Verify workspace<br/>[VerifyView.tsx]"]
  node_auditview["Audit workspace<br/>[AuditView.tsx]"]
  node_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and access"]
  node_api["Fastify API<br/>[server.ts]"]
  node_resources["Resource management"]
  node_access["Tenant access<br/>[authorization.ts]"]
  node_participants["Resource participants"]
  node_auth["Authentication"]
  node_audit["Audit querying"]
end

subgraph group_integrity["Evidence integrity"]
  node_evidence["Evidence service"]
  node_coreevent["Evidence creation<br/>[evidence.ts]"]
  node_crypto["Canonical hashing<br/>[hash.ts]"]
  node_repository["Evidence repository"]
end

subgraph group_state["Persistence"]
  node_db[("PostgreSQL<br/>[database.ts]")]
end

subgraph group_ledger["Anchoring and verification"]
  node_batch["Merkle batching<br/>[batch-service.ts]"]
  node_merkle["Merkle tree and proofs<br/>[merkle.ts]"]
  node_verification["Independent verification<br/>[merkle-verifier.ts]"]
  node_fabricadapter["Fabric adapter"]
end

node_user(("User"))
node_fabric{{"Hyperledger Fabric"}}
node_oidc{{"OIDC provider"}}

node_user -->|"uses"| node_webapp
node_webapp -->|"renders"| node_records
node_webapp -->|"renders"| node_overview
node_webapp -->|"renders"| node_verifyview
node_webapp -->|"renders"| node_auditview
node_records -->|"requests"| node_client
node_overview -->|"requests"| node_client
node_verifyview -->|"requests"| node_client
node_auditview -->|"requests"| node_client
node_client -->|"HTTP requests"| node_api
node_api -->|"routes"| node_resources
node_api -->|"routes"| node_evidence
node_api -->|"routes"| node_participants
node_api -->|"routes"| node_audit
node_api -->|"checks readiness"| node_db
node_evidence -->|"persists events"| node_db
node_evidence -->|"creates event"| node_coreevent
node_evidence -->|"protects evidence"| node_batch
node_coreevent -->|"hashes state"| node_crypto
node_batch -->|"reads and writes batches"| node_db
node_batch -->|"builds commitment"| node_merkle
node_batch -->|"submits root"| node_fabricadapter
node_fabricadapter -->|"anchors root"| node_fabric
node_verification -->|"checks proofs"| node_merkle
node_verification -->|"checks hashes"| node_crypto
node_audit -->|"queries events"| node_db
node_participants -->|"reads and writes"| node_db
node_resources -.->|"enforces access"| node_access
node_api -.->|"authenticates requests"| node_auth
node_auth -.->|"validates tokens"| node_oidc
node_repository -.->|"stores evidence"| node_db

click node_webapp "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/web/src/main.tsx"
click node_records "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/web/src/views/RecordsView.tsx"
click node_overview "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/web/src/views/DashboardView.tsx"
click node_verifyview "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/web/src/views/VerifyView.tsx"
click node_auditview "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/web/src/views/AuditView.tsx"
click node_client "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/web/src/api.ts"
click node_api "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/api/src/server.ts"
click node_resources "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/api/src/services/resource-service.ts"
click node_access "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/api/src/services/authorization.ts"
click node_participants "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/api/src/services/resource-participant-service.ts"
click node_auth "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/api/src/services/authenticator-factory.ts"
click node_evidence "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/api/src/services/evidence-service.ts"
click node_coreevent "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/packages/vsl-core/src/evidence.ts"
click node_crypto "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/packages/crypto/src/hash.ts"
click node_repository "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/packages/vsl-core/src/repository/evidence-repository.ts"
click node_batch "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/packages/vsl-core/src/anchoring/batch-service.ts"
click node_merkle "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/packages/merkle/src/merkle.ts"
click node_verification "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/packages/vsl-core/src/verification/merkle-verifier.ts"
click node_fabricadapter "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/packages/vsl-core/src/blockchain/fabric-anchor-adapter.ts"
click node_audit "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/api/src/services/audit-query-service.ts"
click node_db "https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/api/src/config/database.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_records,node_overview,node_verifyview,node_auditview,node_client,node_user toneBlue
class node_api,node_resources,node_access,node_participants,node_auth,node_audit toneAmber
class node_evidence,node_coreevent,node_crypto,node_repository toneMint
class node_db toneRose
class node_batch,node_merkle,node_verification,node_fabricadapter,node_fabric,node_oidc toneIndigo
```

## Components

### Web workspaces

- [Web app](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/web/src/main.tsx): `apps/web/src/main.tsx`
- [Records workspace](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/web/src/views/RecordsView.tsx): `apps/web/src/views/RecordsView.tsx`
- [Overview workspace](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/web/src/views/DashboardView.tsx): `apps/web/src/views/DashboardView.tsx`
- [Verify workspace](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/web/src/views/VerifyView.tsx): `apps/web/src/views/VerifyView.tsx`
- [Audit workspace](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/web/src/views/AuditView.tsx): `apps/web/src/views/AuditView.tsx`
- [API client](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/web/src/api.ts): `apps/web/src/api.ts`

### API and access

- [Fastify API](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/api/src/server.ts): `apps/api/src/server.ts`
- [Resource management](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/api/src/services/resource-service.ts): `apps/api/src/services/resource-service.ts`
- [Tenant access](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/api/src/services/authorization.ts): `apps/api/src/services/authorization.ts`
- [Resource participants](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/api/src/services/resource-participant-service.ts): `apps/api/src/services/resource-participant-service.ts`
- [Authentication](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/api/src/services/authenticator-factory.ts): `apps/api/src/services/authenticator-factory.ts`
- [Audit querying](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/api/src/services/audit-query-service.ts): `apps/api/src/services/audit-query-service.ts`

### Evidence integrity

- [Evidence service](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/api/src/services/evidence-service.ts): `apps/api/src/services/evidence-service.ts`
- [Evidence creation](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/packages/vsl-core/src/evidence.ts): `packages/vsl-core/src/evidence.ts`
- [Canonical hashing](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/packages/crypto/src/hash.ts): `packages/crypto/src/hash.ts`
- [Evidence repository](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/packages/vsl-core/src/repository/evidence-repository.ts): `packages/vsl-core/src/repository/evidence-repository.ts`

### Persistence

- [PostgreSQL](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/apps/api/src/config/database.ts): `apps/api/src/config/database.ts`

### Anchoring and verification

- [Merkle batching](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/packages/vsl-core/src/anchoring/batch-service.ts): `packages/vsl-core/src/anchoring/batch-service.ts`
- [Merkle tree and proofs](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/packages/merkle/src/merkle.ts): `packages/merkle/src/merkle.ts`
- [Independent verification](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/packages/vsl-core/src/verification/merkle-verifier.ts): `packages/vsl-core/src/verification/merkle-verifier.ts`
- [Fabric adapter](https://github.com/jaikanth-r/verifiable-state-layer/blob/main/packages/vsl-core/src/blockchain/fabric-anchor-adapter.ts): `packages/vsl-core/src/blockchain/fabric-anchor-adapter.ts`

### Other components

- **User**
- **Hyperledger Fabric**
- **OIDC provider**

## Connections

- User → Web app: uses (evidence: `README.md`)
- Web app → Records workspace: renders (evidence: `apps/web/src/main.tsx`)
- Web app → Overview workspace: renders (evidence: `apps/web/src/main.tsx`)
- Web app → Verify workspace: renders (evidence: `apps/web/src/main.tsx`)
- Web app → Audit workspace: renders (evidence: `apps/web/src/main.tsx`)
- Records workspace → API client: requests (evidence: `apps/web/src/views/RecordsView.tsx`)
- Overview workspace → API client: requests (evidence: `apps/web/src/views/DashboardView.tsx`)
- Verify workspace → API client: requests (evidence: `apps/web/src/views/VerifyView.tsx`)
- Audit workspace → API client: requests (evidence: `apps/web/src/views/AuditView.tsx`)
- API client → Fastify API: HTTP requests (evidence: `README.md`)
- Fastify API → Resource management: routes (evidence: `apps/api/src/server.ts`)
- Fastify API → Evidence service: routes (evidence: `apps/api/src/server.ts`)
- Fastify API → Resource participants: routes (evidence: `apps/api/src/server.ts`)
- Fastify API → Audit querying: routes (evidence: `apps/api/src/server.ts`)
- Fastify API → PostgreSQL: checks readiness (evidence: `apps/api/src/server.ts`)
- Evidence service → PostgreSQL: persists events (evidence: `apps/api/src/services/evidence-service.ts`)
- Evidence service → Evidence creation: creates event (evidence: `apps/api/src/services/evidence-service.ts`)
- Evidence service → Merkle batching: protects evidence (evidence: `apps/api/src/services/evidence-service.ts`)
- Evidence creation → Canonical hashing: hashes state (evidence: `README.md`)
- Merkle batching → PostgreSQL: reads and writes batches (evidence: `packages/vsl-core/src/anchoring/batch-service.ts`)
- Merkle batching → Merkle tree and proofs: builds commitment (evidence: `packages/vsl-core/src/anchoring/batch-service.ts`)
- Merkle batching → Fabric adapter: submits root (evidence: `packages/vsl-core/src/anchoring/batch-service.ts`)
- Fabric adapter → Hyperledger Fabric: anchors root (evidence: `README.md`)
- Independent verification → Merkle tree and proofs: checks proofs (evidence: `packages/vsl-core/src/verification/merkle-verifier.ts`)
- Independent verification → Canonical hashing: checks hashes (evidence: `packages/vsl-core/src/verification/merkle-verifier.ts`)
- Audit querying → PostgreSQL: queries events (evidence: `apps/api/src/services/audit-query-service.ts`)
- Resource participants → PostgreSQL: reads and writes (evidence: `apps/api/src/services/resource-participant-service.ts`)
- Resource management → Tenant access: enforces access
- Fastify API → Authentication: authenticates requests
- Authentication → OIDC provider: validates tokens (evidence: `README.md`)
- Evidence repository → PostgreSQL: stores evidence
