# brweinstein/corsa architecture

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

- Interactive diagram: https://gitdiagram.com/brweinstein/corsa
- Repository: https://github.com/brweinstein/corsa

## Overview

##### Project type and purpose
- This is an educational, client-side web application—a full-stack project in the sense that it includes a Rust/WASM “backend” core and a Next.js/React “frontend” UI.

##### File structure
Top level:
- rust/ – Cargo project with src/lib.rs, src/number_theory.rs, src/rsa.rs, src/util.rs
- web/ – Next.js app (App Router) with React components, styles, tests, plus build configs (package.json, next.config.js, tailwind.config.ts)
- README.md, LICENSE, .gitignore

Observations:
- rust/ is purely computational logic. It’s packaged to WebAssembly via wasm-bindgen (build script in web/package.json).
- web/ contains:
– src/app: Next.js entry points (layout.tsx, page.tsx, head.tsx)
– src/components and nested panels for visualizations and controls
– src/lib: small wrappers for WASM calls (wasm.ts) and helper functions (num.ts)
– public/pkg (not shown) holds the compiled WASM artifacts
- Tests are split: `cargo test` for Rust, Vitest/RTL for the web.

##### README for additional insights
- Tech stack is explicitly called out: Rust→WASM, Next.js/React/TS, Tailwind, Vitest.
- Build instructions: wasm-pack build step, then npm install and npm run dev.
- No external database or API services—everything runs in the browser.

##### Main components and relationships
a. Rust core (Cargo project)
– Exposes number_theory and RSA functions via wasm-bindgen
– Output: .wasm binary + JS glue in web/public/pkg
b. Web application (Next.js)
– Server‐side: Node.js/Next.js build and static generation (app router)
– Client‐side: React components that import the WASM module and call into the Rust logic
c. UI components
– Panels (PrimesPanel, EncryptDecryptPanel, VisualizersPanel, etc.)
– Visualizers (CircleVisualizer, TwoLineVisualizer) render SVG/canvas
– StepController and Panel orchestrate user inputs and render cycles
d. Build pipeline
– wasm-pack (Cargo → WASM)
– npm scripts (bundle JS/TSX, integrate WASM, run dev server)
e. Developer environment
– Local dev machine runs both Cargo and Node toolchains
– Tests: Rust testing vs. Vitest/RTL

