System architecture
The monorepo components responsible for data, evidence, and transactions.
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.mddocs/architecture/06-event-flow.mdapps/api/src/modules/shadow-ledgerpackages/hashing/srcpackages/verifier/src
