# elder-plinius/p4rs3lt0ngv3 architecture

> Architecture diagram of the GitHub repository elder-plinius/p4rs3lt0ngv3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elder-plinius/p4rs3lt0ngv3
- Repository: https://github.com/elder-plinius/p4rs3lt0ngv3

## Overview

1. **Overall shape**
   - This repo is a **static browser app** for text transformation, decoding, steganography, and AI-assisted text operations.
   - The runnable artifact is generated into **`dist/`** by the build, then opened directly in a browser or served as static files.

2. **Frontend shell**
   - The UI is a **Vue 2.6** single-page app entrypointed by **`js/app.js`**.
   - Styling is split across **`css/style.css`** and **`css/notification.css`**.
   - The main HTML shell starts from **`index.template.html`**, then tool templates and scripts are injected during build.

3. **Tool-driven application architecture**
   - The app is organized around a **tool registry + tab system** rather than a single monolithic editor.
   - Core plumbing lives in **`js/core/toolRegistry.js`**, **`js/tools/Tool.js`**, and the many concrete tool classes under **`js/tools/`**.
   - Each tool owns a particular workflow: transform, decode, emoji steganography, tokenizer, splitter, prompt crafting, mutation lab, etc.

4. **Canonical transform engine**
   - The largest subsystem is the **transform library** under **`src/transformers/`**.
   - Transformers are grouped by domain: encodings, ciphers, Unicode styles, formatting, technical codes, fantasy scripts, ancient scripts, and visual transformations.
   - These modules are the source of truth for encode/decode behavior and are bundled into a browser-ready artifact during build.

5. **Transform execution pipeline**
   - Text flows from the UI into a selected tool, then into a transformer implementation.
   - Shared transform behavior is normalized through **`src/transformers/BaseTransformer.js`** and helper logic in **`js/core/transformOptions.js`**.
   - The transform layer is intentionally modular so both the browser UI and the Python CLI can invoke the same canonical behavior.

6. **Decoder subsystem**
   - Universal decoding is handled separately from normal transforms in **`js/core/decoder.js`**.
   - Decoder logic uses lexical analysis and format heuristics from **`js/core/lexemeAnalysis.js`** and related helpers to guess likely encodings or scripts.
   - This subsystem can also prefer the currently active transform before falling back to other decode candidates.

7. **Steganography and special text carriers**
   - Steganography support is split across **`js/core/steganography.js`**, the emoji data/config files, and specific transform modules for invisible or zero-width techniques.
   - Related generated or curated data lives in **`js/data/`**, such as emoji compatibility, glitch tokens, end sequences, and model lists.
   - The UI exposes these features through dedicated tools and advanced settings, with bit-order and carrier options affecting how payloads are embedded.

8. **AI/OpenRouter boundary**
   - Some tools are network-backed and depend on **OpenRouter**: AI translation, PromptCraft, Anti-Classifier, and optional decoder translation hints.
   - These tools are isolated from the offline transform engine; they share a locally stored API key but require external model access.
   - The repo treats AI features as optional augmentation, not a dependency for core offline functionality.

9. **Build and packaging pipeline**
   - Build scripts under **`build/`** assemble the app from source into a runnable static bundle.
   - Key build steps: generate the transformer index, bundle transforms, copy static assets, inject tool scripts/templates, and generate emoji data.
   - The build outputs into **`dist/`**, which becomes the only runtime artifact for the browser deployment.

10. **Tool templates and UI composition**
    - Each tool has an HTML template in **`templates/`**, and these templates are injected into the final page at build time.
    - This keeps tool structure declarative while the JavaScript side handles behavior and state.
    - Documentation in **`docs/`** describes the template system, tool architecture, and UI components, which is important for understanding how the tabs are composed.

11. **Runtime utilities and shared state**
    - Shared browser utilities live in **`js/utils/`** and cover clipboard, emoji handling, escaping, focus, history, notifications, and theming.
    - These utilities act as cross-cutting infrastructure for all tools, especially around copy history, auto-copy, keyboard shortcuts, and theme switching.
    - Configuration and constants in **`js/config/`** and data modules in **`js/data/`** feed both the UI and transform logic.