##### Architectural patterns and design principles
- Separation of concerns:
- Number theory & RSA logic entirely in Rust (strongly typed, tested in cargo).
- UI and rendering in Next.js/React (type-safe TSX, CSS modules/Tailwind).
- Module boundaries: WASM as a library boundary between compute and presentation.
- Progressive enhancement: fallback JS stub if WASM package missing.
- Componentized UI: each panel/visualizer is isolated, reusable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Machine
    subgraph "Developer Machine"
        direction TB
        CargoToml["Cargo.toml"]:::buildTools
        LibRs["lib.rs"]:::wasm
        NumberTheory["number_theory.rs"]:::wasm
        RsaRs["rsa.rs"]:::wasm
        UtilRs["util.rs"]:::wasm
        WasmPack["wasm-pack"]:::buildTools
        NodeNpm["npm/Next.js build"]:::buildTools
    end

    %% Build Pipeline
    subgraph "Build Pipeline"
        direction TB
        CargoToml -->|compile| WasmPack
        LibRs --> WasmPack
        NumberTheory --> WasmPack
        RsaRs --> WasmPack
        UtilRs --> WasmPack
        WasmPack -->|generates| WasmPkg["web/public/pkg (WASM artifacts)"]:::wasm
        NodeNpm -->|bundles| WebAssets["Static Assets (JS/CSS)"]:::server
    end

    %% Server Layer
    subgraph "Web Server (Next.js)"
        direction TB
        NextConfig["next.config.js"]:::server
        PackageJson["package.json"]:::buildTools
        TailwindConfig["tailwind.config.ts"]:::buildTools
        WebAssets
    end

    %% Client Layer
    subgraph "Browser Client"
        direction TB
        Layout["layout.tsx"]:::client
        Page["page.tsx"]:::client
        HeadComp["head.tsx"]:::client
        WasmWrapper["wasm.ts"]:::wasm
        NumUtils["num.ts"]:::buildTools
        PanelComp["Panel.tsx"]:::client
        StepController["StepController.tsx"]:::client
        TwoLineVis["TwoLineVisualizer.tsx"]:::client
        CircleVis["CircleVisualizer.tsx"]:::client
        DerivedPanel["DerivedPanel.tsx"]:::client
        EncryptDecryptPanel["EncryptDecryptPanel.tsx"]:::client
        PrimesPanel["PrimesPanel.tsx"]:::client
        TextConverterPanel["TextConverterPanel.tsx"]:::client
        VisualizersPanel["VisualizersPanel.tsx"]:::client
        GlobalsCSS["globals.css"]:::client
    end

    %% Testing Infrastructure
    subgraph "Testing Infrastructure"
        direction TB
        CargoTest["cargo test"]:::test
        VitestSetup["vitest.setup.ts"]:::test
        PanelSpec["panel-collapsible.spec.tsx"]:::test
        WasmWiringSpec["wasm-wiring.spec.ts"]:::test
    end

    %% Connections
    DeveloperMachine -->|builds WASM| BuildPipeline
    BuildPipeline -->|deploy assets| WebServer
    WebServer -->|serves| BrowserClient
    BrowserClient -->|loads| WasmPkg
    BrowserClient -->|imports| WasmWrapper
    BrowserClient -->|calls| LibRs
    BrowserClient -->|uses utils| NumUtils
    Layout --> Page
    Page --> HeadComp
    Page --> PanelComp
    PanelComp --> StepController
    PanelComp --> DerivedPanel
    PanelComp --> EncryptDecryptPanel
    PanelComp --> PrimesPanel
    PanelComp --> TextConverterPanel
    PanelComp --> VisualizersPanel
    VisualizersPanel --> TwoLineVis
    VisualizersPanel --> CircleVis
    BrowserClient --> GlobalsCSS

    CargoTest --> LibRs
    PanelSpec --> PanelComp
    WasmWiringSpec --> WasmWrapper

    %% Click Events
    click CargoToml "https://github.com/brweinstein/corsa/blob/main/rust/Cargo.toml"
    click LibRs "https://github.com/brweinstein/corsa/blob/main/rust/src/lib.rs"
    click NumberTheory "https://github.com/brweinstein/corsa/blob/main/rust/src/number_theory.rs"
    click RsaRs "https://github.com/brweinstein/corsa/blob/main/rust/src/rsa.rs"
    click UtilRs "https://github.com/brweinstein/corsa/blob/main/rust/src/util.rs"
    click WasmWrapper "https://github.com/brweinstein/corsa/blob/main/web/src/lib/wasm.ts"
    click NumUtils "https://github.com/brweinstein/corsa/blob/main/web/src/lib/num.ts"
    click Layout "https://github.com/brweinstein/corsa/blob/main/web/src/app/layout.tsx"
    click Page "https://github.com/brweinstein/corsa/blob/main/web/src/app/page.tsx"
    click HeadComp "https://github.com/brweinstein/corsa/blob/main/web/src/app/head.tsx"
    click PanelComp "https://github.com/brweinstein/corsa/blob/main/web/src/components/Panel.tsx"
    click StepController "https://github.com/brweinstein/corsa/blob/main/web/src/components/StepController.tsx"
    click TwoLineVis "https://github.com/brweinstein/corsa/blob/main/web/src/components/TwoLineVisualizer.tsx"
    click CircleVis "https://github.com/brweinstein/corsa/blob/main/web/src/components/.trash/CircleVisualizer.tsx"
    click DerivedPanel "https://github.com/brweinstein/corsa/blob/main/web/src/components/panels/DerivedPanel.tsx"
    click EncryptDecryptPanel "https://github.com/brweinstein/corsa/blob/main/web/src/components/panels/EncryptDecryptPanel.tsx"
    click PrimesPanel "https://github.com/brweinstein/corsa/blob/main/web/src/components/panels/PrimesPanel.tsx"
    click TextConverterPanel "https://github.com/brweinstein/corsa/blob/main/web/src/components/panels/TextConverterPanel.tsx"
    click VisualizersPanel "https://github.com/brweinstein/corsa/blob/main/web/src/components/panels/VisualizersPanel.tsx"
    click PackageJson "https://github.com/brweinstein/corsa/blob/main/web/package.json"
    click NextConfig "https://github.com/brweinstein/corsa/blob/main/web/next.config.js"
    click TailwindConfig "https://github.com/brweinstein/corsa/blob/main/web/tailwind.config.ts"
    click GlobalsCSS "https://github.com/brweinstein/corsa/blob/main/web/src/styles/globals.css"
    click PanelSpec "https://github.com/brweinstein/corsa/blob/main/web/src/test/panel-collapsible.spec.tsx"
    click WasmWiringSpec "https://github.com/brweinstein/corsa/blob/main/web/src/test/wasm-wiring.spec.ts"
    click VitestSetup "https://github.com/brweinstein/corsa/blob/main/web/src/test/vitest.setup.ts"

    %% Styles
    classDef buildTools fill:#cccccc,stroke:#333,stroke-width:1px
    classDef server fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef client fill:#90EE90,stroke:#333,stroke-width:1px
    classDef wasm fill:#FFA500,stroke:#333,stroke-width:1px
    classDef test fill:#f9e79f,stroke:#333,stroke-width:1px
```
