# furryr/csense architecture

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

- Interactive diagram: https://gitdiagram.com/furryr/csense
- Repository: https://github.com/furryr/csense

## Overview

##### Project type and purpose
- CSense is a **single-page web application** (pure front-end) that loads and executes CCW (scratch-like) scripts in a sandbox, analyzes them for security vulnerabilities, and displays results.
- No explicit “backend” folder: all networking is done client-side via API wrappers (`src/api/ccwdata.js`, `src/api/vmapi.js`).

##### File structure to find architectural components
Top-level folders and their roles:
- `src/api/`
– CCW chain data client (`ccwdata.js`)
– Virtual machine API client (`vmapi.js`)
- `src/base/`
– Core engine glue (Monaco editor integration, scene manager, global state)
- `src/sandbox/`
– Secure execution environment (TypeScript bridge + JS sandbox runner)
- `src/scene/`
– Individual UI “scenes” or pages (home, about, project, result overlays, etc.)
- `src/overlay/`
– Floating UI components (identity prompt, result window)
- `src/util/`
– Helpers (cookies, encryption, DOM injection, window helpers)
- `src/asset/`
– Static cert, other assets
Build tooling:
- `script/*.mjs` for bundling headers & build steps
- `tsup.config.*.ts` & `tsconfig.json` for compilation
- `package.json`, ESLint/Prettier configs

##### README for additional context
- CSense is an **open-source CCW security auditing tool**.
- No server-side component; the tool runs entirely in the browser.
- It relies on external CCW APIs (chain data + VM execution services).

##### Main components
A. Browser-hosted front-end (container)
– UI Layer
- Scene Manager (from `src/base/scene.js`)
- Scenes (`src/scene/*.js`)
- Overlays (`src/overlay/*.js`)
– Editor & Sandbox
- Monaco Editor integration (`src/base/monaco.js`)
- Sandbox Runner (`src/sandbox/index.js`, `sandbox.ts`, `bridge.ts`)
– State & Utilities
- Global State (`src/base/state.js`)
- Utilities (`src/util/*.js`)
– Asset Loader
- Certs, static files (`src/asset/cert.pem`)
B. External Services (over HTTPS)
– CCW Data API (`src/api/ccwdata.js`)
– CCW VM Execution API (`src/api/vmapi.js`)
C. Build Pipeline (developer tooling, outside browser)
– TSUP bundler (`tsup.config.*.ts`)
– Build scripts (`script/build.mjs`, `script/header.mjs`)
– NPM scripts in `package.json`

##### Relationships and data flows
1. User opens the SPA → Browser loads bundled JS (via `index.js`).
2. Scene Manager renders the Home scene.
3. User writes or loads a CCW script in Monaco Editor.
4. Upon “analyze” action:
- Sandbox bridge sends script to sandbox runner → isolates execution.
- Sandbox runner invokes VM API (`vmapi.js`) to execute/inspect.
- Potentially fetches data from Chain Data API (`ccwdata.js`).
5. Results returned → Overlay/Result component displays vulnerabilities.
6. Utilities (cookie, encryption) manage user identity or persisted settings.

