# jovo-jovi/b2s-brand-to-shelf architecture

> Architecture diagram of the GitHub repository jovo-jovi/b2s-brand-to-shelf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jovo-jovi/b2s-brand-to-shelf
- Repository: https://github.com/jovo-jovi/b2s-brand-to-shelf

## Overview

#### Purpose and Current State
B2S is a planned consolidation of six Balance Bites single-file HTML business tools into a white-label web application. The target runtime is Vite, React, and TypeScript, deployed as a static site on Vercel. This repository currently contains the product definition, migration evidence, operating process, and frozen legacy sources rather than the target application implementation.

#### Entry Points and Operating Control
Work begins with the repository operating model and session state, not an executable application entry point. Engineers must establish current constraints and perform the required delta audit before planning or implementation.
- `docs/method/DEV_OS.md`
- `SESSION_CONTEXT.md`
- `docs/archive/2026-07/DELTA_RUN_01.md`

Always-on agent/build rules are defined separately for general development and specialist domains such as print and returns.
- `AGENTS.md`
- `.cursor/rules/b2s-devos.mdc`
- `.cursor/rules/b2s-print.mdc`

#### Legacy-System Boundary
The existing tools are browser-delivered standalone HTML artifacts and are explicitly frozen read-only reference material. They are the functional source for extraction and migration, not code to modify or directly extend.
- `legacy/FREEZE.md`
- `legacy/balance-bites-invoice-pro.html`
- `legacy/balance-bites-label-editor- latest.html`

Other legacy domains include carton, stand, sticker, and stock-cost workflows. Their behavior and stored browser data must be audited before defining the unified implementation.

#### Discovery, Audit, and Migration Stages
The prescribed control flow is: inspect frozen legacy tools and browser data; run the delta audit; reconcile audit findings with inventory/proposal records; then plan target capabilities. Historical artifacts preserve earlier assumptions but should not supersede the current delta run.
- `docs/archive/2026-07/DELTA_RUN_01.md`
- `docs/archive/2026-07/inventory.json`
- `docs/archive/2026-07/UNIFICATION.md`

Requirement extracts provide evidence for the functional behavior being migrated.
- `docs/requirements/extracts/REPORT.md`
- `docs/requirements/extracts/EXTRACT_INVOICE_PRO.md`
- `docs/requirements/extracts/EXTRACT_STOCK_COSTS.md`

#### Target Product Architecture
The target is a white-label business application, with product boundaries already specified for brand configuration, tenancy, security, domain entities, data, content, templates, calculations, imports, and printable documents. These documents are the primary architecture contract for downstream design and implementation.
- `docs/product/ARCHITECTURE.md`
- `docs/product/DOMAIN_MODEL.md`
- `docs/product/DATA_MODEL.md`

Key cross-cutting boundaries are:
- White-label and tenant isolation: `docs/product/BRAND_CONFIG.md`, `docs/product/TENANCY_MODEL.md`
- Security and regulatory constraints: `docs/product/SECURITY_MODEL.md`, `docs/product/REGULATORY.md`
- Document/template/print pipeline: `docs/product/DOCUMENT_SPEC.md`, `docs/product/TEMPLATE_MODEL.md`, `docs/product/PRINT_CONTRACT.md`
- Calculations and import workflows: `docs/product/CALC_SPEC.md`, `docs/product/IMPORT_SPEC.md`

#### Quality Gates and Decision Records
Acceptance, scope, risks, and decisions govern what may enter the target app. Architectural decisions are intended to be captured as ADRs once the documented phase process reaches that point.
- `docs/product/ACCEPTANCE.md`
- `docs/product/RISK_REGISTER.md`
- `docs/product/DECISIONS.md`

Repository scripts validate process artifacts and records; they support governance rather than the application runtime.
- `scripts/check_ledger.py`
- `scripts/check_done_steps_shape.py`
- `scripts/check_credentials.py`

#### Infrastructure and External Dependencies
The intended production infrastructure is Vercel static hosting. The browser is the legacy execution and data-storage environment; migration must account for browser-resident data captured during audit. No backend, database, API integration, or deployed frontend source is present in the tree, so those choices remain constrained by the product and security specifications rather than implemented code.

