# jakiboy/revens architecture

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

- Interactive diagram: https://gitdiagram.com/jakiboy/revens
- Repository: https://github.com/jakiboy/revens

## Overview

1. **What this repo is**
   ReVens is a desktop launcher/catalog for reverse-engineering tools, built as an **Electron app with a React renderer**. The app itself is not the tooling; it manages a large, JSON-driven inventory of external utilities, downloads, and launch actions.

2. **Top-level runtime shape**
   The application is split into the classic Electron boundary:
   - **Main process** in `src/main/*` handles windows, app lifecycle, menus, tray, shortcuts, IPC, launching external tools, and AI plumbing.
   - **Renderer/UI** in `src/app/*` handles the visible launcher experience: tabs, sections, search, settings, downloads, notices, and help/about content.
   - **Preload** (`src/main/preload.js`) is the bridge between the two.

3. **Primary windows and app flow**
   Startup is centered around `src/main.js`, which loads the **splash screen** (`src/splash.html` / `src/main/splash.js`) and then the **main window** (`src/main.html`). This suggests a staged boot: splash while initializing, then the launcher UI once config and metadata are ready.

4. **Renderer subsystem**
   The renderer is organized around reusable UI components in `src/app/components/`. The visible app is composed from pieces like header/footer, tabs, sections, search, download, settings, notice, and AI/about panes. This is a catalog-style interface, not a document-driven site or single workflow app.

5. **Catalog/data-driven architecture**
   Most of the launcher content is driven by the files under `src/config/`:
   - `items.json` is the core package/tool catalog
   - `sections.json`, `strings.json`, `paths.json`, and `app.json` provide grouping, labels, and path/config metadata
   - `context.txt` and `prompt.txt` support the AI assistant
   This means the UI is largely data-driven: the catalog defines what appears, how it is grouped, and what actions are available.

6. **External tool boundary**
   ReVens acts as a **manager for external executables**. The repository contains the launcher and metadata, but the actual reverse-engineering tools are separate payloads/downloads. That boundary is important for the architecture diagram: the Electron app orchestrates tools, but does not embed their functionality.

7. **Launch/download subsystem**
   The main-process files `src/main/launcher.js` and `src/app/launcher.js` indicate a dedicated subsystem for resolving tool paths, starting executables, and likely coordinating downloads or updates. The README’s package-manager focus and “download separately” language reinforce that the app controls acquisition and execution rather than reimplementing tools.

8. **AI subsystem**
   `src/main/ai.js` and `src/app/components/ai.js` implement a local AI assistant backed by **Ollama**. The prompt/context assets in `src/config/` show that the assistant is configured from local text resources, with the main process mediating access and the renderer providing the chat UI.

9. **System integration**
   `src/main/menu.js`, `tray.js`, `shortcut.js`, and `ipc.js` are the app’s integration layer with the OS. These modules handle app-level affordances such as menus, tray icon behavior, hotkeys/shortcuts, and IPC routing between UI and privileged actions.

10. **Assets and shell/installer packaging**
   The repo includes substantial static assets under `src/app/assets/` plus installer materials in `assets/installer/` using **Inno Setup**. That indicates a packaged Windows desktop distribution, with branding/splash images, CSS themes, and installer-specific resources separate from application logic.

11. **Build and generation pipeline**
   The repo has a noticeable generation workflow:
   - root scripts: `init.sh`, `run.sh`, `build.sh`
   - catalog/tooling scripts in `scripts/` such as `generate.py`, `update_items.py`, `fix_items.py`, and test helpers
   - a README template under `scripts/Readme.md.tpl`
   This points to an architecture where the package catalog and documentation are generated from source data rather than maintained entirely by hand.

12. **Operational intent and constraints**
   The project is Windows-first, Electron-based, and oriented toward security/reversing workflows. Most package entries are legacy third-party tools with their own runtimes, so the app’s key responsibility is metadata management, download orchestration, launch control, and optional AI guidance—not heavy computation itself.

