# security-alliance/safe-harbor architecture

> Architecture diagram of the GitHub repository security-alliance/safe-harbor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/security-alliance/safe-harbor
- Repository: https://github.com/security-alliance/safe-harbor

## Overview

##### Project type and purpose
- This is an open-source “framework + tooling” repository rather than a monolithic application. Its purpose is twofold:
- Provide legal documentation (PDFs, FAQs, summaries) for the Safe Harbor agreement.
- Supply on-chain registry smart contracts (via Foundry) and off-chain JavaScript helpers to interact with them.
- Key indicator: README describes a legal framework backed by on-chain registry contracts and off-chain assets.

##### File structure
- Top-level:
- documents/ – static legal artifacts (agreement.pdf, FAQ.md, summary.pdf, deployment guide).
- assets/ – logo, flowchart image.
- js/ – Node.js module (domain.js, types.js, fs.js, main.js), package.json, tests under js/test.
- registry-contracts/ – smart contracts (Solidity) with scripts, tests, Foundry config.
- .github/workflows – CI for running Foundry tests via GitHub Actions.
- Architectural patterns:
- Separation of concerns: off-chain docs vs. off-chain tooling vs. on-chain contracts.
- CI/CD pipeline invoking on-chain test suite.
- EIP-712 domain/type definitions in JS for typed contract calls.

##### README for additional insights
- Describes on-chain adoption flow: governance → upload docs to IPFS → call registry contract.
- Mentions multiple target chains (Ethereum, Polygon, Arbitrum…) using the same registry address.
- Includes a flowchart asset: “assets/flowchart.png” illustrating high-level flow.

##### Final advice
- Reference the existing “assets/flowchart.png” as a starting template, then extend it with tooling and CI details.
- Iteratively review with stakeholders (legal, dev, governance teams) to ensure all architectural elements are covered.
- Avoid over-simplification: capturing docs, tooling, CI, and multi-chain deployments ensures a complete view.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    Governance["Protocol Governance"]:::actor

    %% Subgraph Off-Chain
    subgraph "Off-Chain Components"
        DocumentsStore["Off-Chain Documentation Store"]:::static
        Assets["Asset Hosting"]:::static
        subgraph "JS Tooling"
            Domain["EIP-712 Domain Definitions"]:::tooling
            Types["EIP-712 Type Definitions"]:::tooling
            FS["File-System Helpers"]:::tooling
            Main["CLI Entry Point"]:::tooling
            subgraph "JS Unit Tests"
                EIPTest["EIP-712 Tests"]:::tooling
                CLItest["CLI Tests"]:::tooling
            end
        end
    end

    %% Subgraph CI/CD
    subgraph "CI/CD Pipeline"
        Workflow["Foundry & JS Tests Workflow"]:::pipeline
    end

    %% Subgraph On-Chain
    subgraph "On-Chain Registry"
        ContractsSrc["Registry Smart Contracts"]:::onchain
        FoundryCfg["Foundry Configuration"]:::onchain
        Scripts["Deployment & Interaction Scripts"]:::onchain
        SC_Tests["Smart Contract Tests"]:::onchain
        ForgeStd["Shared Forge Std Library"]:::onchain
        AgreementMeta["Agreement Metadata"]:::onchain
    end

    %% External Services
    subgraph "External Services"
        IPFS["IPFS"]:::external
        Blockchain["Blockchain Networks"]:::external
        Explorers["Etherscan / Explorers"]:::external
    end

    %% Relationships
    Governance -->|"upload docs"| IPFS
    IPFS -->|"IPFS hash"| Main
    Main -->|"construct EIP-712 payload"| Domain
    Main -->|"construct EIP-712 payload"| Types
    Main -->|"reads FS Helpers"| FS
    Main -->|"submit tx"| ContractsSrc
    ContractsSrc -->|"emit Adoption event"| Blockchain
    Blockchain -->|view events| Explorers

    Workflow -->|"runs JS tests"| EIPTest
    Workflow -->|"runs JS tests"| CLItest
    Workflow -->|"runs Foundry tests"| SC_Tests

    %% Optional multi-chain deployment
    ContractsSrc -.->|deploy to additional chains| Blockchain

    %% Click Events
    click DocumentsStore "https://github.com/security-alliance/safe-harbor/tree/main/documents/"
    click Assets "https://github.com/security-alliance/safe-harbor/tree/main/assets/"
    click Domain "https://github.com/security-alliance/safe-harbor/blob/main/js/domain.js"
    click Types "https://github.com/security-alliance/safe-harbor/blob/main/js/types.js"
    click FS "https://github.com/security-alliance/safe-harbor/blob/main/js/fs.js"
    click Main "https://github.com/security-alliance/safe-harbor/blob/main/js/main.js"
    click EIPTest "https://github.com/security-alliance/safe-harbor/blob/main/js/test/eip712Test.js"
    click CLItest "https://github.com/security-alliance/safe-harbor/blob/main/js/test.sh"
    click Workflow "https://github.com/security-alliance/safe-harbor/blob/main/.github/workflows/foundry.yaml"
    click ContractsSrc "https://github.com/security-alliance/safe-harbor/tree/main/registry-contracts/src/"
    click FoundryCfg "https://github.com/security-alliance/safe-harbor/blob/main/registry-contracts/foundry.toml"
    click Scripts "https://github.com/security-alliance/safe-harbor/tree/main/registry-contracts/script/"
    click SC_Tests "https://github.com/security-alliance/safe-harbor/tree/main/registry-contracts/test/"
    click ForgeStd "https://github.com/security-alliance/safe-harbor/tree/main/registry-contracts/lib/forge-std/"
    click AgreementMeta "https://github.com/security-alliance/safe-harbor/blob/main/registry-contracts/agreementDetails.json"

    %% Styles
    classDef static fill:#a8e6cf,stroke:#379683,color:#05386b;
    classDef tooling fill:#dcedc1,stroke:#379683,color:#05386b;
    classDef pipeline fill:#ffd3b6,stroke:#e17055,color:#2d3436;
    classDef onchain fill:#ffaaa5,stroke:#d63031,color:#2d3436;
    classDef external fill:#e0e0e0,stroke:#636e72,color:#2d3436;
    classDef actor fill:#ff8b94,stroke:#c0392b,color:#ffffff;
```
