# hashim-777x/tokenization-rwa architecture

> Architecture diagram of the GitHub repository hashim-777x/tokenization-rwa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hashim-777x/tokenization-rwa
- Repository: https://github.com/hashim-777x/tokenization-rwa

## Overview

1. This repo is a Foundry-based Ethereum project. The core system is Solidity code under `src`, with tests, scripts, and build tooling managed by Foundry (`forge`, `cast`, `anvil`).

2. The on-chain boundary is the Solidity contract layer in `src`. The exact contracts aren’t visible from the tree, but this is where the protocol logic lives and where any Chainlink/OpenZeppelin dependencies are consumed.

3. The project depends on two major Solidity libraries in `lib`: `openzeppelin-contracts` for standard contract primitives and `chainlink-brownie-contracts` for Chainlink integrations. That strongly suggests the on-chain code is designed to interact with Chainlink services rather than being a standalone contract set.

4. There is a separate off-chain JavaScript subsystem under `functions/`. This looks like a Chainlink Functions-style package: `functions/sources/alpacaBalance.js` likely contains the request code that runs off-chain, while `functions/configs/alpacaMintConfig.js` and `functions/simulators/alpacaMintSimulator.js` support local configuration and simulation.

5. The off-chain functions area is an important architectural boundary. It separates deterministic Solidity execution from external data access logic, likely pulling data from Alpaca-related APIs or services and preparing responses for on-chain consumption.

6. `functions/uploadSecrets.js` indicates a secrets-management path for the off-chain execution environment. That means sensitive credentials are not embedded in Solidity; they are handled separately and uploaded to whatever Chainlink Functions or runtime environment this repo targets.

7. `broadcast/` is the deployment artifact area produced by Foundry scripting. It typically records actual transaction outputs and deployed addresses, so it acts as the runtime deployment boundary between source code and live chain state.

8. `script/` contains deployment or operational Solidity scripts, separate from the production contracts. These scripts are the orchestration layer for deploying, configuring, or interacting with the on-chain contracts.

9. `foundry.toml`, `remappings.txt`, and `package-lock.json`/`package.json` show a mixed tooling setup: Foundry for Solidity compilation/testing and Node.js for the off-chain Functions package. The repo is therefore not purely smart contracts; it spans both EVM and JavaScript runtimes.

10. `.github/workflows/test.yml` provides CI around the Foundry test suite. So the main verification path is automated contract testing in CI, likely supplemented by local simulation for the off-chain Functions code.

11. The overall data flow appears to be: off-chain JS function code gathers external Alpaca-related data, optionally uses secrets, then supports on-chain contract behavior through Chainlink integration. The Solidity side likely requests or consumes that data, while deployment scripts and broadcast artifacts manage the live-chain lifecycle.

12. For an architecture diagram, the key boundaries are: external data sources on the off-chain side, Chainlink Functions/off-chain JavaScript in the middle, and Solidity contracts on-chain at the core, with Foundry plus CI wrapping build, test, and deployment operations.

