# mizcausevic-dev/promptforge architecture

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

- Interactive diagram: https://gitdiagram.com/mizcausevic-dev/promptforge
- Repository: https://github.com/mizcausevic-dev/promptforge

## Overview

#### Purpose and principal workflow
PromptForge is a browser-only collaborative prompt library: people browse approved prompts, fill named variables, preview and copy resolved text, and create versioned revisions for review. The initiating actor is a **Browser user**; the HTML shell loads the application, which routes interactions through a single-page UI and persists the shared data model in browser storage. Mock model responses are stored demo results, not calls to model providers.

#### Components

##### Browser application
- **Browser user** — `null` — Uses the prompt library, edits and tests prompts, and can switch among client-side mock accounts; there is no real authentication.
- **HTML shell** — `index.html` — Hosts the SPA and its browser-side assets.
- **SPA controller and router** — `app.js` — Owns initialization, hash routing, event handling, shared state, and rendering of route-selected views; README documents routes including browse, prompt detail, editing, folders, and moderation.
- **Prompt data and demo fixtures** — `seed.js` — Supplies mock users and initial prompts, versions, comments, test cases, folders, and favorites through `window.PF_SEED`.

##### Prompt library and editing
- **Discovery and prompt detail** — `app.js` — Supports public browsing, search and filters, prompt detail, version history, attribution, comments, variable forms, and resolved previews; the excerpt shows search over title, current body, category, tags, and author.
- **Prompt authoring and versioning** — `app.js` — Handles creation and revision editing; README documents that saves preserve earlier bodies as versions, and the excerpt shows a live preview while editing.
- **Variable resolution and copy validation** — `app.js` — Extracts named variables, fills previews, and validates missing values before copy, as documented and reflected in the exported pure-logic test API.
- **Organization and user activity** — `app.js` — Manages favorites, folders, tags, and upvotes; the excerpt shows favorite and upvote mutations followed by persistence and rerendering.
- **Moderation workflow** — `app.js` — Implements draft, pending, approved, and flagged states, with admin actions and non-approved prompts excluded from public browse according to the README.

##### Evaluation and data exchange
- **Test-case evaluation** — `app.js` — Stores per-prompt cases and mock responses for version comparisons; the excerpt wires “run test” actions, and README describes side-by-side PASS/FAIL results and reruns.
- **Import, export, and data validation** — `app.js` — Provides JSON exchange and validates/merges imported data; the sampled framework-free test file exercises validation and merge behavior.
- **Browser persistence and migration** — `app.js` — Maintains the application database in browser storage and includes a schema migration chokepoint; README identifies `localStorage` key `promptforge.db.v1` as the persistence mechanism.

#### Relationships
- **Browser user -> HTML shell**: opens the application in a browser; README documents opening `index.html` directly or serving it.
- **HTML shell -> SPA controller and router**: hosts the SPA entry point; README identifies the shell and application files.
- **SPA controller and router -> Prompt data and demo fixtures**: initializes demo data from `window.PF_SEED` on first run, as documented by the seed module.
- **SPA controller and router -> Browser persistence and migration**: loads and saves application state; README documents localStorage persistence and the source excerpt shows migration and storage helpers.
- **Browser user -> SPA controller and router**: navigates routes and triggers UI actions through browser interaction; the excerpt shows global event handling and hash-based routing is documented.
- **SPA controller and router -> Discovery and prompt detail**: renders route-selected library views; README documents browsing and detail capabilities.
- **Discovery and prompt detail -> Variable resolution and copy validation**: resolves prompt variables for preview and validates missing values before copying; README documents this detail-page workflow.
- **Browser user -> Prompt authoring and versioning**: submits prompt creations or revisions through the editor; the excerpt shows the save action and README documents versioned saves.
- **Prompt authoring and versioning -> Browser persistence and migration**: persists prompt mutations through the application state path; the excerpt shows mutation handlers calling `saveDB()`.
- **Browser user -> Moderation workflow**: admin actions approve or flag prompts; the excerpt shows approve and flag controls.
- **Moderation workflow -> Browser persistence and migration**: persists moderation changes through the application’s save path; README documents moderation states and the excerpt wires moderation actions.
- **Browser user -> Test-case evaluation**: runs test cases from the prompt detail view; the excerpt binds run-test controls.
- **Test-case evaluation -> Browser persistence and migration**: stores test-case results with prompt state; README documents per-prompt test cases and reruns.
- **Browser user -> Organization and user activity**: toggles favorites and upvotes or organizes prompts; the excerpt shows those actions.
- **Organization and user activity -> Browser persistence and migration**: saves these state mutations; the excerpt shows `saveDB()` after favorite and upvote changes.
- **Browser user -> Import, export, and data validation**: initiates JSON exchange; README documents import/export.
- **Import, export, and data validation -> Browser persistence and migration**: merges validated import data into application state; the sampled tests exercise `mergeImport` and schema-version stamping.