Main entry points: [`src/main`](https://github.com/jakiboy/revens/tree/main/src/main) (Main core), [`src/app/launcher.js`](https://github.com/jakiboy/revens/blob/main/src/app/launcher.js) (UI launcher), [`src/main/ipc.js`](https://github.com/jakiboy/revens/blob/main/src/main/ipc.js) (IPC router), [`src/main.js`](https://github.com/jakiboy/revens/blob/main/src/main.js) (App entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Electron runtime"]
  node_entry["App entry<br/>bootstrap<br/>[main.js]"]
  node_splash["Splash boot<br/>window boot<br/>[splash.js]"]
  node_preload["Preload bridge<br/>ipc bridge<br/>[preload.js]"]
  node_maincore{{"Main core<br/>electron main"}}
  node_ipc["IPC router<br/>message routing<br/>[ipc.js]"]
  node_launcher["Launch control<br/>tool orchestration<br/>[launcher.js]"]
  node_ai_main["AI backend<br/>ollama integration<br/>[ai.js]"]
  node_shell{{"OS integration<br/>menu tray shortcuts"}}
  node_ui_app["Launcher UI<br/>react renderer<br/>[app.js]"]
  node_ui_components{{"UI components<br/>renderer components"}}
  node_ui_launcher["UI launcher<br/>ui orchestration<br/>[launcher.js]"]
end

subgraph group_catalog["Catalog data"]
  node_catalog_items["Tool catalog<br/>json inventory<br/>[items.json]"]
  node_catalog_sections["Section map<br/>catalog metadata<br/>[sections.json]"]
  node_catalog_strings["Labels<br/>copy metadata<br/>[strings.json]"]
  node_catalog_paths["Path config<br/>path metadata<br/>[paths.json]"]
  node_catalog_ai["AI prompt set<br/>prompt assets"]
end

subgraph group_tools["Build and scripts"]
  node_generator["Generator scripts<br/>build pipeline<br/>[generate.py]"]
  node_readme_tpl["Docs template<br/>generated docs<br/>[Readme.md.tpl]"]
end

subgraph group_packaging["Installer and assets"]
  node_installer["Installer<br/>inno setup<br/>[ReVens.iss]"]
  node_branding[("Brand assets<br/>static assets")]
end

node_entry -->|"loads"| node_splash
node_entry -->|"creates"| node_maincore
node_maincore -->|"injects"| node_preload
node_preload -->|"forwards"| node_ipc
node_maincore -->|"manages"| node_shell
node_maincore -->|"orchestrates"| node_launcher
node_maincore -->|"serves"| node_ai_main
node_ipc -->|"requests"| node_launcher
node_ipc -->|"requests"| node_ai_main
node_ui_app -->|"composes"| node_ui_components
node_ui_app -->|"coordinates"| node_ui_launcher
node_ui_launcher -->|"renders"| node_catalog_items
node_ui_launcher -->|"groups"| node_catalog_sections
node_ui_launcher -->|"labels"| node_catalog_strings
node_ui_launcher -->|"resolves"| node_catalog_paths
node_ui_components -->|"shows"| node_catalog_ai
node_generator -->|"generates"| node_catalog_items
node_generator -->|"renders"| node_readme_tpl
node_installer -->|"packages"| node_branding
node_installer -->|"installs"| node_entry

click node_entry "https://github.com/jakiboy/revens/blob/main/src/main.js"
click node_splash "https://github.com/jakiboy/revens/blob/main/src/main/splash.js"
click node_preload "https://github.com/jakiboy/revens/blob/main/src/main/preload.js"
click node_maincore "https://github.com/jakiboy/revens/tree/main/src/main"
click node_ipc "https://github.com/jakiboy/revens/blob/main/src/main/ipc.js"
click node_launcher "https://github.com/jakiboy/revens/blob/main/src/main/launcher.js"
click node_ai_main "https://github.com/jakiboy/revens/blob/main/src/main/ai.js"
click node_shell "https://github.com/jakiboy/revens/tree/main/src/main"
click node_ui_app "https://github.com/jakiboy/revens/blob/main/src/app.js"
click node_ui_components "https://github.com/jakiboy/revens/tree/main/src/app/components"
click node_ui_launcher "https://github.com/jakiboy/revens/blob/main/src/app/launcher.js"
click node_catalog_items "https://github.com/jakiboy/revens/blob/main/src/config/items.json"
click node_catalog_sections "https://github.com/jakiboy/revens/blob/main/src/config/sections.json"
click node_catalog_strings "https://github.com/jakiboy/revens/blob/main/src/config/strings.json"
click node_catalog_paths "https://github.com/jakiboy/revens/blob/main/src/config/paths.json"
click node_catalog_ai "https://github.com/jakiboy/revens/tree/main/src/config"
click node_installer "https://github.com/jakiboy/revens/blob/main/assets/installer/ReVens.iss"
click node_branding "https://github.com/jakiboy/revens/tree/main/src/app/assets"
click node_generator "https://github.com/jakiboy/revens/blob/main/scripts/generate.py"
click node_readme_tpl "https://github.com/jakiboy/revens/blob/main/scripts/Readme.md.tpl"

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_entry,node_splash,node_preload,node_maincore,node_ipc,node_launcher,node_ai_main,node_shell,node_ui_app,node_ui_components,node_ui_launcher toneBlue
class node_catalog_items,node_catalog_sections,node_catalog_strings,node_catalog_paths,node_catalog_ai toneAmber
class node_generator,node_readme_tpl toneMint
class node_installer,node_branding toneRose
```

## Components

### Electron runtime

Main, preload, and renderer layers of the desktop app.

- [App entry](https://github.com/jakiboy/revens/blob/main/src/main.js): bootstrap · Starts Electron, loads the staged splash-to-main window flow. · `src/main.js`
- [Splash boot](https://github.com/jakiboy/revens/blob/main/src/main/splash.js): window boot · Initial splash screen and startup handoff logic. · `src/main/splash.js`
- [Preload bridge](https://github.com/jakiboy/revens/blob/main/src/main/preload.js): ipc bridge · Safe bridge between renderer code and privileged main-process APIs. · `src/main/preload.js`
- [Main core](https://github.com/jakiboy/revens/tree/main/src/main): electron main · Coordinates lifecycle, window creation, and app-wide orchestration. · `src/main`
- [IPC router](https://github.com/jakiboy/revens/blob/main/src/main/ipc.js): message routing · Routes renderer requests to privileged operations. · `src/main/ipc.js`
- [Launch control](https://github.com/jakiboy/revens/blob/main/src/main/launcher.js): tool orchestration · Resolves executable paths, starts external tools, and coordinates download-oriented actions. · `src/main/launcher.js`
- [AI backend](https://github.com/jakiboy/revens/blob/main/src/main/ai.js): ollama integration · Main-process access layer for the local AI assistant. · `src/main/ai.js`
- [OS integration](https://github.com/jakiboy/revens/tree/main/src/main): menu tray shortcuts · Menus, tray behavior, and global shortcut handling. · `src/main`
- [Launcher UI](https://github.com/jakiboy/revens/blob/main/src/app.js): react renderer · Primary renderer experience for browsing tools and settings. · `src/app.js`
- [UI components](https://github.com/jakiboy/revens/tree/main/src/app/components): renderer components · Header, tabs, sections, search, download, settings, notice, and about panes. · `src/app/components`
- [UI launcher](https://github.com/jakiboy/revens/blob/main/src/app/launcher.js): ui orchestration · Renderer-side coordination for catalog display and tool actions. · `src/app/launcher.js`

### Catalog data

JSON and prompt assets that drive the launcher UI and AI assistant.

- [Tool catalog](https://github.com/jakiboy/revens/blob/main/src/config/items.json): json inventory · Core data set describing tools, metadata, and launch entries. · `src/config/items.json`
- [Section map](https://github.com/jakiboy/revens/blob/main/src/config/sections.json): catalog metadata · Groups and organizes catalog content for the launcher. · `src/config/sections.json`
- [Labels](https://github.com/jakiboy/revens/blob/main/src/config/strings.json): copy metadata · UI strings and naming resources. · `src/config/strings.json`
- [Path config](https://github.com/jakiboy/revens/blob/main/src/config/paths.json): path metadata · Repository and runtime path definitions used by launcher logic. · `src/config/paths.json`
- [AI prompt set](https://github.com/jakiboy/revens/tree/main/src/config): prompt assets · Context and prompt resources used to shape local assistant behavior. · `src/config`

### Build and scripts

Generation, update, and packaging workflows.

- [Generator scripts](https://github.com/jakiboy/revens/blob/main/scripts/generate.py): build pipeline · Catalog generation, update, and validation scripts. · `scripts/generate.py`
- [Docs template](https://github.com/jakiboy/revens/blob/main/scripts/Readme.md.tpl): generated docs · Template used to render repository documentation from source data. · `scripts/Readme.md.tpl`

### Installer and assets

Desktop distribution resources and static branding assets.

- [Installer](https://github.com/jakiboy/revens/blob/main/assets/installer/ReVens.iss): inno setup · Windows installer packaging and release resources. · `assets/installer/ReVens.iss`
- [Brand assets](https://github.com/jakiboy/revens/tree/main/src/app/assets): static assets · Splash, theme, and installer artwork used by the desktop build. · `src/app/assets`

## Connections

- App entry → Splash boot: loads · Bootstraps the splash screen before the main launcher is ready.
- App entry → Main core: creates · Initializes the Electron application core and main window lifecycle.
- Main core → Preload bridge: injects · Connects the renderer to the privileged bridge.
- Preload bridge → IPC router: forwards · Exposes controlled IPC access to the renderer.
- Main core → OS integration: manages · Owns menus, tray behavior, and global shortcuts.
- Main core → Launch control: orchestrates · Delegates tool execution and path resolution.
- Main core → AI backend: serves · Provides backend access for the local AI assistant.
- IPC router → Launch control: requests · Routes UI actions to launch and download operations.
- IPC router → AI backend: requests · Routes chat and assistant operations to the backend.
- Launcher UI → UI components: composes · Builds the visible launcher from reusable renderer pieces.
- Launcher UI → UI launcher: coordinates · Uses renderer orchestration for catalog-driven interactions.
- UI launcher → Tool catalog: renders · Consumes the tool inventory to populate the launcher.
- UI launcher → Section map: groups · Uses section metadata to organize the catalog.
- UI launcher → Labels: labels · Uses copy and naming metadata in the UI.
- UI launcher → Path config: resolves · Uses path metadata for file and runtime resolution.
- UI components → AI prompt set: shows · AI and help surfaces are driven by local prompt resources.
- Generator scripts → Tool catalog: generates · Produces or updates the catalog source data.
- Generator scripts → Docs template: renders · Uses the documentation template during generation.
- Installer → Brand assets: packages · Bundles assets into the Windows installer.
- Installer → App entry: installs · Packages the Electron application for distribution.