# cartridge-gg/controller architecture

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

- Interactive diagram: https://gitdiagram.com/cartridge-gg/controller
- Repository: https://github.com/cartridge-gg/controller

## Overview

##### Project type and purpose
- This is a full-stack, mono-repo dApp SDK and sandboxed front-end suite for gaming-specific smart-contract wallets on StarkNet.
- Key purposes:
- Provide Rust and WASM SDKs for account interactions (`account_sdk`, `account-wasm`).
- Contain and compile Cairo contracts (`contracts`).
- Expose a TypeScript “Controller” SDK that embeds a sandboxed keychain iframe for signing (`controller`).
- Ship two user-facing front-ends: Keychain (at x.cartridge.gg) and Profile (at profile.cartridge.gg).
- Offer shared UI components (`ui`) and example apps (`examples`) that consume the Controller SDK.

##### File structure
- Top-level build tools: `pnpm-workspace.yaml`, `turbo.json`, `Makefile`, GitHub workflows.
- `/packages` directory hosts functional modules:
- `account_sdk` (Rust SDK), `account-wasm` (WASM build), `contracts` (Cairo), `controller` (TS SDK), `connector` (simple TS glue), `keychain`, `profile` (front-ends), `ui` (component library), plus lint and config packages.
- `examples` demonstrate Next.js, Svelte, Node.js integrations.
- Shared configs: ESLint, Prettier, Rust toolchain, Docker, GraphQL codegen.

##### README for insights
- README clearly spells out subprojects and their roles.
- Development workflow spins up four local servers: Controller example (Next.js, Svelte), Keychain, Profile.

##### Main components and relationships
a. On-chain Smart Contracts (StarkNet network)
- Deployed Cairo contracts under `/packages/contracts/controller` and `/packages/contracts/resolver`.
b. Rust & WASM SDK
- `account_sdk` (Rust crate) used in CLI or Node contexts.
- `account-wasm` compiled to WASM for browser usage by Keychain and examples.
c. Controller SDK (`packages/controller`)
- A TS library implementing StarkNet.js account interface.
- Internally loads a sandboxed Keychain iframe for signing.
d. Keychain Front-End (`packages/keychain`)
- React/Vite app served at localhost:3001 or x.cartridge.gg.
- Uses account-wasm to perform crypto, manages Passkey/WebAuthn and session tokens.
- Exposes an iframe messaging API consumed by Controller SDK.
e. Profile Front-End (`packages/profile`)
- React/Vite app served at localhost:3003 or profile.cartridge.gg.
- Uses Controller SDK for on-chain reads and uses `ui` and GraphQL APIs for off-chain data.
f. UI Library (`packages/ui`)
- Shared component and styling library used by Keychain, Profile, and Examples.
- Connects to GraphQL backends via auto-generated code in `utils/api`.
g. Backend APIs (GraphQL)
- Cartridge API endpoint (`/utils/api/cartridge/...`) provides user, balances, transfers, etc.
- Indexer API endpoint (`/utils/api/indexer/...`) provides event and token indexing.
h. Example Apps (`examples/next`, `examples/svelte`, `examples/node`)
- Import Controller SDK and UI, demonstrate integration and e2e tests.
i. CI/CD & Tooling
- GitHub Actions for build, test, deploy.
- Dockerfiles, codegen scripts, schema pulls.

[Developer Environment] | [Frontend Apps] | [SDKs & Libraries] | [Blockchain & Backends]
- Frontends: Keychain, Profile, Examples
- SDKs: Controller SDK (TS), account-wasm (WASM), account_sdk (Rust)
- UI Library
- Backends: GraphQL Cartridge API, GraphQL Indexer API, StarkNet Blockchain
- Examples → Controller SDK → Keychain iframe → account-wasm → Blockchain
- Controller SDK ↔ Keychain iframe (postMessage channel)
- Frontends & UI Library → GraphQL APIs (Cartridge & Indexer)
- Rust SDK → CLI / Node.js contexts → Blockchain

##### Architectural patterns and principles
- Monorepo managed by pnpm/Turbo: emphasize shared build and versioning.
- Micro-frontend sandbox: Keychain and Profile as isolated apps with iframe boundary.
- SDK composition: layering from low-level Rust → WASM → TS Controller → Frontend apps.
- Separation of concerns: On-chain logic (contracts) vs off-chain UI & data (GraphQL APIs).