#### Coverage limits
The `app.js` sample omits substantial sections, so exact initialization order, storage fallback details, and several action implementations cannot be confirmed. README documents features not fully visible in the excerpts; relationships above distinguish that documentation from direct source evidence. No external model provider, server, or real identity system is established.

Main entry points: [`app.js`](https://github.com/mizcausevic-dev/promptforge/blob/master/app.js) (Browser persistence and migration), [`index.html`](https://github.com/mizcausevic-dev/promptforge/blob/master/index.html) (HTML shell), [`seed.js`](https://github.com/mizcausevic-dev/promptforge/blob/master/seed.js) (Prompt data and demo fixtures)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser_runtime["Browser Runtime"]
  node_html_shell["HTML shell<br/>Entry document"]
  node_spa_controller["SPA controller and router<br/>[app.js]"]
  node_demo_fixtures["Prompt data and demo fixtures<br/>Seed module"]
end

subgraph group_prompt_workflows["Prompt Workflows"]
  node_discovery_detail["Discovery and prompt detail<br/>UI workflow"]
  node_authoring_versioning["Prompt authoring and versioning<br/>UI workflow"]
  node_variable_resolution["Variable resolution and copy validation<br/>UI workflow"]
  node_organization_activity["Organization and user activity<br/>UI workflow"]
  node_moderation["Moderation workflow<br/>UI workflow"]
end

subgraph group_evaluation_exchange["Evaluation &amp; Data"]
  node_test_evaluation["Test-case evaluation<br/>Evaluation workflow"]
  node_import_export["Import, export, and data validation<br/>Data exchange workflow"]
  node_browser_persistence[("Browser persistence and migration<br/>Browser storage")]
end

node_browser_user["Browser user<br/>External actor"]

node_browser_user -->|"opens"| node_html_shell
node_html_shell -->|"hosts"| node_spa_controller
node_spa_controller -->|"initializes from"| node_demo_fixtures
node_spa_controller -->|"loads and saves"| node_browser_persistence
node_browser_user -->|"interacts with"| node_spa_controller
node_spa_controller -->|"renders views"| node_discovery_detail
node_discovery_detail -->|"resolves and validates"| node_variable_resolution
node_browser_user -->|"submits edits"| node_authoring_versioning
node_authoring_versioning -->|"persists changes"| node_browser_persistence
node_browser_user -->|"moderates prompts"| node_moderation
node_moderation -->|"persists changes"| node_browser_persistence
node_browser_user -->|"runs tests"| node_test_evaluation
node_test_evaluation -->|"stores results"| node_browser_persistence
node_browser_user -->|"organizes prompts"| node_organization_activity
node_organization_activity -->|"persists changes"| node_browser_persistence
node_browser_user -->|"exchanges JSON"| node_import_export
node_import_export -->|"merges imported data"| node_browser_persistence

click node_html_shell "https://github.com/mizcausevic-dev/promptforge/blob/master/index.html"
click node_spa_controller "https://github.com/mizcausevic-dev/promptforge/blob/master/app.js"
click node_demo_fixtures "https://github.com/mizcausevic-dev/promptforge/blob/master/seed.js"
click node_discovery_detail "https://github.com/mizcausevic-dev/promptforge/blob/master/app.js"
click node_authoring_versioning "https://github.com/mizcausevic-dev/promptforge/blob/master/app.js"
click node_variable_resolution "https://github.com/mizcausevic-dev/promptforge/blob/master/app.js"
click node_organization_activity "https://github.com/mizcausevic-dev/promptforge/blob/master/app.js"
click node_moderation "https://github.com/mizcausevic-dev/promptforge/blob/master/app.js"
click node_test_evaluation "https://github.com/mizcausevic-dev/promptforge/blob/master/app.js"
click node_import_export "https://github.com/mizcausevic-dev/promptforge/blob/master/app.js"
click node_browser_persistence "https://github.com/mizcausevic-dev/promptforge/blob/master/app.js"

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_html_shell,node_spa_controller,node_demo_fixtures,node_browser_user toneBlue
class node_discovery_detail,node_authoring_versioning,node_variable_resolution,node_organization_activity,node_moderation toneAmber
class node_test_evaluation,node_import_export,node_browser_persistence toneMint
```

## Components

### Browser Runtime

SPA entry point and demo data.

- [HTML shell](https://github.com/mizcausevic-dev/promptforge/blob/master/index.html): Entry document · `index.html`
- [SPA controller and router](https://github.com/mizcausevic-dev/promptforge/blob/master/app.js): SPA controller · `app.js`
- [Prompt data and demo fixtures](https://github.com/mizcausevic-dev/promptforge/blob/master/seed.js): Seed module · `seed.js`

### Prompt Workflows

Library, authoring, organization, and moderation features.

- [Discovery and prompt detail](https://github.com/mizcausevic-dev/promptforge/blob/master/app.js): UI workflow · `app.js`
- [Prompt authoring and versioning](https://github.com/mizcausevic-dev/promptforge/blob/master/app.js): UI workflow · `app.js`
- [Variable resolution and copy validation](https://github.com/mizcausevic-dev/promptforge/blob/master/app.js): UI workflow · `app.js`
- [Organization and user activity](https://github.com/mizcausevic-dev/promptforge/blob/master/app.js): UI workflow · `app.js`
- [Moderation workflow](https://github.com/mizcausevic-dev/promptforge/blob/master/app.js): UI workflow · `app.js`

### Evaluation & Data

Test evaluation, JSON exchange, and browser persistence.

- [Test-case evaluation](https://github.com/mizcausevic-dev/promptforge/blob/master/app.js): Evaluation workflow · `app.js`
- [Import, export, and data validation](https://github.com/mizcausevic-dev/promptforge/blob/master/app.js): Data exchange workflow · `app.js`
- [Browser persistence and migration](https://github.com/mizcausevic-dev/promptforge/blob/master/app.js): Browser storage · `app.js`

### Other components

- **Browser user**: External actor

## Connections

- Browser user → HTML shell: opens
- HTML shell → SPA controller and router: hosts
- SPA controller and router → Prompt data and demo fixtures: initializes from
- SPA controller and router → Browser persistence and migration: loads and saves
- Browser user → SPA controller and router: interacts with
- SPA controller and router → Discovery and prompt detail: renders views
- Discovery and prompt detail → Variable resolution and copy validation: resolves and validates
- Browser user → Prompt authoring and versioning: submits edits
- Prompt authoring and versioning → Browser persistence and migration: persists changes
- Browser user → Moderation workflow: moderates prompts
- Moderation workflow → Browser persistence and migration: persists changes
- Browser user → Test-case evaluation: runs tests
- Test-case evaluation → Browser persistence and migration: stores results
- Browser user → Organization and user activity: organizes prompts
- Organization and user activity → Browser persistence and migration: persists changes
- Browser user → Import, export, and data validation: exchanges JSON
- Import, export, and data validation → Browser persistence and migration: merges imported data