# mmcoms/penware architecture

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

- Interactive diagram: https://gitdiagram.com/mmcoms/penware
- Repository: https://github.com/mmcoms/penware

## Overview

PenWare is a browser-based firmware release monitor and device guide for security-research hardware. Users browse a catalog, scan watched feeds, compare results with locally saved baselines, and receive in-app alerts; device pages also provide install/recovery guidance and backup options. A separate six-hour watcher checks catalog feeds and opens an issue for new releases. The sampled code supports the app, scan, persistence, catalog-import, and USB-backup links; watcher details and some external wiring are documented in the README rather than shown in sampled source.

Main entry points: [`src/components/penware/penware-app.tsx`](https://github.com/mmcoms/penware/blob/main/src/components/penware/penware-app.tsx) (Fleet and device UI), [`src/lib/penware/check.ts`](https://github.com/mmcoms/penware/blob/main/src/lib/penware/check.ts) (Feed checker), [`src/routeTree.gen.ts`](https://github.com/mmcoms/penware/blob/main/src/routeTree.gen.ts) (Route tree), [`src/components/penware/device-backup.tsx`](https://github.com/mmcoms/penware/blob/main/src/components/penware/device-backup.tsx) (Device backup panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App experience"]
  node_index["Home route<br/>[index.tsx]"]
  node_appscreen["Fleet and device UI<br/>[penware-app.tsx]"]
  node_router["Router setup<br/>[router.tsx]"]
  node_route_tree["Route tree<br/>[routeTree.gen.ts]"]
  node_root["App shell<br/>[__root.tsx]"]
  node_errors["Error display"]
end

subgraph group_firmware["Firmware monitoring"]
  node_checker["Feed checker<br/>[check.ts]"]
  node_watcher["Scheduled watcher<br/>[watch.mjs]"]
end

subgraph group_data["Catalog and state"]
  node_catalog_file["Device catalog<br/>[catalog.json]"]
  node_catalog_loader["Catalog loader<br/>[catalog.ts]"]
  node_store[("Browser state<br/>[store.ts]")]
end

subgraph group_backup["Backup tools"]
  node_backup_panel["Device backup panel<br/>[device-backup.tsx]"]
end

node_user(("Visitor"))
node_github_releases{{"GitHub releases"}}
node_biscuit_feed{{"Biscuit feed"}}
node_hak5_feed{{"Hak5 feed"}}
node_issues{{"GitHub issues"}}
node_remote_catalog{{"Remote catalog"}}
node_usb_device{{"ESP32 over USB"}}
node_local_files["Downloaded backup"]

node_user -->|"opens"| node_index
node_index -->|"renders"| node_appscreen
node_router -->|"uses"| node_route_tree
node_router -->|"configures errors"| node_errors
node_route_tree -->|"registers route"| node_root
node_route_tree -->|"registers route"| node_index
node_appscreen -->|"requests scans"| node_checker
node_checker -->|"fetches releases"| node_github_releases
node_checker -->|"fetches manifests"| node_biscuit_feed
node_checker -->|"fetches firmware"| node_hak5_feed
node_appscreen -->|"reads and updates"| node_store
node_store -->|"persists locally"| node_user
node_catalog_file -->|"loaded by"| node_catalog_loader
node_appscreen -->|"uses built-ins"| node_catalog_loader
node_appscreen -->|"imports remote catalog"| node_checker
node_checker -->|"fetches catalog"| node_remote_catalog
node_watcher -->|"reads catalog"| node_catalog_file
node_watcher -->|"opens issue"| node_issues
node_appscreen -->|"renders"| node_backup_panel
node_backup_panel -->|"reads flash"| node_usb_device
node_backup_panel -->|"saves backup"| node_local_files

click node_index "https://github.com/mmcoms/penware/blob/main/src/routes/index.tsx"
click node_appscreen "https://github.com/mmcoms/penware/blob/main/src/components/penware/penware-app.tsx"
click node_router "https://github.com/mmcoms/penware/blob/main/src/router.tsx"
click node_route_tree "https://github.com/mmcoms/penware/blob/main/src/routeTree.gen.ts"
click node_root "https://github.com/mmcoms/penware/blob/main/src/routes/__root.tsx"
click node_errors "https://github.com/mmcoms/penware/blob/main/src/lib/error-component.tsx"
click node_checker "https://github.com/mmcoms/penware/blob/main/src/lib/penware/check.ts"
click node_watcher "https://github.com/mmcoms/penware/blob/main/scripts/watch.mjs"
click node_catalog_file "https://github.com/mmcoms/penware/blob/main/catalog.json"
click node_catalog_loader "https://github.com/mmcoms/penware/blob/main/src/lib/penware/catalog.ts"
click node_store "https://github.com/mmcoms/penware/blob/main/src/lib/penware/store.ts"
click node_backup_panel "https://github.com/mmcoms/penware/blob/main/src/components/penware/device-backup.tsx"

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_index,node_appscreen,node_router,node_route_tree,node_root,node_errors toneBlue
class node_checker,node_watcher toneAmber
class node_catalog_file,node_catalog_loader,node_store toneMint
class node_backup_panel toneRose
class node_user,node_github_releases,node_biscuit_feed,node_hak5_feed,node_issues,node_remote_catalog,node_usb_device,node_local_files toneIndigo
```

## Components

### App experience

- [Home route](https://github.com/mmcoms/penware/blob/main/src/routes/index.tsx): `src/routes/index.tsx`
- [Fleet and device UI](https://github.com/mmcoms/penware/blob/main/src/components/penware/penware-app.tsx): `src/components/penware/penware-app.tsx`
- [Router setup](https://github.com/mmcoms/penware/blob/main/src/router.tsx): `src/router.tsx`
- [Route tree](https://github.com/mmcoms/penware/blob/main/src/routeTree.gen.ts): `src/routeTree.gen.ts`
- [App shell](https://github.com/mmcoms/penware/blob/main/src/routes/__root.tsx): `src/routes/__root.tsx`
- [Error display](https://github.com/mmcoms/penware/blob/main/src/lib/error-component.tsx): `src/lib/error-component.tsx`

### Firmware monitoring

- [Feed checker](https://github.com/mmcoms/penware/blob/main/src/lib/penware/check.ts): `src/lib/penware/check.ts`
- [Scheduled watcher](https://github.com/mmcoms/penware/blob/main/scripts/watch.mjs): `scripts/watch.mjs`

### Catalog and state

- [Device catalog](https://github.com/mmcoms/penware/blob/main/catalog.json): `catalog.json`
- [Catalog loader](https://github.com/mmcoms/penware/blob/main/src/lib/penware/catalog.ts): `src/lib/penware/catalog.ts`
- [Browser state](https://github.com/mmcoms/penware/blob/main/src/lib/penware/store.ts): `src/lib/penware/store.ts`

### Backup tools

- [Device backup panel](https://github.com/mmcoms/penware/blob/main/src/components/penware/device-backup.tsx): `src/components/penware/device-backup.tsx`

### Other components

- **Visitor**
- **GitHub releases**
- **Biscuit feed**
- **Hak5 feed**
- **GitHub issues**
- **Remote catalog**
- **ESP32 over USB**
- **Downloaded backup**

## Connections

- Visitor → Home route: opens (evidence: `README.md`)
- Home route → Fleet and device UI: renders (evidence: `src/routes/index.tsx`)
- Router setup → Route tree: uses (evidence: `src/router.tsx`)
- Router setup → Error display: configures errors (evidence: `src/router.tsx`)
- Route tree → App shell: registers route (evidence: `src/routeTree.gen.ts`)
- Route tree → Home route: registers route (evidence: `src/routeTree.gen.ts`)
- Fleet and device UI → Feed checker: requests scans (evidence: `src/components/penware/penware-app.tsx`)
- Feed checker → GitHub releases: fetches releases (evidence: `src/lib/penware/check.ts`)
- Feed checker → Biscuit feed: fetches manifests (evidence: `src/lib/penware/check.ts`)
- Feed checker → Hak5 feed: fetches firmware (evidence: `src/lib/penware/check.ts`)
- Fleet and device UI → Browser state: reads and updates (evidence: `src/components/penware/penware-app.tsx`)
- Browser state → Visitor: persists locally (evidence: `README.md`)
- Device catalog → Catalog loader: loaded by (evidence: `src/lib/penware/catalog.ts`)
- Fleet and device UI → Catalog loader: uses built-ins (evidence: `src/components/penware/penware-app.tsx`)
- Fleet and device UI → Feed checker: imports remote catalog (evidence: `src/components/penware/penware-app.tsx`)
- Feed checker → Remote catalog: fetches catalog (evidence: `README.md`)
- Scheduled watcher → Device catalog: reads catalog (evidence: `README.md`)
- Scheduled watcher → GitHub issues: opens issue (evidence: `README.md`)
- Fleet and device UI → Device backup panel: renders (evidence: `src/components/penware/penware-app.tsx`)
- Device backup panel → ESP32 over USB: reads flash (evidence: `src/components/penware/device-backup.tsx`)
- Device backup panel → Downloaded backup: saves backup (evidence: `src/components/penware/device-backup.tsx`)
