# auvoid/ssimon architecture

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

- Interactive diagram: https://gitdiagram.com/auvoid/ssimon
- Repository: https://github.com/auvoid/ssimon

## Overview

##### Project type and purpose
- SSIMON is an open-source TypeScript library (not a monolithic app or microservice).
- Purpose: provide a modular, plug-and-play framework for creating, managing, and storing W3C Decentralized Identifiers (DIDs) and Verifiable Credentials (VCs).

##### File structure
- Top-level:
- package.json, tsconfig.json, config files, docs/ (user/developer docs), .github/ (CI/CD + templates)
- src/ (all implementation code)
- src/NetworkAdapter/ (abstract and concrete adapters for DID methods)
- src/Storage/ (abstract and concrete stores, GenericStore)
- src/identity-manager.ts & .types.ts (core orchestration API)
- src/index.ts (public export entry point)
- Patterns:
- Adapter Pattern for pluggable DID methods (NetworkAdapter)
- Repository/Strategy-style for storage backends (Storage/GenericStore)
- Single responsibility in CredentialsManager and IdentityAccount submodules
- Tests in src/tests/ using Vitest, build scripts in .github/workflows

##### README
- Highlights adapter ecosystem, W3C compliance, “plug and play,” and simple API.

a. Main components:
- SSIMON Core API – exposed by src/index.ts & identity-manager.ts
- NetworkAdapter Layer – CredentialsManager, IdentityAccount adapters
- Storage Layer – GenericStore and other store implementations
- Utilities – codec, crypto
- External Systems – DID networks, data storage backends (e.g., local FS, cloud DB)
b. Relationships & data flow:
1. Client code → SSIMON Core API (initialize, issue DID/VC, query)
2. Core → NetworkAdapter(s) to interact with blockchain/ledger for DIDs & VCs
3. Core → StorageAdapter(s) to persist DIDs/VCs locally or remotely
4. Utility modules support both layers (e.g., crypto.js for signing)
c. Architectural patterns/design principles:
- Adapter pattern enables multiple DID methods
- Open/closed principle: new adapters added without touching core
- Separation of concerns: identity orchestration vs. network vs. storage
d. Key technologies/frameworks:
- TypeScript (src/, .types.ts)
- Node.js modules (package.json)
- Vitest for tests (vitest.config.ts)

##### Key detail pointers
- CredentialsManager and IdentityAccount as distinct sub-adapters under NetworkAdapter.
- GenericStore’s index.types.ts interface as the contract for all storage backends.
- Testing suite as a separate “Quality” artifact (Vitest) if desired.

