PRD Page 2

13.5 Decisions & directional rulings

Ruling Date Rationale
Email on every plan event — one event = one email + notification + custnote. No event batching. 20260701 Transparency + audit trail; each action is atomic and logged. Pace (qty×2mo) prevents notification fatigue.
Contact-type notes = log-only — no auto customer email. Manual contact is staff's action, not a customer-facing event. 20260701 Clarity: contact-note is internal documentation; email goes only to the note author (in-app).
Notifications from a shared account (nstewart@), not individual staff. 20260701 Single sender reduces support confusion; individual author tracked in transactions.by_email.
Check Plan Health is universal — applies to all plan types (Choice, Trade, Regular), not just Choice. 20260702 Parity: legacy had no equivalent; modern adds uniformly. Trade gets its own email summary block (not the Choice "titles selected" template).
Account health derivation, not persistence (for now). Flags computed on-read from transactions rows (codes 38–46) + StandingOrder lifecycle scopes. 20260701 Faster iteration; permanentization to account_meta columns + batch classification = deferred pending flag-set stabilization.

13.6 🔧 For builders

Core event pipeline:

Plan lifecycle + health:

Brutus chat architecture:

Knowledge Base (future):

References:

14. Reports & Analytics

14.1 Purpose

Reports and analytics provide operations and management teams with visibility into sales trends, inventory velocity, standing order health, account performance, and fulfillment metrics. These dashboards and exports allow staff to monitor business health, plan inventory acquisitions, track fulfillment, analyze marketing effectiveness, and manage standing orders.

14.2 Legacy behavior

The legacy VFP application offered a limited set of hardcoded reports accessible through menu systems. Key legacy reporting features included:

Management menu reports (GEN_ORDER_MENU :120589, MIS_ORDER_MENU :126571 in webnet.prg):

Inventory projection (GEN_ORDER_MENU_INVPROJECT :122921):

Specialized reports:

Reports were often run ad-hoc, output to files on disk, or printed directly. Caching and reusability were manual (recalculate from scratch each time or maintain cached spreadsheets).

14.3 Ported forward + enhancements

The modern application consolidates and significantly expands the legacy reporting capability through a unified Analytics Dashboard service architecture, with 24 fully implemented reports across eight categories.

Services — Reporting is organized into domain-specific services (app/Services/Reports/Analytics/):

All services support consistent filtering across reports: date range, account keys, inventory nature (CENTE/TRADE), and order type (daily/standing).

Report categories — Ported from legacy ad-hoc menus and expanded:

  1. Sales & Performance (5 reports) — Annual performance, monthly comparison, multi-year trends, sales-by-plan-type, executive dashboard ("Big Picture")
  2. Standing Order Plans (3 reports) — Vital signs, year-over-year, 12+ month projections
  3. Inventory (4 reports) — Lifecycle metrics (Not Yet Published → Promotional → Clearance → Expired), CENTE vs TRADE comparison, heavy stock analysis, historical snapshots
  4. Analytics Breakdowns (10 reports) — Performance by bestseller flag, territory, series, format, division, non-consignment returns, order type, campaign, marketing channel, sales presentations
  5. Account Analytics (7 reports) — Summary, age breakdown, type breakdown, plan type breakdown, purchase metrics, health indicators, activity tracking
  6. Projections (3 reports) — No New ISBNs scenario, depletion calendar, acquisition recommendations
  7. Acquisitions & Production (3 reports) — Acquisitions status, acquisition timeline, production timeline
  8. Royalties (2 reports) — Annual billing and royalties planning

Enhancements over legacy:

Divergences from legacy (all approved):

14.4 Current state

Shipped:

In progress / Partial:

Not yet ported:

14.5 Decisions & directional rulings

D12 — No New ISBNs Projection (5-year ISBN lifetime)
All depletion projections use a fixed 5-year ISBN lifetime from PUBDATE. Titles older than 5 years are considered "expired" and excluded from recommendations. This matches legacy's acquisition planning model and ensures forecasts remain realistic across the catalog.

D13 — Caching is indefinite unless explicitly bypassed
Reports are stored persistently in storage/app/private/reports/ and never expire automatically. This is a deliberate trade-off: accuracy is secondary to performance and predictability. Users who need fresh data must explicitly use --no-cache flag (which archives the old report with a timestamp and regenerates). This prevents accidental multiple-hour regenerations when a report is requested twice in the same session.

D14 — Acquisitions spreadsheet = source of truth (transitional)
During the transition period, inventory acquisitions data lives in a CSV spreadsheet (ACQUISITIONS_SPREADSHEET_PATH). The website provides read-only analytics over that file. CRUD operations are disabled (ACQUISITIONS_TRANSITION_MODE=true). When ready, ACQUISITIONS_TRANSITION_MODE=false will unlock full in-app management. This prevents dual-source data conflicts during the bridge period.

D15 — Report generation runs on CLI, not web
Long-running reports (20–30 minutes for 2-year datasets) are generated via artisan experience:generate-report, not the web interface. This prevents timeout errors and allows asynchronous scheduling. The web interface (/analytics/reports/company/download) retrieves cached reports or shows generation-in-progress status if a lock is active.

D16 — Report JSON format (future: CSV/Excel/PDF)
Current reports export as JSON (consumable by web UI and by programmatic API). Future support for CSV, Excel, and PDF formats is planned. The service layer (CompanyReportService::generateReport()) is format-agnostic; output format is a parameter.

14.6 🔧 For builders

Services and key methods:

Controllers:

Routes:

Artisan commands:

Filter parameters (supported across all reports):

Caching behavior:

Configuration:

Development references:

Testing:

15. EDI / ONIX / MARC — Metadata Ingestion & Distribution

Centerpoint receives, processes, and distributes bibliographic metadata through three overlapping channels: ONIX (book metadata from publishers), MARC (library-formatted catalogs), and EDI (order/fulfillment messages with trading partners). This chapter documents each pipeline, their current implementation status, and the architecture for builders extending them.

15.1 Purpose

The metadata problem: Centerpoint serves libraries with book orders, but the source data (titles, pricing, publication status, BISAC categories, contributor information, cover images) must flow in from publishers and be reformatted for multiple downstream audiences:

The solution: Three independent pipelines transform vendor data into MySQL, then export in multiple formats on demand.

Scope of this chapter:

15.2 Background: Legacy Implementation

The legacy app (webnet.prg) supported three separate metadata paths, each hardcoded to a specific vendor or format.

ONIX: Legacy feature GEN_ONIX_MENU (:115721 in webnet.prg, with GEN_ONIX_WRITE :116051) offered a manual UI to export the complete inventory as an ONIX 2.1 file (a date-range / catalog-nature / single-ISBN form → confirm-and-write to a network share, for fulfillment-partner consumption).

⚠️ The legacy menu implemented only this export path. The file-drop ingestion and per-ISBN message-view described in §15.3–15.4 are new-system capabilities (onix-cli + OnixReconciliationService), not ports of legacy functionality — no ingestion trigger exists in webnet.prg.

