Repository map
The repository is one Git project with the web application at the root and the contracts, the SDK, the interoperability suite and these docs in their own folders, each with its own package.json.
Top level
| Path | What it is |
|---|---|
package.json | The web app package: Next.js, React, ethers, the crypto and ZK libraries, and the scripts dev, build, lint, typecheck, test, test:run, test:coverage, test:e2e, interop, sdk:build, sdk:test, import:check, api:key, zk:public |
next.config.ts | Security headers per route and the build directory switch used by the E2E run |
tsconfig.json | Type-checks every *.ts and *.tsx file except blockchain/ and packages/sdk/dist |
eslint.config.mjs | Next.js and TypeScript lint rules |
vitest.config.ts | Unit test settings and coverage thresholds for src/services and src/lib |
playwright.config.ts | The end-to-end harness settings |
example.env | Every environment variable name the app, server and scripts read, with placeholder values |
.github/workflows/ci.yml | The CI pipeline |
README.md, SECURITY.md, CHANGELOG.md | Project readme, disclosure policy, release history |
Web application: src/
| Path | What it is |
|---|---|
src/app/ | Next.js App Router: one folder per route (verify, login, dashboard, records, students, student, wallet, present, access, open, admin, about, legal pages) and api/ for server routes. Page-specific components sit next to their page. See Routes. |
src/app/api/ | Server routes: auth, upload, documents, v1 (verification API), status-lists, ops |
src/app/globals.css | Design tokens (OKLCH colours, radii, shadows, motion) and global styles |
src/components/ui/ | Design-system primitives: Button, Field, Section, Page, Notice, FactList, HashValue, CheckLine, StatusStamp, Seal, EmptyState and others |
src/components/layout/ | Header with role workspaces, footer, wallet chip, network and demo banners, navigation model |
src/components/home/, access/, present/, vc/ | Shared components of the home page, access panels, phone presentation and VC panels |
src/services/ | The service layer: index.ts composes everything; wallet/, contracts/, credentials/ gateways; domain/ services; indexing/ log scans and caches; documents/ key session and gateway fetch; import/ executors; zk/ prover bridge; react/ provider and hooks; testing/ fakes |
src/lib/ | Pure logic shared by browser, server and scripts: hashing, commitments, EIP-712 types, the credential package, document crypto (doc-crypto/), selective disclosure (disclosure/), VC and Open Badges (vc/), compact codes and the phone store (present/), bulk import (import/), ZK helpers (zk/), RPC failover (rpc/), the seal geometry (seal/), the API envelope (api/) |
src/lib/server/ | Server-only helpers: config, sessions, SIWE, rate limits and store, Pinata and pinning, upload checks, the API handler, status lists, the monitor |
src/contracts/ | ABIs and deployment manifests the app bundles: v0.2 ABIs at the top level, v03/ (ABIs, deployment.<chainId>.json, manifest.ts), zk/ (gate ABI and manifest) |
src/workers/ | The access prover Web Worker |
src/types/ | Shared TypeScript types and declarations |
src/compliance/ | A test that checks the data protection assessment (docs/compliance/DPIA.md) keeps its required sections |
Contracts: blockchain/
| Path | What it is |
|---|---|
blockchain/contracts/v03/ | The current registries, CertichainTimelock, VersionAnnouncer, their interfaces, the shared libraries/CredentialTypes.sol, and test mocks |
blockchain/contracts/zk/ | CertichainAccessGate, its interface, and the Semaphore imports |
blockchain/contracts/AcademicRecords.sol and abstract/, libraries/, modules/, interfaces/ | The legacy v0.2 system |
blockchain/scripts/ | Deploy, verify, smoke, handover, timelock proposal and handover, set readiness and activation, governance status and log checks, admission checks, ZK artifact and key checks, gas and network measurement, ABI export. Shared code in scripts/lib/. See Deployment and scripts. |
blockchain/test/ | Hardhat tests: v0.2 suites at the top level, v03/ (with shared behaviours/ and helpers/), invariants/, gas/, zk/, and fixtures/ with vectors shared with the TypeScript code |
blockchain/hardhat.config.ts | Compiler profiles and networks |
blockchain/deployments/ | Deployment records written by the scripts |
blockchain/timelock-files/ | Safe batch files for timelock schedule, execute and cancel operations |
blockchain/gas-snapshot.json | The committed gas snapshot that CI compares against |
Other folders
| Path | What it is |
|---|---|
e2e/ | Playwright: global-setup.ts starts a local chain and deploys contracts; support/ holds the test wallet, accounts, local chain, mock storage and shared steps; journeys/ holds the end-to-end journeys. See End-to-end tests. |
packages/sdk/ | @certichain/sdk, a private, unpublished client for the verification API. See SDK. |
interop/ | Its own package: an independent verifier library checks Certichain exports. See Interop and SDK tests. |
vc/ | JSON-LD contexts, schemas, test vectors and the description of the certichain-eip712-2026 cryptosuite |
public/ | Icons, the web app manifest, the service worker; public/zk/ is filled with circuit files at build time and not committed |
scripts/ | Build-time helpers: zk-public.mjs (circuit files), api-key.mjs (hash an API key), import-check.ts |
docs/ | The engineering handbook: plan, specs, decision log, deviations, runbooks, guides (API, import, mobile, network, onboarding, governance), the whitepaper, release notes. docs/security/ is internal. |
blockchain-docs/ | This documentation site |
Generated and ignored
These are produced locally and not committed: node_modules/ (in each package), .next/ and other Next.js build folders, blockchain/artifacts/, blockchain/cache/, blockchain/typechain-types/, public/zk/, coverage output, Playwright reports, the local manifest src/contracts/v03/deployment.31337.json, and this site's build/ and .docusaurus/.
Where new code goes
| Kind of change | Place |
|---|---|
| A page or page-only component | src/app/<route>/ |
| A shared UI primitive | src/components/ui/ |
| Rules of a feature | A service in src/services/domain/, wired in src/services/index.ts |
| Pure logic or a file format | src/lib/ (with a test next to it) |
| Anything that needs a server secret | src/lib/server/ and a route in src/app/api/ |
| A contract change | A new set in blockchain/contracts/v03/, never an edit to a deployed one; see Contract set upgrade |
| A deployment or governance tool | blockchain/scripts/ with its logic in blockchain/scripts/lib/ |
| A user journey test | e2e/journeys/ |
Source files
package.json,blockchain/package.json,packages/sdk/package.json,interop/package.jsontsconfig.json,.gitignore,blockchain/.gitignore