##### Architectural patterns & principles
- Modular front-end with clear separation:
- **Presentation** (Scenes/Overlays)
- **Business Logic** (Sandbox + API modules)
- **Infrastructure/Utilities**
- Sandbox isolation for untrusted code execution.
- Single-page, event-driven scene manager.
- Build-time bundling for shipping a single JS artifact.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    EP["Entry Point"]:::init
    click EP "https://github.com/furryr/csense/blob/main/src/index.js"

    %% Browser App Container
    subgraph "Browser App (SPA)"
        %% UI Layer
        subgraph "UI Layer"
            SM["Scene Manager"]:::ui
            click SM "https://github.com/furryr/csense/blob/main/src/base/scene.js"
            HS["Home Scene"]:::ui
            click HS "https://github.com/furryr/csense/blob/main/src/scene/home.js"
            AS["About Scene"]:::ui
            click AS "https://github.com/furryr/csense/blob/main/src/scene/about.js"
            PS["Project Scene"]:::ui
            click PS "https://github.com/furryr/csense/blob/main/src/scene/project.js"
            SS["Script Scene"]:::ui
            click SS "https://github.com/furryr/csense/blob/main/src/scene/script.js"
            CDS["CCW Data Scene"]:::ui
            click CDS "https://github.com/furryr/csense/blob/main/src/scene/ccwdata.js"
            ES["Economy Scene"]:::ui
            click ES "https://github.com/furryr/csense/blob/main/src/scene/economy.js"
            EPS["Economy Pool Scene"]:::ui
            click EPS "https://github.com/furryr/csense/blob/main/src/scene/economyPool.js"
            LS["Leaderboard Scene"]:::ui
            click LS "https://github.com/furryr/csense/blob/main/src/scene/leaderboard.js"
            AchS["Achievement Scene"]:::ui
            click AchS "https://github.com/furryr/csense/blob/main/src/scene/achievement.js"
            MS["MMO Scene"]:::ui
            click MS "https://github.com/furryr/csense/blob/main/src/scene/mmo.js"
            SprS["Sprite Scene"]:::ui
            click SprS "https://github.com/furryr/csense/blob/main/src/scene/sprite.js"
            IP["Identity Prompt Overlay"]:::ui
            click IP "https://github.com/furryr/csense/blob/main/src/overlay/identity.js"
            RO["Result Display Overlay"]:::ui
            click RO "https://github.com/furryr/csense/blob/main/src/overlay/result.js"
        end

        %% Editor & Sandbox
        subgraph "Editor & Sandbox"
            ME["Monaco Editor"]:::logic
            click ME "https://github.com/furryr/csense/blob/main/src/base/monaco.js"
            SB["Sandbox Runner"]:::logic
            click SB "https://github.com/furryr/csense/blob/main/src/sandbox/index.js"
            BR["TypeScript Bridge"]:::logic
            click BR "https://github.com/furryr/csense/blob/main/src/sandbox/bridge.ts"
            SI["Sandbox Implementation"]:::logic
            click SI "https://github.com/furryr/csense/blob/main/src/sandbox/sandbox.ts"
        end

        %% State & Utilities
        subgraph "State & Utilities"
            GS["Global State"]:::logic
            click GS "https://github.com/furryr/csense/blob/main/src/base/state.js"
            CU["Cookie Utilities"]:::util
            click CU "https://github.com/furryr/csense/blob/main/src/util/cookie.js"
            EU["Encryption Utilities"]:::util
            click EU "https://github.com/furryr/csense/blob/main/src/util/encryption.js"
            DI["DOM Injection Helpers"]:::util
            click DI "https://github.com/furryr/csense/blob/main/src/util/inject.js"
            WH["Window Helpers"]:::util
            click WH "https://github.com/furryr/csense/blob/main/src/util/window.js"
        end

        AL["Asset Loader (cert.pem)"]:::util
        click AL "https://github.com/furryr/csense/blob/main/src/asset/cert.pem"
    end

    %% External Services
    subgraph "External CCW Services"
        API1["Chain Data API"]:::external
        click API1 "https://github.com/furryr/csense/blob/main/src/api/ccwdata.js"
        API2["VM Execution API"]:::external
        click API2 "https://github.com/furryr/csense/blob/main/src/api/vmapi.js"
    end

    %% Build Pipeline
    subgraph "Build Pipeline"
        DEV["tsup.config.dev.ts"]:::build
        click DEV "https://github.com/furryr/csense/blob/main/tsup.config.dev.ts"
        REL["tsup.config.release.ts"]:::build
        click REL "https://github.com/furryr/csense/blob/main/tsup.config.release.ts"
        BS1["Build Script: build.mjs"]:::build
        click BS1 "https://github.com/furryr/csense/blob/main/script/build.mjs"
        BS2["Build Script: header.mjs"]:::build
        click BS2 "https://github.com/furryr/csense/blob/main/script/header.mjs"
        NPM["NPM Config (package.json)"]:::build
        click NPM "https://github.com/furryr/csense/blob/main/package.json"
    end

    %% Actors
    User["User"]:::actor

    %% Data Flows
    User -->|opens SPA| EP
    EP -->|loads App| SM
    SM -->|renders| HS
    SM --> AS
    SM --> PS
    SM --> SS
    SM --> CDS
    SM --> ES
    SM --> EPS
    SM --> LS
    SM --> AchS
    SM --> MS
    SM --> SprS
    SM --> IP
    SM --> RO

    SM -->|integrates| ME
    ME -->|user code| SB
    SB -->|execute script| API2
    SB -->|fetch CCW blocks| API1
    API2 -->|execution result| SB
    API1 -->|chain data| SB
    SB -->|analysis result| RO
    GS --> SM
    GS --> SB
    AL --> SM

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef logic fill:#DFFFE0,stroke:#28a745,color:#22863a;
    classDef util fill:#F0F8FF,stroke:#6a737d,color:#586069;
    classDef external fill:#FFE8B0,stroke:#d18616,color:#d18616;
    classDef build fill:#E8E8E8,stroke:#6a737d,color:#586069;
    classDef actor fill:#F5E6FF,stroke:#6f42c1,color:#6f42c1;
    classDef init fill:#FFFFFF,stroke:#000000,color:#000000;
```