The legacy pipeline was synchronous, file-driven, and tightly bound to Ingram's ONIX 3.0 schema. No scheduling, no message queue, no re-processing — ingest happened once per upload.

MARC: Legacy feature GENERAL_VIEW_ACCESS_MARC (:20272) provided catalog access through:

B&T is now defunct (as of 2026); the EDI infrastructure remains but is deferred pending a broader "distribution-partner pipeline" design.

15.3 Key Concepts

Metadata formats:

Pipeline architecture: All three follow a similar pattern:

  1. Ingest — Raw vendor file arrives (ONIX XML, EDI text, MARC binary/MRK)
  2. Parse — Format-specific parser extracts structured data
  3. Reconcile — Cross-reference with MySQL inventory table; resolve ISBNs, pricing, availability flags
  4. Store — Intermediate results cached in a transient store (onix-cli SQLite, EDI file system)
  5. Export — On-demand output in target format (ONIX XML, MARC file, EDI message, or spreadsheet)

ONIX as source of truth: The ONIX ingestion pipeline is the primary path for new metadata. MARC is read-only input (from legacy data or publishers) but does not auto-update inventory. EDI is order/fulfillment messaging, not title metadata.

15.4 Current State in the App

ONIX Ingestion (✅ Full Parity)

Architecture:

Routes & controllers (routes/onix_edi.php):

Scheduled sync (routes/console.php:306–331):

onix:sync --time-limit=540   # Friday 03:00 ET, 9-minute budget
onix:sync --time-limit=540   # Monday 03:00 ET, 9-minute budget

Full pipeline: OnixSync command (app/Console/Commands/OnixSync.php:13–31 class/signature; orchestration in handle() at :33–157) orchestrates:

  1. Ingest new ONIX files from the watch directory (config('cp.TRADE_MESSAGES_PATH'))
  2. Resolve ISBNs against inventory via OnixReconciliationService
  3. Cache results in storage/onix-store.sqlite (managed by onix-cli)
  4. Export reconciliation report as spreadsheet (CSV)
  5. Optionally email a daily status report (OnixDailyReport mail class)

Options (command flags):

Known limitation: The legacy OnixProduct class (app/Onix/OnixProduct.php:1–12) is marked @deprecated. It was an earlier attempt to parse ONIX in-app; the onix-cli tool supersedes it. Do not use for new work.

MARC Record Delivery (✅ Full Parity)

Architecture:

Routes & access:

File locations: Legacy FTP path: \\Webnet\ftp\From Cecilia\Processing orders - Direct to libraries\{LIBRARY_CODE}

Example: \\Webnet\ftp\From Cecilia\Processing orders - Direct to libraries\ALI_COUNTY\ALI_COUNTY_2024.mrc

Centerpoint staff do not auto-generate MARC records. The system exposes pre-built MARC files from the legacy FTP drive and provides a query interface. If libraries require fresh MARC exports (e.g., from a custom title list or standing order), the export path is via the BuildList flyer export (app/Http/Controllers/BuildListController.php) or a custom query tool.

Validation: MarcValidator enforces field 020 (ISBN) length constraints; other rules can be added as needed. Violations are logged but do not block ingestion or delivery.

EDI Messaging (⏸️ Deferred / B&T Legacy)

Status: Deferred pending generalization for future distribution partners.

Current state:

Hardcoded B&T context: Baker & Taylor's account key 6095400000001 is embedded throughout the legacy code (webnet.prg:42875, :149330, etc.). The app mirrors this hard-coding in the EDI controller's FTP credential store.

Decision (approved 20260703): The B&T EDI pipeline is deferred and will be generalized into a broader "distribution-partner pipeline" design. This will abstract:

Until then: EDI functionality stays read-only, and B&T orders are routed through the legacy system or manually entered into Centerpoint.

15.5 Architecture & Design

ONIX Pipeline Layers

Publisher ONIX feed (XML)
        ↓
   [watch directory]
        ↓
  onix-cli tool (standalone Rust/Node binary)
     - XML parsing
     - ISBN resolution (Ingram catalog)
     - BISAC classification
     - Deduplication
        ↓
  [SQLite message store: onix-store.sqlite]
        ↓
  OnixReconciliationService (Laravel)
     - Cross-ref vs inventory MySQL
     - Pricing/availability reconcile
     - Flag missing or outdated titles
        ↓
  [Result spreadsheet + cache]
        ↓
  Export paths:
   • CSV (staff reporting)
   • ONIX XML (fulfill partner consumption)
   • MySQL inventory update (future phase)

Key design rules:

  1. Subprocess isolation: onix-cli runs as a separate process; failure does not crash Laravel. OnixService::centerpointUpdate() streams results with Process::forever() (no timeout).
  2. Deferred reconciliation: CLI outputs raw ONIX data; reconciliation happens in Laravel where we can query MySQL. This keeps onix-cli stateless and portable.
  3. Time budgeting: --time-limit=S allows long-running ingests to be split across multiple runs without re-parsing already-processed messages.
  4. Reprocessing: --reprocess re-resolves all cached ISBNs against current inventory, useful after inventory schema changes or pricing updates.

MARC Access Architecture

Library staff request MARC file
        ↓
  MarcFtpController routes request to network FTP
        ↓
  [FTP shared folder: \\Webnet\ftp\...\{LIBRARY}]
        ↓
  MarcParser detects format (.mrc binary vs .mrk text)
        ↓
  MarcComposer converts binary→MRK or MRK→binary
        ↓
  [MarcRecord value objects in memory]
        ↓
  MarcValidator checks field constraints (optional)
        ↓
  Serve file to client (download or render in UI)

Design decisions:

EDI (Future: Generalized Distribution-Partner Pipeline)

Planned design (not yet implemented):

Vendor account config (encrypted)
        ↓
  [accounts → vendor relationship table]
        ↓
  DistributionPartnerService
     - Credential lookup
     - Schedule management
     - Mutual exclusion (no dual-order)
        ↓
  Inbound: {Vendor}MessageService
     - EDI 850 (purchase orders)
     - EDI 856 (advance ship)
     - Custom vendor formats
        ↓
  [Message queue: jobs.messages_pending]
        ↓
  Route to order pipeline OR skip if conflict
        ↓
  Outbound: {Vendor}ExportService
     - EDI 810 (invoices)
     - Shipment notices
     - Custom manifests

Decoupling benefits:

15.6 🔧 For Builders

Adding ONIX Support for a New Publisher

  1. Update the watch directory path:

    • Check config('cp.TRADE_MESSAGES_PATH') in config/centerpoint.php
    • Coordinate with ops: where will the publisher's ONIX files land?

  2. Extend OnixReconciliationService:

    • Add publisher-specific field mappings if needed (e.g., custom BISAC override logic)
    • Test with sample ONIX file using php artisan onix:sync --dry-run --limit=10

  3. Add a scheduled sync if needed:

    • Example: routes/console.php:306–331 shows Friday/Monday schedules
    • Use Schedule::command('onix:sync --time-limit=540')->fridays()->at('03:00')
    • Set a time limit (--time-limit) if the publisher sends many files

  4. Test reconciliation:

    php artisan onix:sync --dry-run --status