##### Detail level
- Local development servers and ports for examples and frontends.
- Build scripts (Makefile, Dockerfile, GitHub workflows) near relevant components.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Subgraphs and modules

    subgraph "Developer Environment"
        PL1("pnpm-workspace.yaml"):::build
        PL2("turbo.json"):::build
        PL3("Makefile"):::build
        PL4(".github/workflows"):::build
    end

    subgraph "Frontend Apps"
        direction TB
        KC("Keychain Front-End\n(React/Vite)"):::frontend
        PR("Profile Front-End\n(React/Vite)"):::frontend

        subgraph "Examples"
            direction TB
            EX1("Next.js Example"):::frontend
            EX2("Svelte Example"):::frontend
            EX3("Node.js Example"):::frontend
        end
    end

    subgraph "SDKs & Libraries"
        direction TB
        RS("Rust SDK\n(account_sdk)"):::sdk
        WS("WASM SDK\n(account-wasm)"):::sdk
        CS("Controller TS SDK"):::sdk
        UI("Shared UI Library"):::sdk
    end

    subgraph "Backends & Blockchain"
        direction TB
        subgraph "Smart Contracts"
            CC("Cairo Contracts\ncontroller"):::backend
            CR("Cairo Contracts\nresolver"):::backend
        end
        API1("GraphQL Cartridge API"):::backend
        API2("GraphQL Indexer API"):::backend
        BC("StarkNet Blockchain"):::backend
    end

    %% Connections
    EX1 -->|"imports Controller SDK"| CS
    EX2 -->|"imports Controller SDK"| CS
    EX3 -->|"imports Controller SDK"| CS

    CS -->|"postMessage iframe"| KC
    KC -->|"uses WASM SDK"| WS
    WS -->|"JSON-RPC"| BC

    RS -->|"CLI/Node usage"| BC

    PR -->|"uses Controller SDK"| CS
    PR -->|"uses UI Library"| UI
    KC -->|"uses UI Library"| UI

    KC -->|"HTTP GraphQL"| API1
    PR -->|"HTTP GraphQL"| API1
    PR -->|"HTTP GraphQL"| API2
    UI -->|"auto-generated API clients"| API1
    UI -->|"auto-generated API clients"| API2

    CC -->|"on-chain deployment"| BC
    CR -->|"on-chain deployment"| BC

    %% Click Events
    click CC "https://github.com/cartridge-gg/controller/tree/main/packages/contracts/controller"
    click CR "https://github.com/cartridge-gg/controller/tree/main/packages/contracts/resolver"
    click RS "https://github.com/cartridge-gg/controller/tree/main/packages/account_sdk"
    click WS "https://github.com/cartridge-gg/controller/tree/main/packages/account-wasm"
    click CS "https://github.com/cartridge-gg/controller/tree/main/packages/controller/src"
    click CS "https://github.com/cartridge-gg/controller/blob/main/packages/controller/package.json"
    click KC "https://github.com/cartridge-gg/controller/tree/main/packages/keychain/src"
    click KC "https://github.com/cartridge-gg/controller/blob/main/packages/keychain/index.html"
    click KC "https://github.com/cartridge-gg/controller/blob/main/packages/keychain/package.json"
    click PR "https://github.com/cartridge-gg/controller/tree/main/packages/profile/src"
    click PR "https://github.com/cartridge-gg/controller/blob/main/packages/profile/index.html"
    click PR "https://github.com/cartridge-gg/controller/blob/main/packages/profile/package.json"
    click UI "https://github.com/cartridge-gg/controller/tree/main/packages/ui/src"
    click UI "https://github.com/cartridge-gg/controller/blob/main/packages/ui/package.json"
    click EX1 "https://github.com/cartridge-gg/controller/tree/main/examples/next"
    click EX2 "https://github.com/cartridge-gg/controller/tree/main/examples/svelte"
    click EX3 "https://github.com/cartridge-gg/controller/tree/main/examples/node"
    click PL1 "https://github.com/cartridge-gg/controller/blob/main/pnpm-workspace.yaml"
    click PL2 "https://github.com/cartridge-gg/controller/blob/main/turbo.json"
    click PL3 "https://github.com/cartridge-gg/controller/tree/main/Makefile"
    click PL4 "https://github.com/cartridge-gg/controller/tree/main/.github/workflows"
    click API1 "https://github.com/cartridge-gg/controller/tree/main/packages/ui/src/utils/api/cartridge"
    click API2 "https://github.com/cartridge-gg/controller/tree/main/packages/ui/src/utils/api/indexer"

    %% Styles
    classDef frontend fill:#ccf,stroke:#00f,stroke-width:2px;
    classDef sdk fill:#cfc,stroke:#0a0,stroke-width:2px;
    classDef backend fill:#fdd,stroke:#808,stroke-width:2px;
    classDef build fill:#eee,stroke:#999,stroke-width:2px;
```
