# jayranedev/securedid-v4 architecture

> Architecture diagram of the GitHub repository jayranedev/securedid-v4, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jayranedev/securedid-v4
- Repository: https://github.com/jayranedev/securedid-v4

## Overview

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: [`packages/shared`](https://github.com/jayranedev/securedid-v4/tree/master/packages/shared) (Shared), [`blockchain/contracts`](https://github.com/jayranedev/securedid-v4/tree/master/blockchain/contracts) (DIDRegistryV6), [`SecureDID Design System`](https://github.com/jayranedev/securedid-v4/tree/HEAD/SecureDID%20Design%20System) (Design System), [`apps/college/src/app/api/rpc/route.ts`](https://github.com/jayranedev/securedid-v4/blob/master/apps/college/src/app/api/rpc/route.ts) (App RPC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Role apps"]
  node_factory_app["Factory<br/>Next.js app"]
  node_panelist_app["Panelist<br/>Next.js app"]
  node_student_app["Student<br/>Next.js app"]
  node_university_app["University<br/>Next.js app"]
  node_college_app["College<br/>Next.js app"]
  node_explorer_app["Explorer<br/>Next.js app"]
  node_attack_demo["Attack Demo<br/>simulation app"]
end

subgraph group_core["Core platform"]
  node_shared_pkg["Shared<br/>frontend substrate"]
  node_factory_contract{{"DIDFactory<br/>smart contract"}}
  node_registry_contract{{"DIDRegistryV6<br/>smart contract"}}
  node_access_contract{{"Access Manager<br/>smart contract"}}
  node_ipfs_storage[("IPFS/Pinata<br/>off-chain storage")]
  node_wallet_stack(("Wallet Stack<br/>auth/connectivity"))
end

subgraph group_aux["Adjacent surfaces"]
  node_legacy_wallet["Wallet App<br/>legacy Next.js app"]
  node_design_system["Design System<br/>prototype assets"]
end

subgraph group_ops["Build and deploy"]
  node_rpc_routes["App RPC<br/>app-local API<br/>[route.ts]"]
  node_deploy_scripts["Deploy Scripts<br/>hardhat scripts"]
  node_tests["Contract Tests<br/>hardhat tests"]
end

node_shared_pkg -->|"ABIs/UI"| node_factory_app
node_shared_pkg -->|"ABIs/UI"| node_panelist_app
node_shared_pkg -->|"ABIs/UI"| node_student_app
node_shared_pkg -->|"ABIs/UI"| node_university_app
node_shared_pkg -->|"ABIs/UI"| node_college_app
node_shared_pkg -->|"ABIs/UI"| node_explorer_app
node_shared_pkg -->|"shared utils"| node_attack_demo
node_wallet_stack -->|"auth layer"| node_shared_pkg
node_factory_app -->|"server bridge"| node_rpc_routes
node_panelist_app -->|"server bridge"| node_rpc_routes
node_student_app -->|"server bridge"| node_rpc_routes
node_university_app -->|"server bridge"| node_rpc_routes
node_college_app -->|"server bridge"| node_rpc_routes
node_explorer_app -->|"server bridge"| node_rpc_routes
node_factory_app -->|"deploy/create"| node_factory_contract
node_panelist_app -->|"govern"| node_registry_contract
node_student_app -->|"register"| node_registry_contract
node_university_app -->|"verify"| node_registry_contract
node_college_app -->|"verify"| node_registry_contract
node_explorer_app -->|"lookup"| node_registry_contract
node_explorer_app -->|"lookup"| node_access_contract
node_panelist_app -->|"approve access"| node_access_contract
node_student_app -->|"grant/revoke"| node_access_contract
node_university_app -->|"check access"| node_access_contract
node_college_app -->|"check access"| node_access_contract
node_registry_contract -->|"credential pointer"| node_ipfs_storage
node_deploy_scripts -->|"deploys"| node_factory_contract
node_deploy_scripts -->|"installs"| node_registry_contract
node_tests -->|"validates"| node_factory_contract
node_design_system -.->|"UI reference"| node_factory_app
node_design_system -.->|"UI reference"| node_panelist_app
node_design_system -.->|"UI reference"| node_student_app
node_design_system -.->|"UI reference"| node_university_app
node_design_system -.->|"UI reference"| node_college_app
node_design_system -.->|"UI reference"| node_explorer_app
node_legacy_wallet -->|"wallet flow"| node_wallet_stack
node_legacy_wallet -.->|"adjacent integration"| node_shared_pkg

click node_factory_app "https://github.com/jayranedev/securedid-v4/tree/master/apps/factory"
click node_panelist_app "https://github.com/jayranedev/securedid-v4/tree/master/apps/panelist"
click node_student_app "https://github.com/jayranedev/securedid-v4/tree/master/apps/student"
click node_university_app "https://github.com/jayranedev/securedid-v4/tree/master/apps/university"
click node_college_app "https://github.com/jayranedev/securedid-v4/tree/master/apps/college"
click node_explorer_app "https://github.com/jayranedev/securedid-v4/tree/master/apps/explorer"
click node_attack_demo "https://github.com/jayranedev/securedid-v4/tree/master/apps/attack-demo"
click node_shared_pkg "https://github.com/jayranedev/securedid-v4/tree/master/packages/shared"
click node_factory_contract "https://github.com/jayranedev/securedid-v4/tree/master/blockchain/contracts"
click node_registry_contract "https://github.com/jayranedev/securedid-v4/tree/master/blockchain/contracts"
click node_access_contract "https://github.com/jayranedev/securedid-v4/tree/master/blockchain/contracts"
click node_wallet_stack "https://github.com/jayranedev/securedid-v4/tree/master/packages/shared/src/wallet"
click node_rpc_routes "https://github.com/jayranedev/securedid-v4/blob/master/apps/college/src/app/api/rpc/route.ts"
click node_deploy_scripts "https://github.com/jayranedev/securedid-v4/tree/master/blockchain/scripts"
click node_tests "https://github.com/jayranedev/securedid-v4/tree/master/blockchain/test"
click node_legacy_wallet "https://github.com/jayranedev/securedid-v4/tree/master/securedid-wallet"
click node_design_system "https://github.com/jayranedev/securedid-v4/tree/master/SecureDID Design System"

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_factory_app,node_panelist_app,node_student_app,node_university_app,node_college_app,node_explorer_app,node_attack_demo toneBlue
class node_shared_pkg,node_factory_contract,node_registry_contract,node_access_contract,node_ipfs_storage,node_wallet_stack toneAmber
class node_legacy_wallet,node_design_system toneMint
class node_rpc_routes,node_deploy_scripts,node_tests toneRose
```

## Components

### Role apps

Primary Next.js portals for each user role and workflow.

- [Factory](https://github.com/jayranedev/securedid-v4/tree/master/apps/factory): Next.js app · Deploys and configures institution registries. · `apps/factory`
- [Panelist](https://github.com/jayranedev/securedid-v4/tree/master/apps/panelist): Next.js app · Governance dashboard for approvals, revocations, and access actions. · `apps/panelist`
- [Student](https://github.com/jayranedev/securedid-v4/tree/master/apps/student): Next.js app · Student identity and credential management portal. · `apps/student`
- [University](https://github.com/jayranedev/securedid-v4/tree/master/apps/university): Next.js app · University verification portal for registry and identity checks. · `apps/university`
- [College](https://github.com/jayranedev/securedid-v4/tree/master/apps/college): Next.js app · College verification portal with SIWE-style auth flow. · `apps/college`
- [Explorer](https://github.com/jayranedev/securedid-v4/tree/master/apps/explorer): Next.js app · Lookup UI for registries, students, and verification requests. · `apps/explorer`
- [Attack Demo](https://github.com/jayranedev/securedid-v4/tree/master/apps/attack-demo): simulation app · Security scenario runner for replay, impersonation, revocation, and takeover cases. · `apps/attack-demo`

### Core platform

Shared integration layer and on-chain trust boundary.

- [Shared](https://github.com/jayranedev/securedid-v4/tree/master/packages/shared): frontend substrate · Common ABIs, chain config, crypto helpers, wallet providers, and UI primitives. · `packages/shared`
- [DIDFactory](https://github.com/jayranedev/securedid-v4/tree/master/blockchain/contracts): smart contract · Creates and tracks institution registries. · `blockchain/contracts`
- [DIDRegistryV6](https://github.com/jayranedev/securedid-v4/tree/master/blockchain/contracts): smart contract · Student identity lifecycle, approval thresholds, revocation, and access-related state. · `blockchain/contracts`
- [Access Manager](https://github.com/jayranedev/securedid-v4/tree/master/blockchain/contracts): smart contract · Verification requests, approval flow, TTL grants, and revocation-aware access control. · `blockchain/contracts`
- **IPFS/Pinata**: off-chain storage · Encrypted verifiable credential payload storage with on-chain pointers.
- [Wallet Stack](https://github.com/jayranedev/securedid-v4/tree/master/packages/shared/src/wallet): auth/connectivity · 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](https://github.com/jayranedev/securedid-v4/tree/master/securedid-wallet): legacy Next.js app · Standalone wallet-focused client adjacent to the main product suite. · `securedid-wallet`
- [Design System](https://github.com/jayranedev/securedid-v4/tree/HEAD/SecureDID%20Design%20System): prototype assets · 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](https://github.com/jayranedev/securedid-v4/blob/master/apps/college/src/app/api/rpc/route.ts): app-local API · Lightweight Next.js RPC bridge used by several portals. · `apps/college/src/app/api/rpc/route.ts`
- [Deploy Scripts](https://github.com/jayranedev/securedid-v4/tree/master/blockchain/scripts): hardhat scripts · Factory deployment and registry creation flows for Base Sepolia. · `blockchain/scripts`
- [Contract Tests](https://github.com/jayranedev/securedid-v4/tree/master/blockchain/test): hardhat tests · Validation of DIDFactory and related on-chain behavior. · `blockchain/test`

## Connections

- 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.