php artisan onix:sync --history=9780743273565  # Check one ISBN
php artisan onix:sync --limit=100              # Process first 100

  5. Monitor & alert:

    • Add publisher email to --notify= so staff get daily reports
    • Set up Sentry monitoring for process failures (timeout, OOM, parsing errors)

Exporting ONIX from Inventory

The OnixExport action (app/Actions/OnixExport.php) generates ONIX XML from the MySQL inventory table. Status: Deferred pending builder review of schema coverage.

To export a title subset:

$action = new OnixExport();
$onix_xml = $action->forIsbn('9780743273565');  // Returns ONIX 3.0 XML string

Delivering MARC to Libraries

  1. Verify FTP path access:

    • Test SMB connectivity: ls \\Webnet\ftp\From Cecilia\Processing orders\
    • Confirm library folders exist (e.g., ALI_COUNTY, WAYNE_COUNTY)

  2. Trigger export at MarcFtpController:

    • Route: GET /marc/{library}/{file} automatically downloads the file
    • For batch downloads: use POST /marc-action/zip to create a batch archive (if implemented)

  3. Parse a MARC file in code:

    $parser = new \App\Marc\MarcParser();
$records = $parser->parseFile('path/to/file.mrc');

foreach ($records as $record) {
    $isbn = $record->getField('020')->subfield('a');  // field 020 = ISBN
    $title = $record->getField('245')->subfield('a'); // field 245 = title
}

  4. Validate MARC:

    $validator = new \App\Marc\Validation\MarcValidator();
$violations = $validator->validate($record);
if (count($violations) > 0) {
    Log::warning('MARC validation failed', ['record' => $record, 'violations' => $violations]);
}

Preparing for EDI Generalization

When ready to onboard a new distribution partner (beyond B&T):

  1. Audit the EDI folder structure:

    • Identify which message types the partner sends/receives
    • Get a sample file to parse
    • Document credential/FTP location

  2. Create a partner-specific service:

    namespace App\Services\Edi\Partners;

class {PartnerName}MessageService
{
    public function parseInbound(string $raw): array { ... }
    public function formatOutbound(Order $order): string { ... }
}

  3. Register in a partner factory:

    class DistributionPartnerFactory
{
    public static function for(string $accountKey): PartnerService { ... }
}

  4. Add configuration row:

    • Table: distribution_partners (new)
    • Columns: id, name, account_key, credential_encrypted, supported_message_types, schedule_expression

  5. Test with sample messages:

    php artisan edi:process {partner} --file=sample_850.txt --dry-run

Code Anchors (Cross-Reference)

Feature File Line
ONIX pipeline entry app/Services/OnixService.php 39–74
ONIX sync command app/Console/Commands/OnixSync.php 13–31
ONIX scheduled runs routes/console.php 306–331
MARC FTP controller app/Http/Controllers/MarcFtpController.php 17–54
MARC parser app/Marc/MarcParser.php 15–99
MARC parser format detection app/Marc/MarcParser.php 29–48
EDI controller app/Http/Controllers/EdiController.php 15–60
ONIX routes routes/onix_edi.php 14–43
MARC routes routes/static_files.php 24, 42–43
MARC domain routes/web.php 28
Legacy ONIX menu webnet.prg 115725
Legacy MARC access webnet.prg 20272
Legacy EDI (B&T) webnet.prg 139788

16. Time Clock, Tickets & Internal Ops

16.1 Purpose

This domain covers three operational staff tools: (1) Interactive Time Clock — staff members punch in/out, with a single status-change endpoint; (2) Support Ticket System — customer-facing issue tracking; (3) Internal Operations Dashboards — aggregated account management and operational views.

16.2 Legacy Behavior

This domain is entirely green-field — the legacy Visual FoxPro application (webnet.prg, lines 1–161252) had no unified time-clock system or formal ticketing subsystem.

The legacy system did have a workaround: procedures SERVICE_HELP (line 4447) and SERVICE_REQUESTS (line 151553) attempted to piggyback service requests onto the CUSTNOTE infrastructure, but this was not a designed system and not used operationally. The legacy application provided no interactive status tracking or draft timesheet projection.

There is no PARITY row for time clock or a modern equivalent of SERVICE_HELP/SERVICE_REQUESTS, because the modern systems diverge by design from non-systems into purpose-built infrastructure.

16.3 Ported Forward + Enhancements

Since these systems are green-field, the story is in-app modernization: three fragmented time-tracking approaches (legacy TimeCard model, chat status endpoints, manual timesheet entry) were unified in June 2026 into one cohesive status-driven state machine (shipped commit aa121654b–82aa72aa8, Jun 15).

Time Clock unification:

Tickets enhancement: The custom ticketing system (TicketController, routes/tickets.php:9–21) supersedes the non-system legacy workaround. It adds: public customer links (UUID tokens per Ticket::public_token), threaded message history, status-change audit trails (TicketStatusHistory), and image attachment processing with recompression (ImageProcessor service).

16.4 Current State

Shipped (Jun 15):

Planned / Out of scope:

16.5 Decisions & Directional Rulings

D-TC-1: Single write endpoint. All status transitions (clock in, clock out, on lunch, etc.) go through one setStatus() endpoint (TimeClockController::setStatus, routes/users.php:83). The controller does NOT hardcode per-action logic; instead, the transition guard in User::updateStatus() decides legality from the current clock state. This reduces surface area and makes the state machine self-evident in config/time_clock.php.

D-TC-2: Status events are canonical. UserStatusChanged events (fired from the controller) trigger the TimeClockState read model + TimesheetDraftSync listener. The worker-friendly side effect (automatic draft entry for clocked-in intervals) never reaches back to corrupt the event stream.

D-TC-3: Tickets diverge from legacy CUSTNOTE. Rather than extend the customer-note infrastructure to handle service requests, tickets are a standalone domain with separate models, permissions (TicketPolicy), and Blade views. This allows future enhancements (SLA tracking, knowledge-base linking) without entanglement.

D-TC-4: Draft timesheet sync is a safety net, not the system. Real-time updates come from the ProjectStatusToTimesheet listener (AppServiceProvider::boot, registered via Event::listen). The nightly timeclock:sync-drafts command (console.php:99–106) caps "forgot to clock out" at end-of-day and runs at 23:45 ET to handle edge cases.

16.6 🔧 For Builders

Time Clock:

Tickets:

Internal Ops:

17. Platform — Auth, Permissions, DBF↔MySQL Bridge, Jobs

17.1 Purpose

Centerpoint runs on a hybrid infrastructure: a modern web application reading from MySQL for speed and reporting, while the legacy DBF files remain the system of record. The Platform layer is the invisible backbone that keeps these systems synchronized, ensures users can authenticate and use the app reliably, and logs every action for audit and operational monitoring.

17.2 Authentication & Permissions

The User Model is the entry point. The User class at app/Models/User.php implements Laravel's Authenticatable contract directly (not via the trait, to avoid naming conflicts with the password() relationship). When a user logs in via the login form, Laravel validates their credentials against the Password model's DBF-mirror data and creates a session.

