# jdevcs/veri-wallet architecture

> Architecture diagram of the GitHub repository jdevcs/veri-wallet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jdevcs/veri-wallet
- Repository: https://github.com/jdevcs/veri-wallet

## Overview

##### Project Type and Purpose
- This is a full-stack verifiable credential wallet:
- Frontend: React 18 + TypeScript, built with Vite
- Backend: NestJS API for issuing, storing, and verifying verifiable credentials
- Storage: File-based persistence (no external database)
- Crypto: Ed25519 signing with encrypted keypair
- CI: GitHub Actions builds/tests both frontend and backend

##### File Structure Analysis
- Top-level directories:
- backend-veri-wallet/ – NestJS project (controllers, services, modules, crypto, storage, tests)
- ui-veri-wallet/ – Vite/React SPA (pages, components, API client)
- docs/ – Markdown docs for both backend and frontend
- Configuration and build scripts:
- Dockerfile in backend, CI workflow in .github/workflows/ci.yml
- tsconfig.json, ESLint, Prettier, Vite config, environment variable usage

##### Key Components
a. Frontend (ui-veri-wallet)
- Pages: DashboardPage, IssueCredentialPage, VerifyCredentialPage
- Components: Header, CredentialList, IssueCredentialForm, VerifyCredentialForm
- API client: credentialsApi.ts uses REST calls (POST /credentials, GET /credentials, POST /credentials/verify, DELETE /credentials/:id)
- Dev server (Vite) and build step
b. Backend (backend-veri-wallet)
- NestJS Modules: CredentialsModule
- Controllers: CredentialsController (HTTP endpoints for issue, list, fetch, verify, delete)
- Services:
- CredentialService (orchestrates issue/verify flows)
- CredentialSignerService (crypto signing)
- KeyManagerService (key loading/decryption)
- Storage layer:
- CredentialRepository interface
- FileCredentialRepository implementation (reads/writes JSON files under data/)
- Main entry: main.ts initializes Nest application, loads config (PORT, KEYPAIR_PASSPHRASE)
c. Persistence
- File system storage: data/keypair.json (encrypted), data/credentials/*.json
d. External/Infrastructure
- Environment variables: PORT, KEYPAIR_PASSPHRASE, VITE_API_BASE_URL
- Docker (optional containerized backend)
- CI pipeline (GitHub Actions)

##### Interactions & Data Flows
- Browser → React SPA
- React SPA → REST API calls to NestJS backend
- NestJS Controller → Service layer → Crypto/Storage modules → File system
- Verification flow: Controller → Service → CredentialSignerService verifies signature
- CI pipeline: checks out code → installs dependencies → runs tests (backend) and build (frontend)

##### Architectural Patterns
- Backend: NestJS’s modular/MVC pattern (Controllers, Providers, Modules)
- Frontend: Component-based SPA, API separation
- Dependency injection in NestJS for crypto and storage abstractions

##### Essential Elements
- Clear labels for all components, modules, and external resources

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::external

    subgraph "Frontend (ui-veri-wallet)"
        direction TB
        Entry["src/main.tsx"]:::frontend
        Vite["vite.config.ts"]:::infra
        HeaderComp["Header"]:::frontend
        DashPage["DashboardPage"]:::frontend
        IssuePage["IssueCredentialPage"]:::frontend
        VerifyPage["VerifyCredentialPage"]:::frontend
        CredList["CredentialList"]:::frontend
        IssueForm["IssueCredentialForm"]:::frontend
        VerifyForm["VerifyCredentialForm"]:::frontend
        APIClient["credentialsApi.ts"]:::frontend

        Entry --> HeaderComp
        Entry --> DashPage
        Entry --> IssuePage
        Entry --> VerifyPage

        DashPage --> CredList
        IssuePage --> IssueForm
        VerifyPage --> VerifyForm

        CredList --> APIClient
        IssueForm --> APIClient
        VerifyForm --> APIClient

        APIClient -->|REST API| APIEndpoint
    end

    subgraph "Backend (backend-veri-wallet)"
        direction TB
        MainApp["src/main.ts"]:::backend
        Ctrl["CredentialsController"]:::backend
        Service["CredentialsService"]:::backend
        Signer["CredentialSignerService"]:::crypto
        KeyManager["KeyManagerService"]:::crypto
        RepoInterface["CredentialRepository"]:::backend
        FileRepo["FileCredentialRepository"]:::storage
        StorageConst["storage.constants.ts"]:::backend
        StorageCyl["File System (data/*.json)"]:::storage
        KeyPair["Keypair (data/keypair.json)"]:::crypto

        MainApp --> Ctrl
        Ctrl --> Service
        Service --> Signer
        Service --> KeyManager
        Service --> RepoInterface
        RepoInterface --> FileRepo
        FileRepo --> StorageCyl
        KeyManager --> KeyPair
    end

    APIEndpoint["/credentials (POST, GET, DELETE, VERIFY)"]:::backend
    APIEndpoint -->|calls| Ctrl

    subgraph "Infrastructure & CI"
        direction TB
        Env["Env Vars: PORT, KEYPAIR_PASSPHRASE, VITE_API_BASE_URL"]:::infra
        Docker["Dockerfile"]:::infra
        CI[".github/workflows/ci.yml"]:::infra

        Env --> MainApp
        CI --> Entry
        CI --> MainApp
        Docker --> MainApp
    end

    User --> Entry
    User --> Vite

    click DashPage "https://github.com/jdevcs/veri-wallet/blob/main/ui-veri-wallet/src/pages/DashboardPage.tsx"
    click IssuePage "https://github.com/jdevcs/veri-wallet/blob/main/ui-veri-wallet/src/pages/IssueCredentialPage.tsx"
    click VerifyPage "https://github.com/jdevcs/veri-wallet/blob/main/ui-veri-wallet/src/pages/VerifyCredentialPage.tsx"
    click HeaderComp "https://github.com/jdevcs/veri-wallet/blob/main/ui-veri-wallet/src/components/Header.tsx"
    click CredList "https://github.com/jdevcs/veri-wallet/blob/main/ui-veri-wallet/src/components/CredentialList.tsx"
    click IssueForm "https://github.com/jdevcs/veri-wallet/blob/main/ui-veri-wallet/src/components/IssueCredentialForm.tsx"
    click VerifyForm "https://github.com/jdevcs/veri-wallet/blob/main/ui-veri-wallet/src/components/VerifyCredentialForm.tsx"
    click APIClient "https://github.com/jdevcs/veri-wallet/blob/main/ui-veri-wallet/src/api/credentialsApi.ts"
    click Vite "https://github.com/jdevcs/veri-wallet/blob/main/ui-veri-wallet/vite.config.ts"
    click Entry "https://github.com/jdevcs/veri-wallet/blob/main/ui-veri-wallet/src/main.tsx"

    click MainApp "https://github.com/jdevcs/veri-wallet/blob/main/backend-veri-wallet/src/main.ts"
    click Ctrl "https://github.com/jdevcs/veri-wallet/blob/main/backend-veri-wallet/src/credentials/credentials.controller.ts"
    click Service "https://github.com/jdevcs/veri-wallet/blob/main/backend-veri-wallet/src/credentials/credentials.service.ts"
    click Signer "https://github.com/jdevcs/veri-wallet/blob/main/backend-veri-wallet/src/credentials/crypto/credential-signer.service.ts"
    click KeyManager "https://github.com/jdevcs/veri-wallet/blob/main/backend-veri-wallet/src/credentials/crypto/key-manager.service.ts"
    click RepoInterface "https://github.com/jdevcs/veri-wallet/blob/main/backend-veri-wallet/src/credentials/storage/credential.repository.ts"
    click FileRepo "https://github.com/jdevcs/veri-wallet/blob/main/backend-veri-wallet/src/credentials/storage/file-credential.repository.ts"
    click StorageConst "https://github.com/jdevcs/veri-wallet/blob/main/backend-veri-wallet/src/credentials/storage/storage.constants.ts"
    click Docker "https://github.com/jdevcs/veri-wallet/tree/main/backend-veri-wallet/Dockerfile"
    click CI "https://github.com/jdevcs/veri-wallet/blob/main/.github/workflows/ci.yml"

    classDef frontend fill:#CCE5FF,stroke:#333,stroke-width:1px
    classDef backend fill:#CCFFCC,stroke:#333,stroke-width:1px
    classDef storage fill:#FFD7CC,stroke:#333,stroke-width:1px
    classDef crypto fill:#E5CCFF,stroke:#333,stroke-width:1px
    classDef infra fill:#F0F0F0,stroke:#333,stroke-width:1px
    classDef external fill:#FFFFFF,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
```
