Skip to content
Documentation/Technical reference

System architecture

The monorepo components responsible for data, evidence, and transactions.

On this page

From source to ledger

The issuer dashboard is the operating interface. The NestJS API coordinates ingestion and access; workers handle fetching, verification, relaying, indexing, and monitoring. PostgreSQL stores state and logs; source/documents are encrypted.

packages/hashing defines bytes and hashes. packages/verifier independently reproduces evidence. packages/contracts defines Zod/API contracts; packages/ingest contains pure parsers and mapping, with endpoint availability documented separately.

Consistency during failure

State, audit, and outbox entries are written in the same transaction. Consumers record inbox receipts atomically with their effects so replay does not lose or duplicate work.

Chain writes follow reserve → sign once → persist raw transaction and hash → broadcast → resend the same transaction. Replacements/cancellations keep the nonce; finalized receipts determine the outcome.

Package boundaries

Domain and pure engines do not depend on NestJS or the database. Applications wire adapters to use cases; packages never depend on an application.

Tests and CI use simulated adapters. Deployment and Base Sepolia smoke verification are separate gates; builds and tests do not prove the live environment has the intended configuration.

Sources reviewed in the monorepo

Based on source code; live availability is stated separately.

  • docs/architecture/03-system-architecture.md
  • docs/architecture/06-event-flow.md
  • apps/api/src/modules/shadow-ledger
  • packages/hashing/src
  • packages/verifier/src