The Password Model (app/Models/Password.php) is not a pure data store — it implements AuthorizableContract, uses the Authorizable + HasApiTokens traits, and carries auth/authorization logic (getAuthPassword(), a custom createToken(), createCredentialsFromPasswordsTable()) plus authz-gated CRUD and cart helpers. It mirrors the DBF passwords table and holds UPASS (the encrypted password hash), UNAME (username), and EMAIL. On each backend request, HandleInertiaRequests middleware calls $request->user()->viewProps() and $request->user()->currentAccountInfo() to populate the inertia props the frontend uses.

Sessions survive password table rebuilds. The nightly RebuildUsers job rebuilds the MySQL passwords table from the DBF at 02:15 (app/Actions/RebuildApplicationTables.php line 200–220), but the session cookie remains valid. This is because the session store (Redis or file-based) is independent of the password table — the session just confirms the user is logged in; the password table is consulted only on new login.

Permissions are managed via a HasPermissionsTrait on the User model (app/Models/Traits/HasPermissionsTrait.php). The trait provides methods like canNow($permission) that check against policies defined in app/Policies/. A user's role (users.role_id) determines which policies allow or deny access. Feature-level checks typically run in controller middleware or policy methods; data mutation checks run in policy update() and delete() methods.

Configuration lives at config/auth.php. The custom password-provider driver's model is App\Models\User::class (config/auth.php:69), not Password; the web guard uses session-based authentication. No changes to this config are needed for most use cases — it's set once and rarely touched.

17.3 The DBF ↔ MySQL Bridge: Three Paths, One Schema

Centerpoint has three code paths that read/write DBF files, each with different mechanics but the same table schemas:

  1. LEGACY path — Direct fopen in PHP (app/Models/Dbf/Table.php). Used by the legacy VFP app and fallback code paths.
  2. dbf-service path — 32-bit Lumen server running VFPOLEDB on :8080 (staff/dbf-service/ config at config/dbf.php). Used when the proxy is healthy.
  3. RUST path — Rust API on :3636 (centerpoint_api repository). Not production-ready; reserved for future migration.

Name the path before hypothesizing. A data inconsistency that looks like a sync bug might be a legacy-path artifact, a timeout in dbf-service, or a Rust-side issue. Knowing which path is in play cuts debugging time in half. Check logs for DBF sync handler: or grep the request context.

INDEX is the link. In MySQL, every record that comes from the DBF has an INDEX column matching the DBF record number (RECNO). When a new Laravel model syncs to DBF, INDEX starts as NULL; after the sync, it's set to the DBF record slot. This link is sacred — never null it out unless you're about to resync. Cascade keys vary by table:

MySQL is readable; DBF is the source of truth. Writes always flow MySQL → DBF via $model->dbf()->save(). The daily rebuild at 02:15 (RebuildApplicationTables::daily_tables() in app/Actions/RebuildApplicationTables.php lines 240–290) tears down and rebuilds web*, back*, bro*, all* tables from their DBF counterparts. A plain Laravel migration on these tables will not survive the rebuild — the DBF and the rebuild job must both carry the column change.

17.4 DBF Integrity & Health Checking

Corruption is detected and healed automatically. The system has three defense layers:

1. parity:fix command (php artisan carts:fix). Runs on-demand or scheduled. It performs a full DBF↔MySQL parity check in two stages:

Healing logic at app/Console/Commands/CartsFix.php (class CartsFix) around lines 116–224.

2. data:check command (php artisan data:check). Broader weekly health check with named checks:

With --fix, it cascades to carts:fix for duplicates and dispatches SyncInventoryText job for missing rows. Scheduled weekly Sunday 8am with --fix (at routes/console.php line 180).

3. PAID flag compatibility (a subtle gotcha). The allheads table stores PAID as '0' or '1', not 'T' or 'F' like VFP booleans. Use Misc::isTruthy($value) in PHP or isTruthy(value) in Vue (Helpers/Strings.js) to normalize. Both accept 'T', '1', 'TRUE', 'Y' — a guard against future copy-paste bugs (used in 15 locations: AlphaCalculateInvoiceService, OrderTrait, Allhead, etc.).

17.5 Jobs & Transaction Logging

Jobs run on Laravel's queue. The scheduler in routes/console.php defines 23 instrumented jobs (e.g., RebuildApplicationTables::daily_tables at line 60, BuildCatalogList::build at line 100). Each scheduled job wraps its Schedule::* chain with an $instrument() closure that emits started/completed/failed transaction rows on before/onSuccess/onFailure hooks — no changes to the command class needed.

TransactionLogger is the primary gate (app/Support/TransactionLogger.php). Most transactions rows flow through TransactionLogger::record() (config-driven gating, fail-soft). (Not strictly universal — a few production call sites still write via Transaction::create() directly, bypassing the gate: app/Listeners/CreateOrderTransaction.php, app/Domain/Orders/History/OrderHistoryService.php:227, and the BulkAddressUpdate services.) Client code calls TransactionLogger::record(int $code, array $data, ...) and the logger decides what to keep based on config/transactions.php gates:

Never edit call sites to silence a noisy transaction — flip a config gate instead. All methods fail-soft: exceptions log a warning and return null so the caller never blocks.

Schedule-level lifecycle uses helper methods:

TransactionLogger::started('job-name', $data);
TransactionLogger::completed('job-name', $data);
TransactionLogger::failed('job-name', $error, $data);
TransactionLogger::bracket('job-name', $work, $startData); // auto-bracket a callable

Pulse monitoring integrates via the "Jobs" widget. It reads codes 29 (started), 30 (completed), 31 (failed), 32 (warned) and renders them with ⚙ (normal) or ⚠ (failed/warned) icons. Commits: 5c3ebd263 (refactor), 33e30878a (instrument 23 jobs).

17.6 🔧 For Builders

Auth gotchas:

DBF↔MySQL gotchas:

Health & repair:

Job instrumentation:

Testing:

For code examples and deep dives: see auth_architecture.md, dbf_integrity_system.md, transaction_logger.md, domain_seams.md § "DBF ↔ MySQL" and "Testing".

Part III — Roadmap & Direction

18. Confirmed Directional Rulings

The decisions below represent the team's locked consensus on how Centerpoint works, why it works that way, and what trade-offs were made to get here. Each has been implemented, tested, and approved. Changes to these rulings require team discussion and explicit consensus.

Orders & Carts

✅ D1 — No pull-time repricing. Once a cart is submitted, prices are locked. No repricing happens when the order enters fulfillment. Rationale: The legacy system had post-submit price adjustments as a workaround for missing cart-time pricing logic. That gap is now closed; repricing at pull time creates fraud risk. (20260702)

✅ D2 — Submitted carts stay in webhead until pull. WEBHEAD records are marked SUBMITTED (MARKCART=5555) and copied to alpha_webheads history, not deleted. Separate HEADING records are created for fulfillment. Rationale: Single source of truth; clean separation of shopping vs. fulfillment state. (20260702)

