# psmri/ubi-verification-sdk architecture

> Architecture diagram of the GitHub repository psmri/ubi-verification-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/psmri/ubi-verification-sdk
- Repository: https://github.com/psmri/ubi-verification-sdk

## Overview

##### Project type and purpose
- This is a standalone, backend Node.js SDK/service built on Fastify that exposes a single HTTP API (`/verification`) for credential verification.
- It is designed to be modular and extensible: new “verifier” modules can be dropped in (online or offline) without touching core logic.

##### File structure
- Top‐level files:
- Dockerfile / docker-compose.yml / deploy.sh → containerization & deployment
- .env.example → environment configuration (PORT, external API URLs, credentials)
- README.md, package.json → project metadata & scripts
- src/config/swagger.yaml → API docs definition
- src/index.js → Fastify server bootstrap (register routes, plugins, swagger)
- src/services/verificationService.js → core service that drives verification
- src/services/verifiers/ → pluggable verifier modules
- VerifierInterface.js → base abstract class
- VerifierFactory.js → selects/verifier instantiation logic based on method & issuerName
- online-verifiers/DhiwayVerifier.js → example online verifier calling external Dhiway API
- offline-verifier/SignatureVerifier.js → example offline verifier applying signature checks

##### README for additional insights
- Fastify for performance & swagger for interactive docs
- Single API endpoint (`POST /verification`) with body { credential, config }
- Health check endpoint (`GET /health`)
- Emphasis on extensibility: add new verifiers by subclassing VerifierInterface
- No direct database or message queues—pure request/response service

A. HTTP Layer (Fastify Server)
- Listens on PORT
- Routes: `/health`, `/documentation`, `/verification`
B. Verification Service (service layer)
- Receives validated request payload
- Delegates to VerifierFactory
C. VerifierFactory
- Reads `config.method` & `config.issuerName`
- Instantiates appropriate verifier subclass
D. Concrete Verifier(s)
- Online: DhiwayVerifier → makes HTTPS call to Dhiway external API
- Offline: SignatureVerifier → runs local crypto checks
E. External Dependency
- Dhiway API (or other online providers as added)
F. Configuration & Docs
- swagger.yaml → drives `/documentation` UI
- .env / .env.example → runtime config (PORT, external URLs)
G. Container/Deployment
- Dockerfile / docker-compose.yml → container boundary

##### Architectural patterns & design principles
- Layered architecture: HTTP → Service → Factory → Verifier
- Dependency inversion via VerifierInterface (plug‐in pattern)
- Single Responsibility: each module has one concern
- Open/Closed: new verifiers can be added without modifying core

##### Essential elements
- Clear labels for each component (e.g., “Fastify HTTP Server”, “VerificationService”)
- Callouts for extensibility points (“Add new verifier here”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client"]:::external

    %% HTTP Layer
    subgraph "HTTP Layer"
        HTTP["Fastify HTTP Server"]:::server
        VerifRoute["POST /verification"]:::server
        Health["GET /health"]:::server
        Docs["Swagger UI"]:::config
    end

    %% Service Layer
    subgraph "Service Layer"
        VerificationService["VerificationService"]:::service
    end

    %% Factory Layer
    subgraph "Factory Layer"
        Factory["VerifierFactory"]:::factory
    end

    %% Verifiers
    subgraph "Verifiers (Plug-in Modules)"
        Interface["VerifierInterface"]:::interface
        Dhiway["DhiwayVerifier"]:::online
        Signature["SignatureVerifier"]:::offline
    end

    %% External Services
    subgraph "External Services"
        DhiwayAPI["Dhiway API"]:::externalService
    end

    %% Config & Deployment
    subgraph "Config & Deployment"
        Env[".env.example"]:::config
        SwaggerFile["swagger.yaml"]:::config
        Dockerfile["Dockerfile"]:::deployment
        Compose["docker-compose.yml"]:::deployment
        Deploy["deploy.sh"]:::deployment
        Package["package.json"]:::config
    end

    %% Connections
    Client -->|"POST /verification"| HTTP
    HTTP --> VerifRoute
    HTTP --> Health
    HTTP --> Docs

    VerifRoute -->|"verify(credential,config)"| VerificationService
    VerificationService -->|"selectVerifier()"| Factory
    Factory -->|"implements"| Interface
    Factory -->|"create verifier"| Dhiway
    Factory -->|"create verifier"| Signature
    Dhiway -->|"HTTPS request"| DhiwayAPI
    Signature -->|"local crypto checks"| VerificationService

    Docs --> SwaggerFile
    HTTP --> Env

    %% Click Events
    click HTTP "https://github.com/psmri/ubi-verification-sdk/blob/main/src/index.js"
    click VerificationService "https://github.com/psmri/ubi-verification-sdk/blob/main/src/services/verificationService.js"
    click Factory "https://github.com/psmri/ubi-verification-sdk/blob/main/src/services/verifiers/VerifierFactory.js"
    click Interface "https://github.com/psmri/ubi-verification-sdk/blob/main/src/services/verifiers/VerifierInterface.js"
    click Dhiway "https://github.com/psmri/ubi-verification-sdk/blob/main/src/services/verifiers/online-verifiers/DhiwayVerifier.js"
    click Signature "https://github.com/psmri/ubi-verification-sdk/blob/main/src/services/verifiers/offline-verifier/SignatureVerifier.js"
    click SwaggerFile "https://github.com/psmri/ubi-verification-sdk/blob/main/src/config/swagger.yaml"
    click Env "https://github.com/psmri/ubi-verification-sdk/blob/main/.env.example"
    click Dockerfile "https://github.com/psmri/ubi-verification-sdk/tree/main/Dockerfile"
    click Compose "https://github.com/psmri/ubi-verification-sdk/blob/main/docker-compose.yml"
    click Deploy "https://github.com/psmri/ubi-verification-sdk/blob/main/deploy.sh"
    click Package "https://github.com/psmri/ubi-verification-sdk/blob/main/package.json"

    %% Styles
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef server fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef service fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef factory fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef interface fill:#f8d7da,stroke:#721c24,stroke-width:1px
    classDef online fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef offline fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef externalService fill:#f5c6cb,stroke:#721c24,stroke-width:1px
    classDef config fill:#fce5cd,stroke:#b35900,stroke-width:1px
    classDef deployment fill:#d6e9c6,stroke:#3c763d,stroke-width:1px
```