Main entry points: [`docs/archive/2026-07/DELTA_RUN_01.md`](https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/docs/archive/2026-07/DELTA_RUN_01.md) (Delta audit), [`docs/product/ARCHITECTURE.md`](https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/docs/product/ARCHITECTURE.md) (Architecture and domain model), [`legacy/balance-bites-invoice-pro.html`](https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/legacy/balance-bites-invoice-pro.html) (Standalone business tools), [`SESSION_CONTEXT.md`](https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/SESSION_CONTEXT.md) (Session context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_governance["Operating control"]
  node_dev_os["Development OS<br/>operating model<br/>[DEV_OS.md]"]
  node_session_context["Session context<br/>session state<br/>[SESSION_CONTEXT.md]"]
  node_agent_rules["Agent rules<br/>development rules<br/>[AGENTS.md]"]
  node_delta_audit["Delta audit<br/>required audit<br/>[DELTA_RUN_01.md]"]
  node_quality_gates["Acceptance and risk gates<br/>product governance<br/>[ACCEPTANCE.md]"]
  node_validation_scripts{{"Governance validators<br/>Python scripts<br/>[check_ledger.py]"}}
end

subgraph group_legacy["Frozen legacy evidence"]
  node_legacy_freeze["Legacy freeze<br/>read-only boundary<br/>[FREEZE.md]"]
  node_legacy_tools["Standalone business tools<br/>browser HTML tools"]
  node_browser_data[("Browser-resident data<br/>legacy data store")]
  node_requirements["Requirement extracts<br/>migration evidence<br/>[REPORT.md]"]
  node_migration_records["Inventory and unification records<br/>historical migration records<br/>[inventory.json]"]
end

subgraph group_contract["Target architecture contract"]
  node_architecture["Architecture and domain model<br/>core product contract<br/>[ARCHITECTURE.md]"]
  node_data_model["Data model<br/>data contract<br/>[DATA_MODEL.md]"]
  node_cross_cutting_specs["Cross-cutting specifications<br/>security and workflow contracts<br/>[SECURITY_MODEL.md]"]
end

subgraph group_target["Planned runtime"]
  node_planned_app["White-label business app<br/>planned React application"]
  node_vercel{{"Vercel static hosting<br/>planned deployment"}}
end

node_dev_os -->|"establishes current constraints"| node_session_context
node_session_context -->|"requires before planning"| node_delta_audit
node_agent_rules -.->|"governs execution"| node_delta_audit
node_legacy_freeze -->|"protects as read-only"| node_legacy_tools
node_legacy_tools -->|"uses and may store data in"| node_browser_data
node_legacy_tools -->|"inspected by"| node_delta_audit
node_browser_data -->|"captured and audited by"| node_delta_audit
node_requirements -->|"supplies behavior evidence"| node_delta_audit
node_delta_audit -->|"reconciles with"| node_migration_records
node_delta_audit -->|"informs capability planning"| node_architecture
node_migration_records -.->|"provides historical context"| node_architecture
node_architecture -->|"defines domain boundaries for"| node_data_model
node_architecture -->|"is constrained by"| node_cross_cutting_specs
node_data_model -->|"guides implementation"| node_planned_app
node_cross_cutting_specs -->|"constrains implementation"| node_planned_app
node_quality_gates -->|"governs acceptance"| node_planned_app
node_validation_scripts -->|"validate process records for"| node_quality_gates
node_planned_app -->|"will deploy to"| node_vercel

click node_dev_os "https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/docs/method/DEV_OS.md"
click node_session_context "https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/SESSION_CONTEXT.md"
click node_agent_rules "https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/AGENTS.md"
click node_delta_audit "https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/docs/archive/2026-07/DELTA_RUN_01.md"
click node_quality_gates "https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/docs/product/ACCEPTANCE.md"
click node_validation_scripts "https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/scripts/check_ledger.py"
click node_legacy_freeze "https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/legacy/FREEZE.md"
click node_legacy_tools "https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/legacy/balance-bites-invoice-pro.html"
click node_requirements "https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/docs/requirements/extracts/REPORT.md"
click node_migration_records "https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/docs/archive/2026-07/inventory.json"
click node_architecture "https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/docs/product/ARCHITECTURE.md"
click node_data_model "https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/docs/product/DATA_MODEL.md"
click node_cross_cutting_specs "https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/docs/product/SECURITY_MODEL.md"

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_dev_os,node_session_context,node_agent_rules,node_delta_audit,node_quality_gates,node_validation_scripts toneBlue
class node_legacy_freeze,node_legacy_tools,node_browser_data,node_requirements,node_migration_records toneAmber
class node_architecture,node_data_model,node_cross_cutting_specs toneMint
class node_planned_app,node_vercel toneRose
```

## Components

### Operating control

Current process and quality gates govern planning.

- [Development OS](https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/docs/method/DEV_OS.md): operating model · `docs/method/DEV_OS.md`
- [Session context](https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/SESSION_CONTEXT.md): session state · `SESSION_CONTEXT.md`
- [Agent rules](https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/AGENTS.md): development rules · General and print specialist rules are always on. · `AGENTS.md`
- [Delta audit](https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/docs/archive/2026-07/DELTA_RUN_01.md): required audit · Current audit supersedes historical assumptions. · `docs/archive/2026-07/DELTA_RUN_01.md`
- [Acceptance and risk gates](https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/docs/product/ACCEPTANCE.md): product governance · `docs/product/ACCEPTANCE.md`
- [Governance validators](https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/scripts/check_ledger.py): Python scripts · Validate ledgers, completion records, and credentials. · `scripts/check_ledger.py`

### Frozen legacy evidence

Read-only sources and browser data define migration evidence.

- [Legacy freeze](https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/legacy/FREEZE.md): read-only boundary · Legacy artifacts must be inspected, not modified. · `legacy/FREEZE.md`
- [Standalone business tools](https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/legacy/balance-bites-invoice-pro.html): browser HTML tools · Invoice, labels, carton, stand, sticker, and stock-cost workflows. · `legacy/balance-bites-invoice-pro.html`
- **Browser-resident data**: legacy data store · Stored browser data must be captured during audit.
- [Requirement extracts](https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/docs/requirements/extracts/REPORT.md): migration evidence · `docs/requirements/extracts/REPORT.md`
- [Inventory and unification records](https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/docs/archive/2026-07/inventory.json): historical migration records · `docs/archive/2026-07/inventory.json`

### Target architecture contract

Specifications constrain the future application.

- [Architecture and domain model](https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/docs/product/ARCHITECTURE.md): core product contract · Defines white-label boundaries and domain entities. · `docs/product/ARCHITECTURE.md`
- [Data model](https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/docs/product/DATA_MODEL.md): data contract · `docs/product/DATA_MODEL.md`
- [Cross-cutting specifications](https://github.com/jovo-jovi/b2s-brand-to-shelf/blob/main/docs/product/SECURITY_MODEL.md): security and workflow contracts · Covers tenancy, security, imports, calculations, templates, and print. · `docs/product/SECURITY_MODEL.md`

### Planned runtime

Not yet implemented in this repository.

- **White-label business app**: planned React application · Future unified implementation; no source exists yet.
- **Vercel static hosting**: planned deployment

## Connections

- Development OS → Session context: establishes current constraints
- Session context → Delta audit: requires before planning
- Agent rules → Delta audit: governs execution
- Legacy freeze → Standalone business tools: protects as read-only
- Standalone business tools → Browser-resident data: uses and may store data in
- Standalone business tools → Delta audit: inspected by
- Browser-resident data → Delta audit: captured and audited by
- Requirement extracts → Delta audit: supplies behavior evidence
- Delta audit → Inventory and unification records: reconciles with
- Delta audit → Architecture and domain model: informs capability planning
- Inventory and unification records → Architecture and domain model: provides historical context
- Architecture and domain model → Data model: defines domain boundaries for
- Architecture and domain model → Cross-cutting specifications: is constrained by
- Data model → White-label business app: guides implementation
- Cross-cutting specifications → White-label business app: constrains implementation
- Acceptance and risk gates → White-label business app: governs acceptance
- Governance validators → Acceptance and risk gates: validate process records for
- White-label business app → Vercel static hosting: will deploy to