✅ D3 — Backorder conversion creates new TRANSNO. When a backorder becomes available and converts to an active order, it receives a new TRANSNO, not a reused ID. Rationale: Legacy MANAGE_SELECT_BACKORDERS creates new HEADING records; app mirrors this for clear audit trail. (20260702)

✅ D4 — Archival is a sweep, not inline. Completed orders move to archive tables via nightly batch (orders:archive-sweep), respecting legacy ARCHIVE_ORDERS gate. Rationale: Batch operations are faster and less prone to race conditions; offline processing avoids customer-facing latency. (20260702)

✅ D6 — Free shipping: locked at cart, recalculated at pull. The seven free-shipping conditions are evaluated when the customer adds items to cart and again when they submit. Staff can override during master edit in exceptional cases. Rationale: Customers see accurate costs in cart summary; edge cases are rare enough for staff override. Certified parity with legacy ladder 20260703. (20260703, c320cd358)

Standing Orders & Plans

✅ D1 — Parity is non-negotiable. The legacy VFP system is still live production. All ports are parity-or-better, never silent regressions. Every claim in PARITY.md is anchored to legacy code, app code, and certification commit. (20260702)

✅ D2 — SORTORDER is a contract with Pitney Bowes. The legacy grouping hash (NNXX codes) is not a display label — it's the key Pitney Bowes uses to batch orders for weigh-in and label generation. The app must build and materialize it identically to legacy. (2026-06-18, parity matrix)

✅ D3 — FINALINV is availability, not ONHAND. Legacy defines ONHAND = FINALINV − ALLSALES. Fulfillment judges availability against FINALINV (gross inventory), not real on-hand stock. This allows standing orders to be promised against titles publishing this month. (parity matrix, D9 Inventory)

✅ D4 — Staged inventory, not production mutation. Queue build seeds a separate queue_inventories working copy. Production inventories are untouched until Ship. Rationale: Preserves ability to re-run, inspect, and audit the queue without altering shelf facts. Improvement on legacy. (20260702)

✅ D5 — Operator owns routing; system informs. Fulfillment UI flags all concerns (oversized groups, address mismatches, unfulfilled titles) and seeds sensible defaults. The operator decides what ships, where, and when — never automatic rerouting. (20260702)

✅ D6 — Contiguous TRANSNO assignment. TRANSNOs must be contiguous in SORTORDER order so that third-party consumers reading the DBF see grouped orders with adjacent numbers. (parity matrix, legacy renumber pattern)

Trade

✅ D-T-1 — Trade as separate run, collision-free reset. Trade and regular fulfillment use shared queue tables but with INVNATURE scope-tagging. Each run type has distinct ActionRun. Reset operations are scope-aware. Rationale: Neither run disturbs the other's staged rows even if both are in flight. (20260629, user decision)

✅ D-T-2 — Trade selection = cumulative-by-level auto-load. Each Trade Level plan is cumulative: Level 1 (CLASS_H) sources 2 titles/month; Level 2 (CLASS_H + CLASS_I) sources 4 titles/month; Level 3 (CLASS_H + CLASS_I + CLASS_J) sources 6 titles/month. No manual per-title curation in batch path. (parity matrix, D-T-2)

✅ D-T-5 — SORTORDER is added to trade (intentional divergence-as-improvement). Although legacy trade had no SORTORDER or batch routing, the modern trade path assigns SORTORDER via content-hash and joins the same PB-lane routing logic as regular standing orders. Trade heads benefit from grouped-shipment optimization without requiring new sort codes. (2026-06-30, user decision)

✅ D-T-6 — Queue full set, dedup on move, operator decides. Trade preloads titles onto back orders for vendor procurement sizing, so the queue must show the full plan demand without purchasing/back-order gates. The dedup + filter happen on move to production via the ship-stage toggle dedup_open_backorder (default ON). (2026-06-30, user decision)

✅ D-T-8 — Trade move = direct-to-production preorder, tentative pricing. Trade lines skip brokered queues entirely and materialize directly to backhead/backdetail (OSOURCE='TRADE STANDING'). Pricing at queue time is tentative; the final price is recalculated out-of-band at ship time. Rationale: Production brodetail→invoice billing is not replicated in fulfillment system; app-trade tool owns that. (parity matrix, 20260703)

✅ B&T / EDI → Distribution-partner pipeline generalization. Baker & Taylor is defunct (decision resolved 20260703). The legacy B&T EDI console suite (850/855/856/810/997), monthly buyer review, and scan-to-ship workflow are deferred in favor of a generalized abstraction. Future work: research EDI interaction patterns + buyer-review workflow for any future partner, then design reusable "distribution-partner pipeline". (20260703, PARITY.md rows 33 + 108, todo.md)

Inventory & Catalog

✅ D9 — FINALINV = lifetime print baseline, never reset. FINALINV is the print-run commitment; ONHAND = FINALINV − ALLSALES (post-release erosion). Standing-order needed = max(0, requested − FINALINV). Rationale: Mirrors legacy exactly; FINALINV is the decision, ONHAND is derivative. (20260618, parity matrix)

✅ D10 — Monthly make-available gates on FINALINV ≠ 0. Missing-FINALINV warning is non-blocking; operator workflow safety + data integrity. Re-seeds ONHAND := FINALINV at publish. Mirrors legacy :129221/:129236 exactly. (20260702, b58f91238)

✅ D11 — FASTPRINT lane (POD). Stock gated OFF (ships full), 6-month PUBDATE window, HOTBOX='FPR' (C(3) truncation; legacy 'FPRINT' stores as 'FPR'), +1-month invoice date, freeship, PIPACK=3/PEPACK=1. Legacy parity at lane entry (FASTPRINT_CREATE :160254). Note: DBF HOTBOX is C(3) — verified 25 production broheads. (20260703, 2a08a04ec + fcaa106af + ceec2ed1a)

✅ D12 — FINALINV readiness gate at Ship, not Queue. Preview stays open at FINALINV=0 (warned) to discover demand; operator keys FINALINV from preview + buffer; Ship holds any order with unsettled FINALINV. Rationale: Improves legacy's dead-end (forced external FINALINV forecast); preserves safety intent. (20260618, parity matrix)

Pricing, Promotions & Campaigns

✅ D10.1 — Submit locks pricing. All order pricing is locked at submit time. Carts are repriced on pull only if back-ordered. Rationale: Legacy parity; pricing is not recalculated mid-cart. (parity matrix, domain_seams.md)

✅ D10.2 — Pricing is always complete. The 42,873 ISBN × account records must be pre-calculated and cached; no on-demand fallback. Required fields always present; sparse optimization only for purchases (92.8% sparse). Cache TTL 3 hours (cold ~30s / cached 0.55s). (organization_context.md, 20260618)

✅ D10.3 — Promotions are slot-based, not semantic. Column names (western, romance, etc.) are historical convenience; slots are interchangeable. Code asks PromotionsConfiguration for column names, never hardcodes them. (dynamic_promotions_plan.md)

