# omque/riverspider-powershell architecture

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

- Interactive diagram: https://gitdiagram.com/omque/riverspider-powershell
- Repository: https://github.com/omque/riverspider-powershell

## Overview

##### Project type and purpose
- This is a single‐purpose, command-line orchestration tool written in PowerShell (“riverSpider-PowerShell”).
- It automates a multi-step workflow:
- Takes a TTPASM input file (assembly code)
- Submits it to a Google Sheets–based assembler Web App
- Downloads the assembled RAM image
- Launches LogiSim (Java GUI) on local circuit files to simulate the processor
- Captures the execution trace and sends it back to the Web App for human-readable analysis

##### File structure
Top-level files only—no subdirectories:
- submit.ps1         – the main CLI orchestration script
- secretString.txt   – stores your Google Apps Script password
- webapp.url         – stores the deployed Web App URL
- test.ttpasm        – sample TTPASM program for testing
- logisim310.jar / .circ files (externally acquired)
- LICENSE, README.md

There are no separate frontend/backend directories or microservices – it’s a single PowerShell script that interacts with:
- Local filesystem (configs, circuit files, TTPASM, output)
- External Web App (HTTP requests)
- Local Java process (LogiSim)

##### README for additional insights
- Specifies prerequisites: Java 8+, PowerShell 7.x
- Outlines a 7-step installation & configuration process (copy circuit files, configure Google Sheet Apps Script, place URL in webapp.url, adjust submit.ps1 constants)
- Describes the workflow and external dependencies (Google Sheets Web App, LogiSim)

##### Main components & interactions (
A. User Terminal (PowerShell 7.x)
B. submit.ps1 (PowerShell Orchestrator)
C. Local Configuration & Inputs
- secretString.txt (password)
- webapp.url (Web App endpoint)
- test.ttpasm or any .ttpasm file
- Circuit files: alu.circ, processorXXXX.circ, regbank.circ
D. External Service: Google Apps Script Web App
- Exposes REST endpoints to assemble TTPASM and analyze logs
- Backed by a Google Sheet “Assembler”
E. Local Java Process: LogiSim (logisim310.jar)
- Loads the circuit files, runs the RAM image, produces a trace log
F. Output: Analysis in Google Sheet, local console logs

Interactions (data flow):
1. User calls: .\submit.ps1 <program.ttpasm>
2. submit.ps1 reads secretString.txt & webapp.url
3. submit.ps1 POSTs TTPASM code + auth to Web App → receives assembled RAM image
4. submit.ps1 writes RAM image locally
5. submit.ps1 spawns Java: java -jar logisim310.jar -tty RAM_image → generates trace log
6. submit.ps1 POSTs trace log + auth to Web App → receives human-readable analysis
7. submit.ps1 prints final results to console and/or writes to files

##### Architectural patterns & design principles
- Orchestration / pipeline pattern: a single script coordinates multiple tools and services
- Separation of concerns:
- Config files (secretString.txt, webapp.url) isolated from code
- Core logic in submit.ps1; external dependencies injected via config
- Externalization of business logic: the assembler and analyzer live in a Google Sheet Web App, keeping heavy logic out of PowerShell

– Clear labels: e.g., “submit.ps1 Orchestrator,” “Google Assembler Web App,” “LogiSim (Java)”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Components
    User["User Terminal (PowerShell)"]:::local
    PS["submit.ps1 Orchestrator"]:::local

    subgraph "Local File System"
        CONF1["secretString.txt"]:::fs
        CONF2["webapp.url"]:::fs
        INPUT["test.ttpasm (or any .ttpasm)"]:::fs
        CIRCF["Circuit Files\n(alu.circ, processorXXXX.circ,\nregbank.circ)"]:::fs
        RAM["RAM Image"]:::fs
        TRACE["Trace Log"]:::fs
        README["README.md"]:::fs
        LICENSE["LICENSE"]:::fs
    end

    EXTW["Google Assembler Web App"]:::external
    GS["Google Sheets (Assembler)"]:::external
    JAVA["LogiSim (Java)"]:::java
    CONSOLE["Local Console Output"]:::local

    %% Data Flow
    User -->|1 Call .\submit.ps1 <program.ttpasm>| PS
    PS -->|2 Read auth| CONF1
    PS -->|2 Read endpoint| CONF2
    PS -->|2 Read input| INPUT
    PS -->|3 POST TTPASM+auth| EXTW
    EXTW --> GS
    GS --> EXTW
    EXTW -->|3 Return RAM image| PS
    PS -->|4 Write RAM image| RAM
    PS -->|5 Spawn LogiSim| JAVA
    JAVA -->|Generates trace| TRACE
    PS -->|6 POST trace+auth| EXTW
    EXTW --> GS
    GS --> EXTW
    EXTW -->|6 Return analysis| PS
    PS -->|7 Print results| CONSOLE

    %% Legend
    subgraph "Legend"
        L1["Local Script/Terminal"]:::local
        L2["Filesystem/Config"]:::fs
        L3["External Service"]:::external
        L4["Execution Engine"]:::java
    end

    %% Click Events
    click PS "https://github.com/omque/riverspider-powershell/blob/main/submit.ps1"
    click CONF2 "https://github.com/omque/riverspider-powershell/blob/main/webapp.url"
    click CONF1 "https://github.com/omque/riverspider-powershell/blob/main/secretString.txt"
    click INPUT "https://github.com/omque/riverspider-powershell/blob/main/test.ttpasm"
    click README "https://github.com/omque/riverspider-powershell/blob/main/README.md"
    click LICENSE "https://github.com/omque/riverspider-powershell/tree/main/LICENSE"

    %% Styles
    classDef local fill:#bbf,stroke:#333,stroke-width:1px
    classDef fs fill:#ccc,stroke:#333,stroke-width:1px
    classDef external fill:#add8e6,stroke:#333,stroke-width:1px
    classDef java fill:#ffa500,stroke:#333,stroke-width:1px
```
