How jayranedev/securedid-v4 works
1. Repository shape
This is a monorepo centered on a decentralized identity system. The main runtime surface is a set of independent Next.js apps under apps/, a shared frontend/runtime library under packages/shared, and the on-chain system under blockchain/. There is also a separate legacy-style wallet app in securedid-wallet/ and a standalone design-system / prototype area in SecureDID Design System/.
2. Core trust boundary: Base Sepolia contracts
The blockchain layer is the source of truth for identity state. The system is deployed against Base Sepolia and is built around three contracts: DIDFactory, DIDRegistryV6, and VerificationAccessManager. The frontend apps are thin clients that read/write on-chain state through shared ABIs and wallet-connected RPC calls.
3. Contract responsibilities
DIDFactory creates and tracks institution registries. DIDRegistryV6 holds student identity lifecycle logic: registration, approval thresholds, revocation, and access-related state. VerificationAccessManager manages third-party access requests and approval flows for verification. Deployment scripts and tests in blockchain/scripts and blockchain/test define how these contracts are instantiated and validated.
4. Shared frontend infrastructure
packages/shared contains the reusable cross-app substrate: contract ABIs, chain config, cryptography helpers, wallet providers, and shared UI pieces like ConnectButton, EthereumGuard, and AddressPill. This package is the main coupling point between apps and chain logic, so diagram it as the common integration layer rather than duplicated code in each app.
5. Role-based application suite
The apps/ directory splits the product into role-specific portals:
- Factory: creates institution registries and configures panelists/thresholds.
- Panelist: governance dashboard for approving, revoking, and handling access.
- Student: student identity and credential management.
- University and College: verification portals with slightly different access/auth flows.
- Explorer: search and lookup UI for registries, students, and VC requests.
- Attack Demo: isolated security simulation app for replay, impersonation, revocation, and governance attack scenarios.
6. Primary data flow: registry creation and issuance
The typical lifecycle starts in Factory, where an institution registry is deployed and initialized. Students then register against that registry in Student. Panelist users review pending identities and provide threshold-based governance approval. Once approved, the identity/credential workflow advances to credential storage and verification access management.
7. Credential storage and confidentiality
The README states that verifiable credentials are encrypted and stored through IPFS/Pinata. That makes off-chain storage part of the architecture: the chain holds pointers/state and approval status, while the actual credential payload lives in distributed storage. This is a key boundary for the diagram because the system separates public trust metadata from private credential data.
8. Verification and access flow
University, College, and Explorer consume registry and access-manager state to validate identities and credential permissions. The access manager adds a controlled sharing layer: verification requests, student approval, TTL-style grants, and revocation-aware access checks. In other words, verification is not just read-only lookup; it is mediated by explicit permission state.
9. Authentication and wallet layer
Wallet authentication is handled with RainbowKit, wagmi, and supporting wallet context in packages/shared. This is the user-entry trust boundary for all role apps. The College app additionally advertises SIWE support, so wallet signatures are part of the authentication path, not just transaction signing.
10. App runtime and backend shape
Each production portal is a Next.js 14 app using the App Router, Tailwind, and TypeScript. Several apps expose an internal src/app/api/rpc/route.ts, which suggests a lightweight server-side RPC bridge or proxy layer rather than a separate backend service. There is no large standalone API server in the tree; the architecture is mostly “frontend + minimal app-local API + chain interactions.”
11. Security and simulation boundary
The apps/attack-demo project is intentionally separate from the main user flows. It models hostile scenarios such as replay attacks, identity fraud, impersonation, revoked credential use, and governance takeover. In an architecture diagram, this should be shown as a test/simulation environment that exercises the same trust assumptions as production without being part of the normal issuance path.
12. Design system and prototype assets
SecureDID Design System/ and its ui_kits/ are mostly static HTML/CSS assets used to define and preview the visual language for each persona. They are not a runtime dependency of the blockchain flow, but they explain the consistent multi-app UX surface. The preview/ files are especially useful as design references for architecture documentation.
13. Deployment and operational context
The product is deployed on Vercel as separate app deployments, with environment-driven configuration for contract addresses, Base Sepolia RPC, and IPFS/Pinata credentials. That means each app can be deployed independently, but they all converge on the same chain contracts and shared environment variables.
14. Secondary/legacy surface
securedid-wallet/ is a separate Next.js wallet-focused app using a pages-router structure and its own wagmi setup. It looks like a standalone auxiliary client rather than the main monorepo flow, so it should be drawn as an adjacent consumer of the same identity ecosystem, not as part of the primary issuance pipeline.
Main entry points: shared Shared · contracts DIDRegistryV6 · SecureDID Design System Design System · route.ts App RPC
Components 18
Role apps
Primary Next.js portals for each user role and workflow.
- Factory · Deploys and configures institution registries.
apps/factory - Panelist · Governance dashboard for approvals, revocations, and access actions.
apps/panelist - Student · Student identity and credential management portal.
apps/student - University · University verification portal for registry and identity checks.
apps/university - College · College verification portal with SIWE-style auth flow.
apps/college - Explorer · Lookup UI for registries, students, and verification requests.
apps/explorer - Attack Demo · Security scenario runner for replay, impersonation, revocation, and takeover cases.
apps/attack-demo
Core platform
Shared integration layer and on-chain trust boundary.
- Shared · Common ABIs, chain config, crypto helpers, wallet providers, and UI primitives.
packages/shared - DIDFactory · Creates and tracks institution registries.
blockchain/contracts - DIDRegistryV6 · Student identity lifecycle, approval thresholds, revocation, and access-related state.
blockchain/contracts - Access Manager · Verification requests, approval flow, TTL grants, and revocation-aware access control.
blockchain/contracts - IPFS/Pinata · Encrypted verifiable credential payload storage with on-chain pointers.
- Wallet Stack · RainbowKit, wagmi, and wallet context used as the entry trust boundary.
packages/shared/src/wallet
Adjacent surfaces
Legacy wallet and design/prototype assets.
- Wallet App · Standalone wallet-focused client adjacent to the main product suite.
securedid-wallet - Design System · Static UI kits and previews for the multi-persona visual language.
SecureDID Design System
Build and deploy
Contracts deployment, tests, and app-local runtime bridges.
- App RPC · Lightweight Next.js RPC bridge used by several portals.
apps/college/src/app/api/rpc/route.ts - Deploy Scripts · Factory deployment and registry creation flows for Base Sepolia.
blockchain/scripts - Contract Tests · Validation of DIDFactory and related on-chain behavior.
blockchain/test
Connections 37
- Shared → Factory: ABIs/UI · Provides contract bindings, wallet UI, and shared helpers.
- Shared → Panelist: ABIs/UI · Provides common wallet and contract integration primitives.
- Shared → Student: ABIs/UI · Provides common wallet and contract integration primitives.
- Shared → University: ABIs/UI · Provides common wallet and contract integration primitives.
- Shared → College: ABIs/UI · Provides common wallet and contract integration primitives.
- Shared → Explorer: ABIs/UI · Provides common wallet and contract integration primitives.
- Shared → Attack Demo: shared utils · Reuses some shared runtime and environment conventions.
- Wallet Stack → Shared: auth layer · Backs wallet connection and signing flows across apps.
- Factory → App RPC: server bridge · Uses app-local RPC for read/write coordination.
- Panelist → App RPC: server bridge · Uses app-local RPC for read/write coordination.
- Student → App RPC: server bridge · Uses app-local RPC for read/write coordination.
- University → App RPC: server bridge · Uses app-local RPC for read/write coordination.
- College → App RPC: server bridge · Uses app-local RPC for read/write coordination.
- Explorer → App RPC: server bridge · Uses app-local RPC for read/write coordination.
- Factory → DIDFactory: deploy/create · Creates and initializes institution registries.
- Panelist → DIDRegistryV6: govern · Approves, revokes, and manages registry state.
- Student → DIDRegistryV6: register · Registers identities against an institution registry.
- University → DIDRegistryV6: verify · Reads registry state for identity validation.
- College → DIDRegistryV6: verify · Reads registry state for identity validation.
- Explorer → DIDRegistryV6: lookup · Searches registry and student identity state.
- Explorer → Access Manager: lookup · Surfaces verification request and permission state.
- Panelist → Access Manager: approve access · Handles access requests and approval flows.
- Student → Access Manager: grant/revoke · Controls access grants and revocations for credentials.
- University → Access Manager: check access · Validates mediated verification permissions.
- College → Access Manager: check access · Validates mediated verification permissions.
- DIDRegistryV6 → IPFS/Pinata: credential pointer · On-chain state references encrypted off-chain credential payloads.
- Deploy Scripts → DIDFactory: deploys · Instantiates the on-chain factory on Base Sepolia.
- Deploy Scripts → DIDRegistryV6: installs · Supports registry deployment and setup.
- Contract Tests → DIDFactory: validates · Exercises factory behavior and registry creation flows.
- Design System → Factory: UI reference · Defines persona-specific visuals for the factory experience.
- Design System → Panelist: UI reference · Defines persona-specific visuals for the panelist experience.
- Design System → Student: UI reference · Defines persona-specific visuals for the student experience.
- Design System → University: UI reference · Defines persona-specific visuals for the university experience.
- Design System → College: UI reference · Defines persona-specific visuals for the college experience.
- Design System → Explorer: UI reference · Defines persona-specific visuals for the explorer experience.
- Wallet App → Wallet Stack: wallet flow · Uses a separate Next.js wallet-focused setup with its own wagmi configuration.
- Wallet App → Shared: adjacent integration · Consumes the same broader identity ecosystem.