✅ D10.4 — Campaigns are processor-first. Each campaign reason has a dedicated processor class implementing CampaignProcessorInterface. The campaign-builder is orchestration, not logic. New campaign types = new processor + factory registration (no wizard-step cascading). (CAMPAIGNS_REFERENCE.md)

✅ D10.5 — Saved queries are filter combinations, not campaigns. They store account-classification flag selections in the wizard, reducing manual filter entry for recurring audience targeting. They do not save campaign settings or email templates. (saved_queries.md)

✅ D10.6 — Campaign options flow through whitelist. New CampaignOption enum cases must be added to BuildCampaignDrafts::normalizeOptions() or they are silently dropped before reaching build. (campaign_options_and_wizard.md, gotcha section)

Accounts & Organizations

✅ D1 — Account classification is point-in-time, not per-request. The 86-column account_meta classification runs once during OrganizationContextService build (context TTL 3 hours) and is cached. No per-request classification. Rationale: ~30s cold / 0.55s cached; per-request would be prohibitive. (20260702, parity matrix)

✅ D2 — Contact denormalization persists during transition. Accounts and passwords keep their SEX, FIRST, LAST, TITLE, VOICEPHONE, FAXPHONE, EMAIL fields through the transition to canonical contacts pool. Writes trigger soft-link ensure-or-create (when implemented); composer fields stay for legacy reads and DBF mirroring. Rationale: Accounts is DBF-mirrored; removing denormalized fields requires schema changes that can't survive rebuild. (parity matrix, address_contact_architecture.md)

✅ D3 — RECALLD dual-persistence survives rebuild. Callback date changes write to both accounts (immediate views) and accounts_meta (survives rebuild). Custnotes created with locked_at timestamp survive partial rebuilds. Rationale: accounts rebuilt daily from DBF, losing MySQL-only changes. (parity matrix)

✅ D4 — Address composition via fallback chain, not override-only. Default_physical composes from accounts directly; non-physical pivots read via contact FK with fallback to accounts composite. COMPANY override (pivot-only) allows alt-row organizational identity. Rationale: No blank address fields; fallback ensures coverage. (parity matrix)

Notifications & Email

✅ Email on every plan event. One event = one email + notification + custnote. No event batching. Rationale: Transparency + audit trail; each action is atomic. Pace (qty×2mo) prevents notification fatigue. (20260701, todo.md §1)

✅ Contact-type notes = log-only. No auto customer email. Manual contact is staff's action, not customer-facing event. Email goes only to the note author (in-app). Rationale: Clarity; contact-note is internal documentation. (20260701, todo.md §2, decision resolved)

✅ Notifications from shared account (nstewart@). Not from individual staff. Rationale: Single sender reduces support confusion; individual author tracked in transactions.by_email. (20260701, config/cp.php:203)

✅ Check Plan Health is universal. Applies to all plan types (Choice, Trade, Regular), not just Choice. Rationale: Modern adds uniformly; Trade gets its own email summary block (not the Choice "titles selected" template). (20260702, todo.md §1)

✅ Account health derivation, not persistence (for now). Flags computed on-read from transactions rows (codes 38–46) + StandingOrder lifecycle scopes. Permanentization to account_meta columns + batch classification = deferred pending flag-set stabilization. (20260701, todo.md §3)

Reports & Analytics

✅ D12 — No New ISBNs Projection (5-year ISBN lifetime). All depletion projections use fixed 5-year ISBN lifetime from PUBDATE. Titles older than 5 years are "expired" and excluded from recommendations. Rationale: Matches legacy acquisition planning model; forecasts remain realistic. (parity matrix)

✅ D13 — Caching is indefinite unless explicitly bypassed. Reports stored persistently in storage/app/private/reports/ and never expire automatically. Trade-off: accuracy is secondary to performance and predictability. Users needing fresh data must use --no-cache flag. (ReportsController, CompanyReportService)

✅ D14 — Acquisitions spreadsheet = source of truth (transitional). During transition, inventory acquisitions live in CSV (ACQUISITIONS_SPREADSHEET_PATH). Website provides read-only analytics. CRUD operations disabled (ACQUISITIONS_TRANSITION_MODE=true). When ready, --false unlocks full in-app management. (InventoryAcquisitionsController)

✅ D15 — Report generation runs on CLI, not web. Long-running reports (20–30 minutes) generated via artisan experience:generate-report, not web interface. Prevents timeout errors; allows asynchronous scheduling. (ExperienceController, CompanyReportService)

Time Clock & Tickets

✅ D-TC-1 — Single write endpoint. All status transitions (clock in, out, on lunch, etc.) go through one setStatus() endpoint. Controller does NOT hardcode per-action logic; transition guard in User::updateStatus() decides legality from current clock state. Rationale: Reduces surface area; state machine self-evident in config/time_clock.php. (20260615, aa121654b–82aa72aa8)

✅ D-TC-2 — Status events are canonical. UserStatusChanged events fire the TimeClockState read model + TimesheetDraftSync listener. Worker-friendly side effect (automatic draft entry) never reaches back to corrupt event stream. (20260615)

✅ D-TC-3 — Tickets diverge from legacy CUSTNOTE. Rather than extend customer-note infrastructure, tickets are standalone domain with separate models, permissions, and views. Rationale: Allows future enhancements (SLA tracking, KB linking) without entanglement. (20260615)

✅ D-TC-4 — Draft timesheet sync is a safety net, not the system. Real-time updates from ProjectStatusToTimesheet listener. Nightly timeclock:sync-drafts command (23:45 ET) caps "forgot to clock out" at end-of-day and handles edge cases. (20260615, console.php:99–106)

Platform & Infrastructure

✅ Sessions survive password rebuilds. The nightly RebuildUsers job (02:15 ET) rebuilds MySQL passwords table from DBF, but session cookie remains valid. Session store (Redis/file) is independent of password table; session confirms login; password table consulted only on new login. (auth_architecture.md, RebuildApplicationTables.php:200–220)

✅ INDEX is the link (DBF-MySQL bridge). Every record from DBF has INDEX matching DBF record number (RECNO). When a new Laravel model syncs to DBF, INDEX starts NULL; after sync, set to DBF record slot. This link is sacred — never null it out unless about to resync. (dbf_integrity_system.md, feedback_index_dbf_assigned.md)

✅ MySQL is readable; DBF is source of truth. Writes flow MySQL → DBF via $model->dbf()->save(). Daily rebuild (02:15 ET) tears down and rebuilds web*, back*, bro*, all* tables from DBF counterparts. Plain Laravel migrations on these tables will NOT survive rebuild — DBF and rebuild job must both carry the column change. (RebuildApplicationTables.php:240–290)

✅ Three DBF code paths (name before hypothesizing). LEGACY path: Direct fopen in PHP. dbf-service path: 32-bit Lumen on :8080 (VFPOLEDB). RUST path: Rust API on :3636 (not production-ready). A data inconsistency might be legacy-path artifact, dbf-service timeout, or Rust-side issue. Knowing which path is in play cuts debugging time in half. (dbf_three_paths.md, feedback_dbf_service_rw_flag.md)