Main entry points: [`functions`](https://github.com/hashim-777x/tokenization-rwa/tree/master/functions) (Functions), [`src`](https://github.com/hashim-777x/tokenization-rwa/tree/master/src) (Contracts), [`functions/sources/alpacaBalance.js`](https://github.com/hashim-777x/tokenization-rwa/blob/master/functions/sources/alpacaBalance.js) (Data request), [`foundry.toml`](https://github.com/hashim-777x/tokenization-rwa/blob/master/foundry.toml) (Foundry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_onchain["On-chain"]
  node_src["Contracts<br/>solidity core"]
  node_script["Scripts"]
end

subgraph group_functions["Functions"]
  node_functions_root["Functions<br/>js subsystem"]
  node_func_source["Data request<br/>js source<br/>[alpacaBalance.js]"]
  node_func_config["Config"]
  node_func_sim["Simulator"]
  node_func_secrets["Secrets<br/>upload helper<br/>[uploadSecrets.js]"]
end

subgraph group_tooling["Tooling"]
  node_broadcast["Broadcasts<br/>deployment artifacts"]
  node_foundry["Foundry<br/>build toolchain<br/>[foundry.toml]"]
  node_node_pkg["Node package<br/>js tooling<br/>[package.json]"]
  node_ci["CI<br/>workflow<br/>[test.yml]"]
end

subgraph group_deps["Dependencies"]
  node_chainlink_lib["Chainlink<br/>solidity lib"]
  node_oz_lib["OpenZeppelin<br/>solidity lib"]
end

node_src -->|"uses"| node_chainlink_lib
node_src -->|"uses"| node_oz_lib
node_src -->|"requests data"| node_func_source
node_script -->|"deploys"| node_src
node_script -->|"records"| node_broadcast
node_functions_root -->|"contains"| node_func_source
node_functions_root -->|"contains"| node_func_config
node_functions_root -->|"contains"| node_func_sim
node_functions_root -->|"contains"| node_func_secrets
node_func_sim -->|"simulates"| node_func_source
node_func_config -->|"configures"| node_func_source
node_func_secrets -->|"supports"| node_func_source
node_foundry -->|"builds"| node_src
node_foundry -->|"runs"| node_script
node_foundry -->|"emits"| node_broadcast
node_node_pkg -->|"packages"| node_functions_root
node_ci -->|"verifies"| node_foundry

click node_src "https://github.com/hashim-777x/tokenization-rwa/tree/master/src"
click node_script "https://github.com/hashim-777x/tokenization-rwa/tree/master/script"
click node_broadcast "https://github.com/hashim-777x/tokenization-rwa/tree/master/broadcast"
click node_functions_root "https://github.com/hashim-777x/tokenization-rwa/tree/master/functions"
click node_func_source "https://github.com/hashim-777x/tokenization-rwa/blob/master/functions/sources/alpacaBalance.js"
click node_func_config "https://github.com/hashim-777x/tokenization-rwa/blob/master/functions/configs/alpacaMintConfig.js"
click node_func_sim "https://github.com/hashim-777x/tokenization-rwa/blob/master/functions/simulators/alpacaMintSimulator.js"
click node_func_secrets "https://github.com/hashim-777x/tokenization-rwa/blob/master/functions/uploadSecrets.js"
click node_chainlink_lib "https://github.com/hashim-777x/tokenization-rwa/tree/master/lib/chainlink-brownie-contracts"
click node_oz_lib "https://github.com/hashim-777x/tokenization-rwa/tree/master/lib/openzeppelin-contracts"
click node_foundry "https://github.com/hashim-777x/tokenization-rwa/blob/master/foundry.toml"
click node_node_pkg "https://github.com/hashim-777x/tokenization-rwa/blob/master/package.json"
click node_ci "https://github.com/hashim-777x/tokenization-rwa/blob/master/.github/workflows/test.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src,node_script toneBlue
class node_functions_root,node_func_source,node_func_config,node_func_sim,node_func_secrets toneAmber
class node_broadcast,node_foundry,node_node_pkg,node_ci toneMint
class node_chainlink_lib,node_oz_lib toneRose
```

## Components

### On-chain

Solidity protocol logic and deployment lifecycle.

- [Contracts](https://github.com/hashim-777x/tokenization-rwa/tree/master/src): solidity core · Primary on-chain protocol contracts and Chainlink-facing logic. · `src`
- [Scripts](https://github.com/hashim-777x/tokenization-rwa/tree/master/script): foundry scripts · Operational Solidity scripts for deployment and configuration. · `script`

### Functions

Off-chain JavaScript logic for external data and simulation.

- [Functions](https://github.com/hashim-777x/tokenization-rwa/tree/master/functions): js subsystem · Off-chain JavaScript package for Chainlink Functions-style execution. · `functions`
- [Data request](https://github.com/hashim-777x/tokenization-rwa/blob/master/functions/sources/alpacaBalance.js): js source · Off-chain request logic that gathers external balance data. · `functions/sources/alpacaBalance.js`
- [Config](https://github.com/hashim-777x/tokenization-rwa/blob/master/functions/configs/alpacaMintConfig.js): js config · Runtime and request configuration for the off-chain function. · `functions/configs/alpacaMintConfig.js`
- [Simulator](https://github.com/hashim-777x/tokenization-rwa/blob/master/functions/simulators/alpacaMintSimulator.js): js simulator · Local simulation harness for the off-chain function flow. · `functions/simulators/alpacaMintSimulator.js`
- [Secrets](https://github.com/hashim-777x/tokenization-rwa/blob/master/functions/uploadSecrets.js): upload helper · Uploads sensitive credentials for the off-chain execution environment. · `functions/uploadSecrets.js`

### Tooling

Build, test, CI, and generated artifacts.

- [Broadcasts](https://github.com/hashim-777x/tokenization-rwa/tree/master/broadcast): deployment artifacts · Recorded transaction outputs and deployed addresses from Foundry runs. · `broadcast`
- [Foundry](https://github.com/hashim-777x/tokenization-rwa/blob/master/foundry.toml): build toolchain · Core Solidity build, test, and local chain tooling. · `foundry.toml`
- [Node package](https://github.com/hashim-777x/tokenization-rwa/blob/master/package.json): js tooling · JavaScript package metadata and dependency lockfile for the Functions side. · `package.json`
- [CI](https://github.com/hashim-777x/tokenization-rwa/blob/master/.github/workflows/test.yml): workflow · Automated Foundry test workflow in GitHub Actions. · `.github/workflows/test.yml`

### Dependencies

Vendored Solidity libraries used by the protocol.

- [Chainlink](https://github.com/hashim-777x/tokenization-rwa/tree/master/lib/chainlink-brownie-contracts): solidity lib · Vendored Chainlink contracts and integration primitives. · `lib/chainlink-brownie-contracts`
- [OpenZeppelin](https://github.com/hashim-777x/tokenization-rwa/tree/master/lib/openzeppelin-contracts): solidity lib · Standard contract primitives and utilities used by the Solidity layer. · `lib/openzeppelin-contracts`

## Connections

- Contracts → Chainlink: uses · Solidity contracts consume Chainlink integration primitives.
- Contracts → OpenZeppelin: uses · Solidity contracts rely on OpenZeppelin base components.
- Contracts → Data request: requests data · On-chain logic is designed to consume off-chain function output.
- Scripts → Contracts: deploys · Scripts orchestrate contract deployment and setup.
- Scripts → Broadcasts: records · Foundry scripts produce live transaction artifacts.
- Functions → Data request: contains · Package contains the primary external-data request code.
- Functions → Config: contains · Package contains runtime configuration for the function.
- Functions → Simulator: contains · Package contains local simulation support.
- Functions → Secrets: contains · Package contains secrets upload tooling.
- Simulator → Data request: simulates · Simulator exercises the request source logic.
- Config → Data request: configures · Configuration feeds the off-chain request code.
- Secrets → Data request: supports · Secrets are used by the off-chain execution path.
- Foundry → Contracts: builds · Foundry compiles the Solidity contracts.
- Foundry → Scripts: runs · Foundry executes deployment and operational scripts.
- Foundry → Broadcasts: emits · Foundry stores deployment output under broadcast artifacts.
- Node package → Functions: packages · Node tooling manages the off-chain JavaScript subsystem.
- CI → Foundry: verifies · CI runs the Foundry test workflow.