##### Putting it together
- Layer 1 (top): Client Application (consumes @tanglelabs/ssimon)
- Layer 2: SSIMON Core API
- Layer 3a: NetworkAdapter
- CredentialsManager
- IdentityAccount
- Layer 3b: StorageAdapter
- GenericStore
- Layer 4 (bottom): External Systems
- DID Ledger / VC Registry
- Persistent DB / File System
- Utilities (side-bar feeding into Core & Adapters)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    ClientApp["Client Application<br/>(@tanglelabs/ssimon)"]

    %% Core Layer
    subgraph "SSIMON Core" 
        CoreAPI["src/index.ts<br/>Public API"] 
        IdentityManager["src/identity-manager.ts<br/>Core Orchestrator"]
        IdentityTypes["src/identity-manager.types.ts<br/>API Types"]
    end

    %% Network Adapter Layer
    subgraph "Network Adapter Layer"
        CredentialsManager["CredentialsManager Adapter"]
        CredentialsSchema["CredentialsManager Schema"]
        IdentityAccount["IdentityAccount Adapter"]
        NetTypes["src/NetworkAdapter/index.types.ts<br/>NetworkAdapter Interfaces"]
    end

    %% Storage Adapter Layer
    subgraph "Storage Adapter Layer"
        StorageEntry["src/Storage/index.ts<br/>Storage Entry"]
        GenericStore["GenericStore Implementation"]
        StoreTypes["GenericStore Types<br/>(Storage Contract)"]
    end

    %% Utilities
    subgraph "Utilities"
        Codec["src/utils/codec.ts<br/>Codec"]
        Crypto["src/utils/crypto.ts<br/>Crypto"]
    end

    %% External Systems
    subgraph "External Systems"
        DIDLedger(["DID Ledger / VC Registry"])
        PersistentStore(["Persistent DB / File System"])
    end

    %% Quality Artifacts
    subgraph "Quality Artifacts"
        TestSuite["src/tests<br/>Vitest Suite"]
        TestFS["Manual Test Helper (FS)"]
        TestRandom["Random Test Utility"]
        CI[".github/workflows<br/>CI/CD Pipelines"]
    end

    %% Connections
    ClientApp -->|"initialize(), createDid(), issueVC()"| CoreAPI
    CoreAPI -->|"orchestrate()"| IdentityManager
    CoreAPI -->|"types" | IdentityTypes

    IdentityManager -->|"createDid() / issueVC()"| CredentialsManager
    IdentityManager -->|"storeCredential(), getCredential()"| GenericStore

    CredentialsManager -->|"schema validation"| CredentialsSchema
    CredentialsManager -->|"ledger ops"| DIDLedger
    IdentityAccount -->|"ledger ops"| DIDLedger

    GenericStore -->|"persist()/query()"| PersistentStore
    GenericStore -->|"contract"| StoreTypes

    CoreAPI --> Codec
    CoreAPI --> Crypto
    CredentialsManager --> Crypto
    GenericStore --> Codec

    %% Quality
    CI --> TestSuite
    TestSuite --> TestFS
    TestSuite --> TestRandom

    %% Click Events
    click CoreAPI "https://github.com/auvoid/ssimon/blob/dev/src/index.ts"
    click IdentityManager "https://github.com/auvoid/ssimon/blob/dev/src/identity-manager.ts"
    click IdentityTypes "https://github.com/auvoid/ssimon/blob/dev/src/identity-manager.types.ts"
    click NetTypes "https://github.com/auvoid/ssimon/blob/dev/src/NetworkAdapter/index.types.ts"
    click CredentialsManager "https://github.com/auvoid/ssimon/blob/dev/src/NetworkAdapter/CredentialsManager/index.ts"
    click CredentialsSchema "https://github.com/auvoid/ssimon/blob/dev/src/NetworkAdapter/CredentialsManager/ob-schema.ts"
    click IdentityAccount "https://github.com/auvoid/ssimon/blob/dev/src/NetworkAdapter/IdentityAccount/index.ts"
    click StorageEntry "https://github.com/auvoid/ssimon/blob/dev/src/Storage/index.ts"
    click GenericStore "https://github.com/auvoid/ssimon/blob/dev/src/Storage/GenericStore/index.ts"
    click StoreTypes "https://github.com/auvoid/ssimon/blob/dev/src/Storage/GenericStore/index.types.ts"
    click Codec "https://github.com/auvoid/ssimon/blob/dev/src/utils/codec.ts"
    click Crypto "https://github.com/auvoid/ssimon/blob/dev/src/utils/crypto.ts"
    click TestSuite "https://github.com/auvoid/ssimon/tree/dev/src/tests"
    click TestFS "https://github.com/auvoid/ssimon/blob/dev/src/tests/test-utils/fs.ts"
    click TestRandom "https://github.com/auvoid/ssimon/blob/dev/src/tests/test-utils/random.ts"
    click CI "https://github.com/auvoid/ssimon/tree/dev/.github/workflows"

    %% Styles
    classDef core fill:#cce5ff,stroke:#339,stroke-width:1px
    classDef adapters fill:#e6ffe6,stroke:#393,stroke-width:1px
    classDef utils fill:#ffe6cc,stroke:#f90,stroke-width:1px
    classDef external fill:#eeeeee,stroke:#888,stroke-width:1px
    classDef quality fill:#f2e6ff,stroke:#933,stroke-width:1px

    class CoreAPI,IdentityManager,IdentityTypes core
    class CredentialsManager,IdentityAccount,CredentialsSchema,NetTypes adapters
    class StorageEntry,GenericStore,StoreTypes adapters
    class Codec,Crypto utils
    class DIDLedger,PersistentStore external
    class TestSuite,TestFS,TestRandom,CI quality
```