✅ TransactionLogger is universal gate. Every transactions table row flows through TransactionLogger::record(). Config gates (config/transactions.php) decide what to keep: global kill switch, code-level disable, job-level fnmatch globs, max payload bytes, legacy override. Never edit call sites to silence noise — flip a config gate instead. Fail-soft: exceptions log warning and return null. (transaction_logger.md, config/transactions.php)

✅ Jobs run on Laravel queue with instrumentation. Scheduler (routes/console.php) defines 23 instrumented jobs. Each wraps with $instrument() closure emitting started/completed/failed transaction rows on before/onSuccess/onFailure hooks — no changes to command class needed. (transaction_logger.md, 5c3ebd263 + 33e30878a)

Cross-Domain Meta-Decisions

✅ Submit locks all pricing and policy. Orders submitted (SUBMITTED=5555) become immutable for pricing, free-shipping, and fulfillment policy. Staff can adjust line items, change quantities, override flags during master edit, but the pricing formula is never reapplied. Rationale: Fraud prevention; customer expectation. (D1 Orders, D10.1 Pricing, 20260702)

✅ DBF remains system of record. Modern MySQL provides read-only views and fast queries; DBF is the canonical persistent store. Every app write goes DBF-ward via cascading services. Rebuild job (02:15 ET) asserts this monthly — MySQL is always a fresh mirror. Rationale: 20+ years of legacy data, external integrations (Pitney Bowes), regulatory audit trail. (dbf_integrity_system.md, feedback_dbf_service_rw_flag.md)

✅ Batch operations, not inline. Fulfillment, archival, inventory release, reports, catalog rebuilds all run as nightly or on-demand batch jobs (orders:release-backorders, orders:archive-sweep, inventory:make-available, experience:generate-report, etc.). Rationale: Avoids customer-facing latency; enables auditing and dry-run before commit; improves data consistency. (parity matrix, multiple D4–D15 decisions)

✅ System informs; operator decides. Fulfillment UI flags oversized groups, address mismatches, unfulfilled titles, dedup candidates. Routing defaults are sensible (PB for multi-member, downstairs for singletons). But the operator owns the final routing decision — never automatic rerouting. Rationale: Honors legacy's manual control model while making it explicit + auditable. (D5 Standing Orders, D-T-6 Trade, 20260702)

These rulings are durable; changes require consensus. See PARITY.md for the detailed legacy-parity ledger and feature-by-feature implementation status.

19. Green-field / Future Features

Shipped Green-field Features (✅)

Brutus ubiquitous chat. The legacy app's email console (NEW_EMAIL_CONSOLE, EMBASE.DBF) was a separate staff interface for promotional outreach — staff navigated menus, composed templates, and scheduled sends as a distinct workflow. The modern app replaces that with Brutus, an intent-driven chat dispatcher that embeds action tools directly into the app. Instead of leaving an account page to open a contact form, staff click a button → the chat opens inline → the contact form renders as a canvas widget inside the chat. Intents (account edit, contact callback, plan actions) map to reusable canvas tools; every page is a trigger surface; the chat handles session bootstrap and response routing transparently. Shipped Jul 2026. 🔧 See brutus_ubiquitous_chat.md for invocation primitives (useBrutusTrigger page-button API, canvas-chip instant dispatch, response shape contract).

Unified Time Clock. Entirely green-field — the legacy app had no unified time-clock system. Prior to June 2026, Centerpoint ran three fragmented timekeeping approaches: a defunct TimeCard model, disparate clock endpoints per action (/clock/{in,out,lunch,break}), and manual timesheet entry without automation. The modern system consolidates these into one status-driven state machine (UserStatus enum, TimeClockState read model, single setStatus() endpoint) that projects the status stream into valid next-state actions and auto-drafted timesheet entries. Staff punch in/out via a single widget; the system automatically splits lunch breaks and detects overnight intervals. Shipped Jun 15, 2026. 🔧 Config at config/time_clock.php; test suite covers state-machine matrix, lunch-split, forgot-clock-out edge cases, draft sync.

Support Ticket System. Entirely green-field — the legacy app's SERVICE_HELP and SERVICE_REQUESTS procedures were non-functional workarounds. The modern system is a purpose-built ticketing infrastructure: customers report issues via email or web form; staff track status through a workflow (open → in progress → feedback requested → complete); every status change writes an audit trail; customers view their tickets via secure public links and receive notifications on updates. Ticket messages are threaded; image attachments are recompressed automatically; assignment and SLA tracking are extensible. A complementary foundation for future customer-success operations. Shipped Jun 2026. 🔧 Models at app/Models/Ticket, routes at routes/tickets.php, access gated by TicketPolicy (staff-only by default; public-link guests see only their own).

Global Diagnostics Panel. Staff-only modal that centralizes system health and debugging across all domains — cart parity, user sync status, order reconciliation, DBF drift, job health, and emerging errors. Built as a tabbed modal, extensible by adding new tabs without scattering diagnostic tools across multiple pages. A force multiplier for ops triage. Shipped May 2026. 🔧 Dispatch via useBrutusTrigger({intent: INTENTS.systemDiagnostics}).

Saved Queries in Campaign Wizard. Allows staff to save filter combinations for reuse across campaign builds — e.g., "libraries in TX with recent Trade activity." Eliminates repetition and creates institutional memory of useful segments. A net-new productivity lever for marketing campaigns. Shipped Feb 2026. 🔧 Mutually exclusive: query_id_ OR regular filters, never both; reuse in campaigns:build invocation.

In Progress / Deferred

Account Health Dashboard & Batch Renewal. Staff surface now shows account health flags (plan expiring, short on budget, recently lagging, contact overdue) and purchase history together with batch renewal capability — paralleling the legacy account-rep dashboard but with modern real-time derivation. Surfacing derived flags in account search results and the plan table are open per §5 todo. No target date.

Knowledge Base grounded-answer tier. A new tier in the Brutus answer pipeline: curated FAQ (regex/keyword) → KB grounded answer (BM25 chunk retrieval + optional LLM enrichment) → fallback (admin alert). The corpus is 67 markdown docs from storage/notes, chunked at H2 granularity; data model is doc_chunks table (durable reference + embedding slot) + sparse BM25 index. No LLM generation required for Level 0 (section-as-answer); enrichment and rephrasing are opt-in. Expected Q4 2026 start.

These features represent modern-app innovation; they have no legacy equivalent and define competitive advantage.

20. Open Questions & Undecided Directions

The following features and technical decisions remain open — either unaudited against the legacy app, explicitly deferred, or blocked on information gathering. These are normal design process checkpoints, not failures or bugs.

Feature-Level Decisions

UNDECIDED — Bonus / Gift / Free Book Program: The legacy app tracked earned credits and allowed customers to redeem free books. The modern app has no counterpart. Decision pending: port the full entitlement ledger (earn / redeem / restore) or retire the program entirely. PARITY.md status = none. (20260702)

