# beyondmrk/super-ai-gen architecture

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

- Interactive diagram: https://gitdiagram.com/beyondmrk/super-ai-gen
- Repository: https://github.com/beyondmrk/super-ai-gen

## Overview

super-ai-gen is a guarded CLI pipeline for generating client-specific stills and video clips with Higgsfield. The main workflow is preflight checks and project setup, manifest preparation, dry-run cost estimation, then staged generation with resumable outputs. Separate safeguards enforce client/model and creative constraints. An optional Windows account router selects and validates the correct Higgsfield login. Edges follow README statements or shown source references and calls; several router internals are represented from their module documentation and indexed references rather than full source inspection.

Main entry points: [`fire.py`](https://github.com/beyondmrk/super-ai-gen/blob/master/fire.py) (Generation runner), [`prefire.py`](https://github.com/beyondmrk/super-ai-gen/blob/master/prefire.py) (Preflight gate), [`hf-accounts/router/router.py`](https://github.com/beyondmrk/super-ai-gen/blob/master/hf-accounts/router/router.py) (Account router), [`hf-accounts/router/accounts.py`](https://github.com/beyondmrk/super-ai-gen/blob/master/hf-accounts/router/accounts.py) (Login manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Generation pipeline"]
  node_prefire["Preflight gate<br/>[prefire.py]"]
  node_marker["Preflight marker"]
  node_manifest["Shot manifest"]
  node_fire["Generation runner<br/>[fire.py]"]
  node_costs["Cost estimates<br/>[fire.py]"]
  node_outputs[("Generated assets")]
  node_run_state["Resume state"]
end

subgraph group_guardrails["Run safeguards"]
  node_registry["Client registry"]
  node_panel_refs["Reference panels<br/>[panels.py]"]
  node_cast_lock["Cast consistency<br/>[castlock.py]"]
  node_cli_recovery["CLI recovery<br/>[hf_call.py]"]
end

subgraph group_account_router["Account routing"]
  node_router_launcher["CLI launcher<br/>[hfstub.cs]"]
  node_router["Account router<br/>[router.py]"]
  node_routing_rules["Login selection<br/>[hfacct.py]"]
  node_strict_checks["Strict spend checks<br/>[strict.py]"]
  node_stamps[("Check stamps<br/>[stamps.py]")]
  node_account_check["Account checker<br/>[hf_check.py]"]
end

subgraph group_router_admin["Account administration"]
  node_account_admin["Login manager<br/>[accounts.py]"]
  node_router_install["Router installer<br/>[install.py]"]
end

node_operator(("Operator"))
node_drive[("Google Drive")]
node_hf_cli["Higgsfield CLI"]

node_operator -->|"starts preflight"| node_prefire
node_prefire -->|"reads client"| node_registry
node_prefire -->|"checks and creates folders"| node_drive
node_prefire -->|"checks account and workspace"| node_hf_cli
node_prefire -->|"writes gate result"| node_marker
node_operator -->|"prepares shots"| node_manifest
node_operator -->|"runs dry-run or stage"| node_fire
node_fire -->|"reads shots"| node_manifest
node_fire -->|"checks gate result"| node_marker
node_fire -->|"resolves client policy"| node_registry
node_fire -->|"calculates stage cost"| node_costs
node_fire -->|"submits generations"| node_hf_cli
node_fire -->|"writes stills and clips"| node_outputs
node_fire -->|"records resumable state"| node_run_state
node_fire -->|"expands references"| node_panel_refs
node_fire -->|"uses cast lint"| node_cast_lock
node_fire -->|"delegates CLI handling"| node_cli_recovery
node_router_launcher -->|"hands off CLI call"| node_router
node_router -->|"selects login"| node_routing_rules
node_router -->|"checks strict policy"| node_strict_checks
node_strict_checks -->|"validates spend stamp"| node_stamps
node_account_check -->|"queries account"| node_hf_cli
node_account_check -->|"writes passing check"| node_stamps
node_account_admin -->|"uses account checks"| node_account_check
node_account_admin -->|"uses routing registry"| node_routing_rules
node_account_admin -->|"uses stamp policy"| node_strict_checks
node_router_install -->|"uses router configuration"| node_routing_rules
node_router -->|"runs real CLI"| node_hf_cli

click node_prefire "https://github.com/beyondmrk/super-ai-gen/blob/master/prefire.py"
click node_registry "https://github.com/beyondmrk/super-ai-gen/blob/master/clients.example.json"
click node_manifest "https://github.com/beyondmrk/super-ai-gen/blob/master/manifest_template.json"
click node_fire "https://github.com/beyondmrk/super-ai-gen/blob/master/fire.py"
click node_costs "https://github.com/beyondmrk/super-ai-gen/blob/master/fire.py"
click node_panel_refs "https://github.com/beyondmrk/super-ai-gen/blob/master/panels.py"
click node_cast_lock "https://github.com/beyondmrk/super-ai-gen/blob/master/castlock.py"
click node_cli_recovery "https://github.com/beyondmrk/super-ai-gen/blob/master/hf_call.py"
click node_router_launcher "https://github.com/beyondmrk/super-ai-gen/blob/master/hf-accounts/router/hfstub.cs"
click node_router "https://github.com/beyondmrk/super-ai-gen/blob/master/hf-accounts/router/router.py"
click node_routing_rules "https://github.com/beyondmrk/super-ai-gen/blob/master/hf-accounts/router/hfacct.py"
click node_strict_checks "https://github.com/beyondmrk/super-ai-gen/blob/master/hf-accounts/router/strict.py"
click node_stamps "https://github.com/beyondmrk/super-ai-gen/blob/master/hf-accounts/router/stamps.py"
click node_account_check "https://github.com/beyondmrk/super-ai-gen/blob/master/hf-accounts/router/hf_check.py"
click node_account_admin "https://github.com/beyondmrk/super-ai-gen/blob/master/hf-accounts/router/accounts.py"
click node_router_install "https://github.com/beyondmrk/super-ai-gen/blob/master/hf-accounts/router/install.py"

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_prefire,node_marker,node_manifest,node_fire,node_costs,node_outputs,node_run_state toneBlue
class node_registry,node_panel_refs,node_cast_lock,node_cli_recovery,node_drive toneAmber
class node_router_launcher,node_router,node_routing_rules,node_strict_checks,node_stamps,node_account_check toneMint
class node_account_admin,node_router_install toneRose
class node_operator,node_hf_cli toneIndigo
```

## Components

### Generation pipeline

- [Preflight gate](https://github.com/beyondmrk/super-ai-gen/blob/master/prefire.py): `prefire.py`
- **Preflight marker**
- [Shot manifest](https://github.com/beyondmrk/super-ai-gen/blob/master/manifest_template.json): `manifest_template.json`
- [Generation runner](https://github.com/beyondmrk/super-ai-gen/blob/master/fire.py): `fire.py`
- [Cost estimates](https://github.com/beyondmrk/super-ai-gen/blob/master/fire.py): `fire.py`
- **Generated assets**
- **Resume state**

### Run safeguards

- [Client registry](https://github.com/beyondmrk/super-ai-gen/blob/master/clients.example.json): `clients.example.json`
- [Reference panels](https://github.com/beyondmrk/super-ai-gen/blob/master/panels.py): `panels.py`
- [Cast consistency](https://github.com/beyondmrk/super-ai-gen/blob/master/castlock.py): `castlock.py`
- [CLI recovery](https://github.com/beyondmrk/super-ai-gen/blob/master/hf_call.py): `hf_call.py`

### Account routing

- [CLI launcher](https://github.com/beyondmrk/super-ai-gen/blob/master/hf-accounts/router/hfstub.cs): `hf-accounts/router/hfstub.cs`
- [Account router](https://github.com/beyondmrk/super-ai-gen/blob/master/hf-accounts/router/router.py): `hf-accounts/router/router.py`
- [Login selection](https://github.com/beyondmrk/super-ai-gen/blob/master/hf-accounts/router/hfacct.py): `hf-accounts/router/hfacct.py`
- [Strict spend checks](https://github.com/beyondmrk/super-ai-gen/blob/master/hf-accounts/router/strict.py): `hf-accounts/router/strict.py`
- [Check stamps](https://github.com/beyondmrk/super-ai-gen/blob/master/hf-accounts/router/stamps.py): `hf-accounts/router/stamps.py`
- [Account checker](https://github.com/beyondmrk/super-ai-gen/blob/master/hf-accounts/router/hf_check.py): `hf-accounts/router/hf_check.py`

### Account administration

- [Login manager](https://github.com/beyondmrk/super-ai-gen/blob/master/hf-accounts/router/accounts.py): `hf-accounts/router/accounts.py`
- [Router installer](https://github.com/beyondmrk/super-ai-gen/blob/master/hf-accounts/router/install.py): `hf-accounts/router/install.py`

### Other components

- **Operator**
- **Google Drive**
- **Higgsfield CLI**

## Connections

- Operator → Preflight gate: starts preflight (evidence: `README.md`)
- Preflight gate → Client registry: reads client (evidence: `README.md`)
- Preflight gate → Google Drive: checks and creates folders (evidence: `README.md`)
- Preflight gate → Higgsfield CLI: checks account and workspace (evidence: `prefire.py`)
- Preflight gate → Preflight marker: writes gate result (evidence: `README.md`)
- Operator → Shot manifest: prepares shots (evidence: `README.md`)
- Operator → Generation runner: runs dry-run or stage (evidence: `README.md`)
- Generation runner → Shot manifest: reads shots (evidence: `README.md`)
- Generation runner → Preflight marker: checks gate result (evidence: `README.md`)
- Generation runner → Client registry: resolves client policy (evidence: `fire.py`)
- Generation runner → Cost estimates: calculates stage cost (evidence: `README.md`)
- Generation runner → Higgsfield CLI: submits generations (evidence: `README.md`)
- Generation runner → Generated assets: writes stills and clips (evidence: `README.md`)
- Generation runner → Resume state: records resumable state (evidence: `README.md`)
- Generation runner → Reference panels: expands references (evidence: `fire.py`)
- Generation runner → Cast consistency: uses cast lint (evidence: `fire.py`)
- Generation runner → CLI recovery: delegates CLI handling (evidence: `fire.py`)
- CLI launcher → Account router: hands off CLI call (evidence: `hf-accounts/router/router.py`)
- Account router → Login selection: selects login (evidence: `hf-accounts/router/router.py`)
- Account router → Strict spend checks: checks strict policy (evidence: `hf-accounts/router/router.py`)
- Strict spend checks → Check stamps: validates spend stamp (evidence: `hf-accounts/router/strict.py`)
- Account checker → Higgsfield CLI: queries account (evidence: `hf-accounts/router/hf_check.py`)
- Account checker → Check stamps: writes passing check (evidence: `hf-accounts/router/hf_check.py`)
- Login manager → Account checker: uses account checks (evidence: `hf-accounts/router/accounts.py`)
- Login manager → Login selection: uses routing registry (evidence: `hf-accounts/router/accounts.py`)
- Login manager → Strict spend checks: uses stamp policy (evidence: `hf-accounts/router/accounts.py`)
- Router installer → Login selection: uses router configuration (evidence: `hf-accounts/router/install.py`)
- Account router → Higgsfield CLI: runs real CLI (evidence: `hf-accounts/router/router.py`)