12. **Command-line companion**
    - The **`p4rs3lt0ngv3_cli/`** package is a Python CLI layer that reuses the existing Node transform runtime through a bridge.
    - The bridge script in **`scripts/cli_bridge.js`** allows the CLI to call the same canonical transforms without reimplementing them in Python.
    - This makes the repo effectively **dual-interface**: browser-first for users, CLI-first for automation, both backed by the same transform source.

13. **Testing boundaries**
    - JavaScript tests under **`tests/`** focus on decoder and steganography behavior.
    - Python end-to-end tests under **`python_tests/`** validate the CLI path.
    - The test split reflects the architecture: browser transform logic, decoder heuristics, and CLI bridging are distinct but connected subsystems.

14. **Diagram-friendly summary**
    - The main architectural flow is: **source transformers and tool modules → build pipeline → static dist bundle → browser UI/tools**.
    - AI-powered features form a side branch through **OpenRouter**, while the Python CLI forms another side branch through a **Node bridge** to the same transformer core.
    - The key boundaries are between **offline local transforms**, **networked AI tools**, and **CLI reuse of browser-native transform logic**.

Main entry points: [`src/transformers/BaseTransformer.js`](https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/src/transformers/BaseTransformer.js) (Base transformer), [`js/tools`](https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/js/tools) (Tools), [`build`](https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/build) (Build scripts), [`js/core/decoder.js`](https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/js/core/decoder.js) (Decoder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_browser["Browser app"]
  node_n_app["App shell<br/>Vue entry<br/>[app.js]"]
  node_n_registry["Tool registry<br/>tab routing<br/>[toolRegistry.js]"]
  node_n_tool_base["Tool base<br/>tool contract<br/>[Tool.js]"]
  node_n_tools["Tools"]
  node_n_ui_utils["UI utils<br/>shared browser utils"]
  node_n_decoder["Decoder<br/>heuristic decode<br/>[decoder.js]"]
  node_n_lexeme["Lexeme analysis<br/>decode heuristics<br/>[lexemeAnalysis.js]"]
  node_n_stego["Steganography<br/>carrier logic<br/>[steganography.js]"]
  node_n_topts["Transform options<br/>transform config"]
end

subgraph group_grp_transform["Transform core"]
  node_n_base["Base transformer<br/>transform API<br/>[BaseTransformer.js]"]
  node_n_encoding["Encodings<br/>transform domain"]
  node_n_cipher["Ciphers<br/>transform domain"]
  node_n_unicode["Unicode styles<br/>transform domain"]
  node_n_format["Format ops<br/>transform domain"]
  node_n_tech["Technical codes<br/>transform domain"]
  node_n_fantasy["Fantasy scripts<br/>transform domain"]
end

subgraph group_grp_build["Build pipeline"]
  node_n_build["Build scripts<br/>bundle pipeline"]
  node_n_templates["Templates<br/>html fragments"]
  node_n_dist[("Dist bundle<br/>static artifact")]
end

subgraph group_grp_cli["CLI companion"]
  node_n_cli_bridge["CLI bridge<br/>node bridge<br/>[cli_bridge.js]"]
  node_n_py_cli["Python CLI<br/>automation CLI"]
end

subgraph group_grp_tests["Tests"]
  node_n_js_tests["JS tests<br/>unit tests"]
  node_n_py_tests["Py tests<br/>e2e tests"]
end

node_n_app -->|"boots"| node_n_registry
node_n_registry -->|"instantiates"| node_n_tool_base
node_n_registry -->|"loads"| node_n_tools
node_n_tools -->|"uses"| node_n_decoder
node_n_tools -->|"uses"| node_n_stego
node_n_tools -->|"configures"| node_n_topts
node_n_tools -->|"shares"| node_n_ui_utils
node_n_decoder -->|"analyzes"| node_n_lexeme
node_n_decoder -->|"respects"| node_n_topts
node_n_stego -->|"encodes via"| node_n_encoding
node_n_stego -->|"uses"| node_n_format
node_n_base -->|"implements"| node_n_encoding
node_n_base -->|"implements"| node_n_cipher
node_n_base -->|"implements"| node_n_unicode
node_n_base -->|"implements"| node_n_format
node_n_base -->|"implements"| node_n_tech
node_n_base -->|"implements"| node_n_fantasy
node_n_build -->|"injects"| node_n_templates
node_n_build -->|"produces"| node_n_dist
node_n_build -->|"bundles"| node_n_encoding
node_n_build -->|"scripts"| node_n_tools
node_n_cli_bridge -->|"reuses"| node_n_base
node_n_py_cli -->|"calls"| node_n_cli_bridge
node_n_js_tests -->|"validates"| node_n_decoder
node_n_js_tests -->|"validates"| node_n_stego
node_n_py_tests -->|"verifies"| node_n_py_cli

click node_n_app "https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/js/app.js"
click node_n_registry "https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/js/core/toolRegistry.js"
click node_n_tool_base "https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/js/tools/Tool.js"
click node_n_tools "https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/js/tools"
click node_n_ui_utils "https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/js/utils"
click node_n_decoder "https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/js/core/decoder.js"
click node_n_lexeme "https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/js/core/lexemeAnalysis.js"
click node_n_stego "https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/js/core/steganography.js"
click node_n_topts "https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/js/core/transformOptions.js"
click node_n_base "https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/src/transformers/BaseTransformer.js"
click node_n_encoding "https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/src/transformers/encoding"
click node_n_cipher "https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/src/transformers/cipher"
click node_n_unicode "https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/src/transformers/unicode"
click node_n_format "https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/src/transformers/format"
click node_n_tech "https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/src/transformers/technical"
click node_n_fantasy "https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/src/transformers/fantasy"
click node_n_build "https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/build"
click node_n_templates "https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/templates"
click node_n_cli_bridge "https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/scripts/cli_bridge.js"
click node_n_py_cli "https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/p4rs3lt0ngv3_cli"
click node_n_js_tests "https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/tests"
click node_n_py_tests "https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/python_tests"

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_n_app,node_n_registry,node_n_tool_base,node_n_tools,node_n_ui_utils,node_n_decoder,node_n_lexeme,node_n_stego,node_n_topts toneBlue
class node_n_base,node_n_encoding,node_n_cipher,node_n_unicode,node_n_format,node_n_tech,node_n_fantasy toneAmber
class node_n_build,node_n_templates,node_n_dist toneMint
class node_n_cli_bridge,node_n_py_cli toneRose
class node_n_js_tests,node_n_py_tests toneIndigo
```

## Components

### Browser app

Static Vue app, tools, and shared browser utilities.

- [App shell](https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/js/app.js): Vue entry · Browser SPA entrypoint and runtime bootstrap. · `js/app.js`
- [Tool registry](https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/js/core/toolRegistry.js): tab routing · Registers tools and coordinates tab-level selection. · `js/core/toolRegistry.js`
- [Tool base](https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/js/tools/Tool.js): tool contract · Shared base class for all browser tools. · `js/tools/Tool.js`
- [Tools](https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/js/tools): UI tools · Concrete browser tools for transforms, decoding, steganography, tokenization, and AI-assisted workflows. · `js/tools`
- [UI utils](https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/js/utils): shared browser utils · Clipboard, history, focus, notifications, emoji, escaping, and theme helpers. · `js/utils`
- [Decoder](https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/js/core/decoder.js): heuristic decode · Universal decoding and candidate selection from lexical and format clues. · `js/core/decoder.js`
- [Lexeme analysis](https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/js/core/lexemeAnalysis.js): decode heuristics · Token and format analysis used to guess encodings and scripts. · `js/core/lexemeAnalysis.js`
- [Steganography](https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/js/core/steganography.js): carrier logic · Bit-packing and carrier handling for invisible, emoji, and other hidden-text channels. · `js/core/steganography.js`
- [Transform options](https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/js/core/transformOptions.js): transform config · Normalizes per-transform options shared by UI and runtime. · `js/core/transformOptions.js`

### Transform core

Canonical transformation engine and domain libraries.

- [Base transformer](https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/src/transformers/BaseTransformer.js): transform API · Common transformer interface and shared behavior. · `src/transformers/BaseTransformer.js`
- [Encodings](https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/src/transformers/encoding): transform domain · Base64, hex, URL, Unicode points, emoji encoding, and related encoders/decoders. · `src/transformers/encoding`
- [Ciphers](https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/src/transformers/cipher): transform domain · Classical and modern cipher implementations. · `src/transformers/cipher`
- [Unicode styles](https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/src/transformers/unicode): transform domain · Styled, mirrored, and symbol-heavy Unicode transformations. · `src/transformers/unicode`
- [Format ops](https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/src/transformers/format): transform domain · Normalization, shuffling, casing, whitespace, and steganographic text formatting. · `src/transformers/format`
- [Technical codes](https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/src/transformers/technical): transform domain · Morse, NATO, braille, semaphore, and other signaling systems. · `src/transformers/technical`
- [Fantasy scripts](https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/src/transformers/fantasy): transform domain · Fictional writing systems and transliteration styles. · `src/transformers/fantasy`

### Build pipeline

Scripts that assemble the static bundle and generated data.

- [Build scripts](https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/build): bundle pipeline · Generates indexes, bundles transforms, injects templates, and copies static assets. · `build`
- [Templates](https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/templates): html fragments · Tool templates injected into the final page during build. · `templates`
- **Dist bundle**: static artifact · Generated browser-ready runtime output.

### CLI companion

Python interface that reuses the Node transform runtime.

- [CLI bridge](https://github.com/elder-plinius/p4rs3lt0ngv3/blob/main/scripts/cli_bridge.js): node bridge · Executes canonical Node transforms for the Python CLI. · `scripts/cli_bridge.js`
- [Python CLI](https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/p4rs3lt0ngv3_cli): automation CLI · Python command-line interface layered over the Node bridge. · `p4rs3lt0ngv3_cli`

### Tests

JavaScript and Python test boundaries.

- [JS tests](https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/tests): unit tests · Decoder and steganography behavior checks. · `tests`
- [Py tests](https://github.com/elder-plinius/p4rs3lt0ngv3/tree/main/python_tests): e2e tests · End-to-end validation of the CLI path. · `python_tests`

## Connections

- App shell → Tool registry: boots · App bootstrap wires the registry and tabs.
- Tool registry → Tool base: instantiates · Registry manages tool instances through the shared base contract.
- Tool registry → Tools: loads · Concrete tools are registered as the main UI capabilities.
- Tools → Decoder: uses · Decode-oriented tools route into the universal decoder.
- Tools → Steganography: uses · Steganography tools coordinate payload encoding and extraction.
- Tools → Transform options: configures · Tools pass normalized options into transform execution.
- Tools → UI utils: shares · All tools rely on common browser utilities and state helpers.
- Decoder → Lexeme analysis: analyzes · Heuristic decode selection is driven by lexical analysis.
- Decoder → Transform options: respects · Decoder behavior is shaped by shared transform options.
- Steganography → Encodings: encodes via · Hidden-text carriers often reuse encoding transformers.
- Steganography → Format ops: uses · Whitespace and zero-width transforms support carrier behavior.
- Base transformer → Encodings: implements · Domain transformers conform to the shared base API.
- Base transformer → Ciphers: implements · Cipher transformers are built on the shared base API.
- Base transformer → Unicode styles: implements · Unicode styling transformers follow the shared base API.
- Base transformer → Format ops: implements · Formatting transforms share the common transformer surface.
- Base transformer → Technical codes: implements · Technical-code transformers use the shared base API.
- Base transformer → Fantasy scripts: implements · Fantasy-script transformers also follow the shared base API.
- Build scripts → Templates: injects · Build steps splice tool templates into the final HTML shell.
- Build scripts → Dist bundle: produces · The build pipeline emits the static browser artifact.
- Build scripts → Encodings: bundles · Transform sources are bundled into the runtime output.
- Build scripts → Tools: scripts · Tool scripts are assembled as part of the build.
- CLI bridge → Base transformer: reuses · The bridge invokes the same canonical transform implementation.
- Python CLI → CLI bridge: calls · Python commands delegate execution to the Node bridge.
- JS tests → Decoder: validates · JS tests cover decode heuristics and special text handling.
- JS tests → Steganography: validates · JS tests cover steganography options and behavior.
- Py tests → Python CLI: verifies · Python tests exercise the CLI end to end.
