# tokenysolutions/t-rex architecture

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

- Interactive diagram: https://gitdiagram.com/tokenysolutions/t-rex
- Repository: https://github.com/tokenysolutions/t-rex

## Overview

##### Project Type and Purpose
- This is a Solidity-based smart-contract suite (no traditional frontend) implementing the ERC-3643 “T-REX” protocol for security tokens on Ethereum.
- Purpose: enable issuance, management, compliance checks, and regulated transfers of security tokens via on-chain modules (registries, compliance logic, role/permissioning, proxy/factory patterns).

##### File Structure Analysis
- Top-level configs and scripts:
- hardhat.config.ts, tsconfig.json, package.json, .github/workflows, scripts/flatten.js → build/test/deploy pipelines
- contracts/ directory (the core):
- DVA, DVD (token variants)
- _testContracts for versioned/development testing
- compliance/legacy & compliance/modular (multiple compliance modules)
- factory (deploy new tokens)
- proxy (upgradeable pattern: authority & interface)
- registry (trusted issuers, claim topics, identity registries: interface, implementation, storage)
- roles (permissioning via owner/agent)
- token (ERC-3643 token implementation & extensions)
- test/ covers unit/integration via hardhat; docs/ holds whitepaper and images

##### README Insights
- Lists six main on-chain components:
1. ONCHAINID (external identity contract)
2. Trusted Issuers Registry
3. Claim Topics Registry
4. Identity Registry
5. Compliance Smart Contract(s)
6. Security Token Contract
- Mentions factory for deployment, proxy for upgradeability, and modular compliance.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Off-Chain Actors & Services
    subgraph "Off-Chain Actors & Services"
        EOA["EOA / Wallet"]:::external
        Oracles["Oracles / KYC Providers"]:::external
        ONCHAINID["ONCHAINID"]:::external
    end

    %% Factory & Deployment
    subgraph "Factory & Deployment"
        Factory["TREXFactory"]:::factory
    end

    %% Proxy Layer
    subgraph "Proxy Layer"
        ProxyAdmin["ProxyAdmin"]:::proxy
        Proxy["Token Proxy"]:::proxy
    end

    %% Implementation Layer
    subgraph "Implementation Layer"
        %% Token Core
        TREXToken["TREXToken (ERC-3643 Core)"]:::token
        TokenRecovery["TokenRecovery"]:::token
        TokenInformation["TokenInformation"]:::token

        %% Registries
        subgraph "Registries"
            TIRegistry["Trusted Issuers Registry"]:::registry
            CTRegistry["Claim Topics Registry"]:::registry
            IDRegistryIface["Identity Registry Interface"]:::registry
            IDRegistryImpl["Identity Registry Implementation"]:::registry
            IDRegistryStorage["Identity Registry Storage"]:::registry
        end

        %% Compliance Modules
        subgraph "Compliance Modules"
            LegacyCompliance["LegacyCompliance"]:::compliance
            CountryAllowlist["CountryAllowlist"]:::compliance
            TransferFees["TransferFees"]:::compliance
            TimeTransferLimits["TimeTransferLimits"]:::compliance
        end

        %% Roles & Permissioning
        subgraph "Roles & Permissioning"
            OwnerRole["OwnerRole"]:::roles
            AgentRole["AgentRole"]:::roles
        end
    end

    %% Flows
    EOA -->|"manageIdentity()"| ONCHAINID
    Oracles -->|"feedClaims()"| ONCHAINID
    Factory -->|"deploys"| Proxy
    Proxy -->|"delegateTo()"| TREXToken
    EOA -->|"transfer()/mint()/burn()"| Proxy
    TREXToken -->|"isTransferAllowed()"| IDRegistryIface
    IDRegistryIface -->|"calls"| IDRegistryImpl
    IDRegistryImpl -->|"reads/writes"| IDRegistryStorage
    TREXToken -->|"queries"| LegacyCompliance
    TREXToken -->|"queries"| CountryAllowlist
    TREXToken -->|"queries"| TransferFees
    TREXToken -->|"queries"| TimeTransferLimits
    LegacyCompliance -->|"validates"| TIRegistry
    CountryAllowlist -->|"uses"| CTRegistry
    TransferFees -->|"uses"| TIRegistry
    TimeTransferLimits -->|"uses"| CTRegistry
    OwnerRole -->|"manage()"| TIRegistry
    OwnerRole -->|"manage()"| CTRegistry
    OwnerRole -->|"manage()"| IDRegistryImpl
    AgentRole -->|"manageModules()"| LegacyCompliance
    AgentRole -->|"manageModules()"| CountryAllowlist

    %% Click Events
    click TIRegistry "https://github.com/tokenysolutions/t-rex/blob/main/contracts/registry/implementation/TrustedIssuersRegistry.sol"
    click CTRegistry "https://github.com/tokenysolutions/t-rex/blob/main/contracts/registry/implementation/ClaimTopicsRegistry.sol"
    click IDRegistryIface "https://github.com/tokenysolutions/t-rex/blob/main/contracts/registry/interface/IIdentityRegistry.sol"
    click IDRegistryImpl "https://github.com/tokenysolutions/t-rex/blob/main/contracts/registry/implementation/IdentityRegistry.sol"
    click IDRegistryStorage "https://github.com/tokenysolutions/t-rex/blob/main/contracts/registry/storage/IdentityRegistryStorage.sol"
    click LegacyCompliance "https://github.com/tokenysolutions/t-rex/blob/main/contracts/compliance/legacy/LegacyCompliance.sol"
    click CountryAllowlist "https://github.com/tokenysolutions/t-rex/blob/main/contracts/compliance/modular/modules/CountryAllowlist.sol"
    click TransferFees "https://github.com/tokenysolutions/t-rex/blob/main/contracts/compliance/modular/modules/TransferFees.sol"
    click TimeTransferLimits "https://github.com/tokenysolutions/t-rex/blob/main/contracts/compliance/modular/modules/TimeTransferLimits.sol"
    click TREXToken "https://github.com/tokenysolutions/t-rex/blob/main/contracts/token/TREXToken.sol"
    click Factory "https://github.com/tokenysolutions/t-rex/blob/main/contracts/factory/TREXFactory.sol"
    click ProxyAdmin "https://github.com/tokenysolutions/t-rex/blob/main/contracts/proxy/authority/ProxyAuthority.sol"
    click OwnerRole "https://github.com/tokenysolutions/t-rex/blob/main/contracts/roles/permissioning/owner/OwnerRole.sol"
    click AgentRole "https://github.com/tokenysolutions/t-rex/blob/main/contracts/roles/permissioning/agent/AgentRole.sol"

    %% Styles
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px
    classDef factory fill:#d4bfff,stroke:#333,stroke-width:1px
    classDef proxy fill:#a2f5a1,stroke:#333,stroke-width:1px
    classDef token fill:#a2f5a1,stroke:#333,stroke-width:1px
    classDef registry fill:#b3d9ff,stroke:#333,stroke-width:1px
    classDef compliance fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef roles fill:#ffecb3,stroke:#333,stroke-width:1px
```
