jovo-jovi/b2s-brand-to-shelf

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.