flowchart LR
    subgraph Clients_&_Tools
        CLI[CLI\ncli/]
        Wallet[Wallet App\nwallet/]
        GUI[GUI & Explorer\nnode-app/, gui/, explorer/]
        SDK[SDKs & Scripts\nsdk/, scripts/, docs/]
    end
    subgraph Node_Runtime
        LNode[citrate-node crate\nnode/]
        API[citrate-api\ncore/api/]
        Net[citrate-network\ncore/network/]
        Seq[lattice-sequencer\ncore/sequencer/]
        Cons[citrate-consensus\ncore/consensus/]
        Exec[citrate-execution (EVM + AI)\ncore/execution/]
        Store[citrate-storage\ncore/storage/]
        Econ[lattice-economics\ncore/economics/]
        MCP[citrate-mcp\ncore/mcp/]
    end
    subgraph External_Systems
        IPFS[(IPFS Daemons)]
        Rocks[(RocksDB)]
        Chain[(Smart Contracts\ncontracts/)]
        Explorer[(Indexing & Analytics\nexplorer/, data-pipelines)]
        Peers((P2P Peers))
    end
    CLI --> LNode
    Wallet --> LNode
    GUI --> API
    SDK --> API
    LNode --> API
    LNode --> Net
    Net --> Peers
    API --> Exec
    Exec --> Store
    LNode --> Seq --> Cons --> Exec
    Store --> Rocks
    Store --> IPFS
    Exec --> MCP
    MCP --> IPFS
    Exec --> Chain
    Econ --> LNode
    Chain --> Explorer
    API --> Explorer

graph TD
    LC[citrate-consensus]
    LE[citrate-execution]
    LS[citrate-storage]
    LNw[citrate-network]
    LSeq[lattice-sequencer]
    LMCP[citrate-mcp]
    LEcon[lattice-economics]
    LApi[citrate-api]
    LNode[citrate-node]
    CLI[citrate-cli]
    NodeApp[node-app]
    LWallet[citrate-wallet]
    LFaucet[citrate-faucet]
    LCore[lattice-core]
    LMCP --> LE
    LMCP --> LS
    LE --> LC
    LS --> LC
    LS --> LE
    LSeq --> LC
    LSeq --> LE
    LNw --> LC
    LNw --> LE
    LNw --> LSeq
    LNw --> LS
    LApi --> LC
    LApi --> LE
    LApi --> LNw
    LApi --> LSeq
    LApi --> LS
    LEcon --> LC
    LEcon --> LE
    LEcon --> LS
    LNode --> LApi
    LNode --> LC
    LNode --> LE
    LNode --> LMCP
    LNode --> LNw
    LNode --> LSeq
    LNode --> LS
    LNode --> LEcon
    CLI --> LApi
    CLI --> LC
    CLI --> LE
    NodeApp --> LApi
    NodeApp --> LE
    NodeApp --> LNw
    NodeApp --> LSeq
    NodeApp --> LS
    LWallet --> LC
    LWallet --> LE
    LFaucet --> LC
    LFaucet --> LE
    LCore --> LC
    LCore --> LEcon
    LCore --> LE
    LCore --> LMCP
    LCore --> LNw
    LCore --> LSeq
    LCore --> LS
    LCore --> LWallet

flowchart TD
    subgraph Storage_and_IPFS [core/storage/src/ipfs]
        IPFSService["IPFSService\nmod.rs"] --> PinMgr["PinningManager\npinning.rs"]
        IPFSService --> Chunking["Chunking helpers\nchunking.rs"]
        IPFSService --> ArtifactSvc["NodeArtifactService\nnode/src/artifact.rs"]
        PinMgr -->|Rewards| IPFSIncentivesC["IPFSIncentives.sol\ncontracts/src"]
        IPFSService -->|Persists| RocksDB[(RocksDB CFs)]
        ArtifactSvc -->|REST| IPFSEndpoints[(CITRATE_IPFS_API, providers)]
    end
    subgraph Execution_and_MCP
        Executor["Executor\ncore/execution/src/executor.rs"] --> IPFSService
        Executor --> InferenceSvc["NodeInferenceService\nnode/src/inference.rs"]
        InferenceSvc --> MCPService["MCPService\ncore/mcp/src/lib.rs"]
        MCPService --> ModelRegistry["ModelRegistry\ncore/mcp/src/registry.rs"]
        MCPService --> ModelCache["ModelCache\ncore/mcp/src/cache.rs"]
    end
    subgraph On-chain
        ModelRegistrySol["ModelRegistry.sol"] -->|Precompile| Executor
        IPFSIncentivesC -->|Claims| Wallets
    end
    ModelRegistry -->|Weight CID| IPFSService
    MCPService --> IPFSEndpoints

flowchart LR
    subgraph Configs_and_Env
        Devnet[devnet-config.toml\nroot]
        Testnet[testnet-config.toml]
        Genesis[genesis.json]
        EnvFile[.env.local]
        GUIConf[gui/lattice-core/config/*.json]
        DockerCfg[docker-compose.yml, Dockerfile]
        Scripts[start_fresh_testnet.sh, scripts/]
    end
    Devnet --> NodeCfg["Node runtime\nnode/config.rs"]
    Testnet --> NodeCfg
    Genesis --> NodeCfg
    EnvFile --> NodeCfg
    DockerCfg --> NodeDeployment[(Docker / Compose)]
    Scripts --> NodeDeployment
    GUIConf --> GUIRuntime["GUI (node-app/, gui/)"]
    NodeCfg --> CoreCrates["Core crates\n(core/*)"]
    NodeDeployment --> CoreCrates
    CoreCrates --> ContractsBuild["Foundry & Solidity\ncontracts/"]
    ContractsBuild --> DeployScripts["contracts/script/"]
    CoreCrates --> MonitoringDocs["docs/, TEST_AUDIT_REPORT.md, ROADMAP_STATUS.md"]
    GUIRuntime --> Users
    NodeDeployment --> Observability["monitoring/, test results/"]

```mermaid
flowchart LR
  subgraph Clients
    U["User / dApp"]
    CLI[CLI]
    SDK[SDK JS]
    GUI[Desktop GUI]
  end

  subgraph Node
    API["JSON-RPC / WS (core/api)"]
    SEQ[Sequencer]
    EXEC[Execution]
    CONS["Consensus (GhostDAG)"]
    STORE["Storage (RocksDB)"]
    NET["P2P Network"]
  end

  subgraph Apps
    EXPL[Explorer]
    DOCS["Docs Portal"]
  end

  U -->|HTTP/WS| API
  CLI -->|HTTP/WS| API
  SDK -->|HTTP/WS| API
  GUI -->|Tauri invoke/RPC| API

  API --> SEQ --> EXEC --> STORE
  CONS --> STORE
  CONS <--> SEQ
  NET <--> SEQ
  NET <--> CONS

  API --> EXPL
  DOCS -. reference .-> U

sequenceDiagram
  participant Wallet
  participant RPC as JSON-RPC (core/api)
  participant Seq as Sequencer
  participant Exec as Execution
  participant Cons as Consensus
  participant DB as Storage

  Wallet->>RPC: eth_sendRawTransaction / citrate_requestInference
  RPC->>Seq: enqueue(tx)
  Seq->>Cons: propose block (DAG tip selection)
  Cons->>Exec: ordered tx set
  Exec->>DB: apply state transitions
  DB-->>RPC: receipts, state proofs
  RPC-->>Wallet: tx hash / inference result