UNDECIDED — Out-of-Catalog Titles (NOSTOCK): The legacy app maintained a NOSTOCK registry for titles no longer in active inventory but occasionally needed for research/fulfillment. The modern app inventory editor shows no equivalent. Decision pending: whether to port or treat as a legacy artifact. PARITY.md status = unaudited. (20260702)

UNDECIDED — Account Priority System: Planned feature (LOW / MEDIUM / HIGH priority levels) with per-account picker, search filters, and budget-warning triggers. Design and implementation both pending. Would surface on account dashboards and rep call lists to highlight VIP or at-risk accounts.

UNDECIDED — Contact Pool Canonicalization: Planned design to build a single canonical Contact model — deduplicating by name, phone, email — to replace the current account-address-linked contact fields. Full schema + dedup logic design pending.

Technical Decisions Awaiting Approval

UNDECIDED — Memo Field (FPT) Writing: The app reads memo fields from titles and trade notes (FoxPro .FPT format). Writing memos back to the DBF is unimplemented. Decision pending: understand the FoxPro block format (memo chunk layout, offset tables) and decide whether to port writes at all or leave memos read-only. Impacts MARC record editing and editorial content updates. Blocked on format audit. (20260702)

UNDECIDED — Account Health Flag Persistence: Health derivations (plan-health, contact-health, account badge) are currently computed on-read from transactions and standing-order scopes. Permanentizing as account_meta columns + batch classification is deferred pending stabilization of the flag set. Once the useful flag combinations are confirmed, a batch reclassification pass will make searches and dashboards faster.

UNDECIDED — Trade "By Email" Bulk Update Tab: A new tab for the trade orders UI to support bulk edits sent in by email. Currently deferred to its own focused session rather than bolted onto the existing "By Standing Order" tab. Scope and interaction design pending.

Domain Gaps

UNDECIDED — Broader Distribution-Partner Pipeline: The legacy app hardcoded B&T EDI messaging (850/855/856/810/997 consoles, manifests, invoices). B&T is now defunct. Decision pending: design an abstract "distribution-partner pipeline" reusable for future vendor relationships (purchase orders, EDI consoles, receiving, vendor payments). Deferred pending stakeholder input on future partner relationships. (20260703)

UNDECIDED — Receiving & Receiving/PO Domain: The app's PrintRunInventoryService lets operators receive and correct FINALINV at the print stage, but a broader receiving/PO domain (ONORDER tracking, RPURCHASES ownership, supplier management) has no app counterpart yet. Scope and business rules pending. Related: publisher link (royalties) editor is partial — journalkey-link editing surface unverified. (20260702)

UNDECIDED — Payment & Deposit System: Legacy tracked daily deposits, check cashing, and payment accounting. The modern app has no equivalent. Decision pending: whether to build in-app or integrate with an external accounting system. This blocks payment-system reconciliation reports and cashier workflows. (20260702)

Reporting & Analytics

UNDECIDED — Editorial Cost-of-Goods (CGS): Legacy tracked per-title cost (unit vs reprint). The modern app has no equivalent cost_of_goods field. Decision pending: add the field and populate from accounting system, or defer pending business rules clarification. Blocks accurate margin reporting.

UNDECIDED — Editorial Sales & Margin Reports: Legacy included per-title sales metrics and cost-of-goods analysis. Modern INVPROJECT (ISBN quantities/sales) report is built but stubbed for production (~2026-07-15 pending ops sign-off). Editorial margin reporting remains unaudited. PARITY.md status = unaudited. (20260702)

UNDECIDED — Web-Copy Proofing Emails: Legacy supported emailing titles for editorial copy review. The modern campaign/flyer export path exists but the single-title one-off proofing email is unaudited. Decision pending: whether to port or n-a as an outdated workflow. (20260702)

UNDECIDED — Multi-Format Report Exports: Reports currently export as JSON (consumable by web UI and API). Future CSV, Excel, and PDF support is planned but not yet implemented. Design pending: whether to implement in-app or delegate to a third-party reporting service.

UI Polish & UX

UNDECIDED — How-Can-We-Help CTA Block: Expiring/lagging plan emails include a generic action button but lack a richer "How can we help?" block. Deferred pending email-design review. (20260701)

UNDECIDED — Account Health Dashboard Surfacing: Derived health flags (has-expired-choice, has-lagging-expiring-choice, contact-health) exist but are not yet surfaced in account search results, account-rep dashboards, or the account-canvas tool descriptions. Deferred pending UI polish and stakeholder review of which flags are most useful. (20260701)

UNDECIDED — Knowledge Base Grounded-Answer Tier: Chat system will eventually support retrieval + optional LLM generation over internal documentation. Preprocessing is locked; engine choice (BM25 vs semantic embeddings) is deferred. Planned for Q4 2026+. (20260701)

UNDECIDED — Downstairs Reroute Picker UI: Legacy's manual downstairs override for grouped shipments is now expressed in the operator-routing model. CLI and admin tools exist; UX polish (a dedicated picker modal) is deferred. (20260703)

UNDECIDED — Scheduled Reminders for Staff: Native Laravel scheduler integration is available but deferred pending business rules clarification on reminder frequency and content. (20260616)

Teams working on these areas should consult the PARITY.md decision log for context and stakeholder feedback.

Part IV — Appendices

Appendix A — Legacy ↔ New Parity Matrix (durable summary)

[See appA_parity_matrix_summary.md for full content]

Appendix B — Legacy Procedure Glossary

Complete descriptive entry for all 379 top-level PROCEDURE and FUNCTION definitions from webnet.prg (the legacy Visual FoxPro application, 161,252 lines). Organized by domain following Part II taxonomy. Each entry: name, type, line number, and 1–2 sentence purpose statement. Entries are alphabetized within each domain section.

Phase 2 Research Complete — 20260704: All 379 routines extracted, categorized, and documented. PFP Decision: Option A — Full documentation. PFP is an archived subsystem documented for posterity; not intended for rebuild in the modern Laravel/Vue application but may be extracted as a separate application if future business requirements warrant.

[NOTE: Full glossary content (sections B.1–B.12) is in APPENDIX_B_DRAFT.md. For the sake of file size, the complete 1945-line glossary with all 379 routine entries is maintained as a separate reference file. To view the complete glossary with all sections, see: staff/storage/notes/APPENDIX_B_DRAFT.md]

B.1–B.12 [See existing PRD.md Appendix B sections for complete content]

Appendix C — Legacy Views & Pages Index (Client-Side Structure)

[Keep existing complete Appendix C from current PRD.md as-is — no changes needed]

Appendix D — Domain Seams & Gotchas

[See appD_domain_seams_gotchas.md for full content]

Appendix E — Glossary of Terms

[See appE_glossary_of_terms.md for full content]

Appendix F — DBF Table Families & Key Fields

[See appF_data_table_reference.md for full content]

Appendix G — Living-Docs Index

[See appG_living_docs_index.md for full content]

End of PRD.md

Revision #2
Created 4 July 2026 13:08:02 by Stephen Reynolds Jr
Updated 4 July 2026 13:47:53 by Stephen Reynolds Jr