Source: GFS_ARCHITECTURE_BLUEPRINT.md. This HTML is generated from the markdown — edit the .md and re-run the builder to refresh.

GFS Systems Architecture Blueprint

Clean Rebuild · $25M → $100M+ Scale

Generated: May 19, 2026

Architect: Claude Opus 4.6 (full-stack ERP + systems review)

Scope: Complete audit of gfs-platform/, guide/, docs/, skills, NS research, dashboards

Files Reviewed: 85+ files, 14,000+ lines of code/HTML, 280K words of research, 59 gap items

EXECUTIVE SUMMARY

GFS has built a surprisingly capable foundation in a short time — 185K rows in D1, 21 live API endpoints, 280K words of NS research, 60+ tools, and a triple-audited system guide. But the system has grown organically and now has structural debt that will block scaling.

This blueprint restructures everything into a cohesive, minimal-touchpoint system designed to carry GFS from $25M to $100M+ without rebuilding again.

The 5 structural problems:

1. No version control — One accident deletes everything
2. Single-laptop dependency — sync.sh + Chartstone = if your Mac dies, the platform dies
3. Dashboard sprawl — 3 separate HTML files, 2 design systems, duplicate code everywhere
4. Documentation overload — 280K words of research but no operational playbook
5. Cron handlers are stubs — The two most important automated processes (sync + daily report) don't actually work

What this blueprint delivers:

• Consolidated single command center (1 dashboard, not 3)
• Server-side sync (no laptop dependency)
• Modular Worker architecture
• Defined workflows for every business process
• Role-based views for scaling from 5 to 50 users
• Clear 4-phase execution plan

PART 1 — CURRENT STATE AUDIT

What Exists Today

gfs-platform/                    40MB total
├── src/index.ts                 517 lines — single-file Worker, 21 endpoints
├── schema.sql                   236 lines — 18 tables, no constraints
├── wrangler.jsonc               D1 + KV + R2 + 2 crons + custom domain route
├── package.json                 3 dependencies (wrangler, workers-types, typescript)
├── sync.sh                      63 lines — Chartstone localhost → D1 (broken dependency)
├── daily-report.sh              54 lines — wrangler d1 queries → markdown file
├── index.html                   632 lines — 12-tab master guide (dark monospace)
├── executive-dashboard.html     494 lines — KPI dashboard (light, system-ui)
├── infrastructure-dashboard.html 416 lines — infra status (dark monospace)
├── guide/                       15 files, 4,524 lines — deployed to Pages
├── docs/                        18 files, 6,709 lines — 280K words of research
├── sql/                         45 files, 39MB — one-time D1 loaders
├── GAPS_TO_CLOSE.md             146 lines — 59 items across 4 tiers
├── sync.log, report.log         Runtime logs
└── daily-report-*.md            Generated reports

D1 Database (185K+ rows)

API Endpoints (21)

Skills Installed: 489

96 relevant across 12 categories. The other 393 (80%) are noise — marketing, C-level advisory, social media, cold email, etc. that have zero relevance to ERP/platform engineering.

PART 2 — ARCHITECTURE PROBLEMS (WHY IT WON'T SCALE)

P1. No Version Control

Risk: CRITICAL

No git repo exists. 14,000+ lines of code, schema, dashboards, and config can be lost to one accidental delete, one bad rm, or one disk failure. No history, no rollback, no collaboration.

P2. Single-Laptop SPOF

Risk: CRITICAL

The entire sync pipeline depends on:

• Chartstone Pro running on Mike's Mac (localhost:56411)
• launchd running sync.sh every 15 minutes
• wrangler CLI being logged in
• Full Disk Access for Terminal.app

If the laptop dies, loses power, or goes to sleep — data stops flowing. This is the #1 architectural risk.

P3. Stub Cron Handlers

Risk: HIGH

The Worker has two cron handlers that don't do anything useful:

• handleSync() — Just writes a sync_log entry with records_synced = 0. The TODO says "Call SuiteAPI for modified records" but it's never been implemented.
• handleDailyReport() — Just console.logs KPIs. The TODO says "Send email via Cloudflare Email" but it's never been implemented.

The actual sync happens in sync.sh on the laptop. So there are two parallel sync systems — one that works (bash) and one that pretends to work (Worker cron).

P4. Dashboard Fragmentation

Risk: MEDIUM

Three separate HTML files with:

• Two different design systems (dark monospace vs light system-ui)
• Duplicate utility functions (formatting, DOM helpers, API calls)
• No shared CSS or component library
• The master guide (index.html) duplicates content from guide/ sub-pages

P5. Date Format Hell

Risk: MEDIUM

Dates stored as M/D/YYYY text strings (e.g., "5/19/2026"). The AR aging query has a 15-line SUBSTR/INSTR/julianday monster to parse dates for bucket calculation. Every date-based query pays this tax. At $100M volume (400K+ txns), this will be a performance bottleneck and a bug factory.

P6. Schema Without Constraints

Risk: MEDIUM

• No UNIQUE on tranid — duplicate transactions possible
• No FOREIGN KEY constraints — orphaned line items possible
• No CHECK constraints — invalid data can flow in
• year column is a generated column from text date parsing — fragile

P7. No Tests, No CI/CD

Risk: MEDIUM

• Zero test files
• No test framework installed
• Manual wrangler deploy only
• No pre-deploy validation
• No staging environment

P8. Research Overload

Risk: LOW

280K words of research across 9 docs is an incredible resource but it's not actionable in its current form. Nobody will re-read 280K words. The research needs to be distilled into the operational system — the good parts extracted, the rest archived.

PART 3 — TARGET ARCHITECTURE ($100M SCALE)

Design Principles

1. Zero laptop dependency — Everything runs in the cloud
2. One command center — Single consolidated dashboard
3. Defined workflows — Every business process has a documented flow with owners
4. Role-based access — Different views for different roles
5. Minimum touchpoints — Fewest clicks to accomplish any task
6. NetSuite is source of truth — CF platform is the analytics/intelligence layer
7. Progressive build — Each phase delivers immediate value

Target System Topology

┌─────────────────────────────────────────────────────────────┐
│                    NETSUITE (Source of Truth)                │
│  Transactions · Entities · Items · Inventory · Pricing      │
│  SuiteFlow Workflows · Saved Search Alerts · Scheduled      │
│  Scripts · User Events · Map/Reduce · N/llm AI              │
├─────────────────────────────────────────────────────────────┤
│                         │                                   │
│              SuiteAPI #2948 (RESTlet)                        │
│              SuiteQL #2947 (Query Tool)                      │
│              Toolkit #2949 (Batch Ops)                       │
│              SuiteAttach (File Upload)                       │
│              MCP Server (Claude ↔ NS)                        │
│                         │                                   │
├─────────────────────────────────────────────────────────────┤
│                  CLOUDFLARE (Intelligence Layer)             │
│                                                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │ Worker   │  │ D1       │  │ KV       │  │ R2       │   │
│  │ (API +   │  │ (185K+   │  │ (Hot     │  │ (Files   │   │
│  │  Sync +  │  │  rows)   │  │  cache)  │  │  PDFs)   │   │
│  │  Crons)  │  │          │  │          │  │          │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
│       │                                                     │
│  ┌──────────────────────────────────────────────────────┐   │
│  │            GFS COMMAND CENTER (Single Page)           │   │
│  │  ┌─────┐ ┌──────┐ ┌──────┐ ┌───────┐ ┌──────────┐  │   │
│  │  │ KPIs│ │ AR   │ │Sales │ │Vendors│ │Infra/Ops │  │   │
│  │  │     │ │Center│ │Pipe  │ │Spend  │ │Dashboard │  │   │
│  │  └─────┘ └──────┘ └──────┘ └───────┘ └──────────┘  │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                             │
│  CF Pages: System Guide · Tool Catalog                      │
├─────────────────────────────────────────────────────────────┤
│                    FUTURE (Phase 4)                          │
│  Workers AI · CF Email · GFS Hub Suitelet · MCP Tools       │
└─────────────────────────────────────────────────────────────┘

Consolidated File Structure (Target)

gfs-platform/                         Git-controlled
├── src/
│   ├── index.ts                      Router + middleware (auth, CORS, errors)
│   ├── routes/
│   │   ├── health.ts                 /api/health, /api/sync-status
│   │   ├── customers.ts             /api/customers, /:id, /:id/history, /ranking
│   │   ├── items.ts                 /api/items, /:id, /performance, /:id/customers
│   │   ├── transactions.ts          /api/transactions
│   │   ├── vendors.ts               /api/vendors, /vendors/spend
│   │   ├── financials.ts            /api/financials/*, /revenue/trend, /ar/aging
│   │   ├── kpis.ts                  /api/kpis, /api/briefing
│   │   └── search.ts               /api/search
│   ├── sync/
│   │   ├── handler.ts               Cron sync via SuiteAPI (replaces sync.sh)
│   │   └── report.ts                Daily report generator
│   ├── lib/
│   │   ├── auth.ts                  Bearer token validation
│   │   ├── cors.ts                  CORS + security headers
│   │   ├── db.ts                    D1 query helpers
│   │   ├── validate.ts              Input validation (safeInt, safeString, allowlists)
│   │   └── types.ts                 TypeScript interfaces
│   └── test/
│       ├── routes.test.ts           API endpoint tests
│       └── sync.test.ts             Sync handler tests
├── dashboard/
│   ├── index.html                   GFS Command Center (single consolidated page)
│   ├── styles.css                   Shared design system
│   └── app.js                       Shared dashboard logic
├── guide/                           System guide (deployed to Pages)
│   ├── index.html                   Master guide
│   ├── database.html
│   ├── api.html
│   ├── workflows.html
│   └── styles.css
├── docs/
│   ├── PLAYBOOK.md                  Operational playbook (distilled from 280K research)
│   ├── WORKFLOWS.md                 All business process definitions
│   ├── RUNBOOK.md                   Operational procedures
│   └── archive/                     Original 9 research docs (reference only)
├── sql/
│   ├── schema.sql                   D1 schema with constraints
│   └── loaders/                     45 batch files (archived)
├── schema.sql                       → symlink to sql/schema.sql
├── wrangler.jsonc
├── package.json
├── tsconfig.json
├── .gitignore
├── GAPS_TO_CLOSE.md
└── README.md                        Project overview + quick start

PART 4 — DEFINED WORKFLOWS ($25M → $100M)

These are the core business processes that need to be defined, automated, and measured. At $25M most of these run on tribal knowledge and manual effort. At $100M they must be systematized.

W1. Order-to-Cash (O2C) — $170M+ cumulative

Quote → Sales Order → Pick/Pack → Ship → Invoice → Payment → Cash Application

Touchpoints today:    8-12 manual steps
Touchpoints target:   3-4 (quote, approve, ship confirmation)

Current gaps:

• No approval workflow for SOs over threshold
• No auto-notification on SO status change
• Manual invoice creation from SO
• No automated dunning escalation that works (dual system conflict)
• 11 customers with expired pricing still active

Automation plan:

• SuiteFlow: SO approval routing (< $5K auto, < $25K manager, ≥ $25K director)
• User Event: Auto-notify warehouse on Pending Fulfillment
• User Event: Auto-notify customer on Ship
• Scheduled Script: Expire pricing past end date
• Saved Search Alert: SOs > 7 days unfulfilled

W2. Procure-to-Pay (P2P) — $145M cumulative

Requisition → PO → Receive → Vendor Bill → Payment → GL

Touchpoints today:    6-8 manual steps
Touchpoints target:   2-3 (request, approve, 3-way match)

Current gaps:

• No PO approval workflow
• 93% of vendors missing payment terms (451 of 484)
• 70% of vendors missing email (341)
• SuiteAPI #2948 runs as Administrator (security risk)
• No 3-way match validation

Automation plan:

• SuiteFlow: PO approval (< $1K auto, < $10K manager, ≥ $10K director)
• User Event: Auto-fill brand/department on PO from vendor defaults
• Map/Reduce: Bulk vendor data cleanup (terms + emails)
• Saved Search Alert: POs pending approval > 2 days

W3. Inventory & Work Orders

Demand Signal → WO → Assembly Build → Adjust Inventory → Fulfill

Touchpoints today:    ALL MANUAL (Zapier dead, 0 WOs in 2026)
Touchpoints target:   Semi-automated (WO from SO demand, build confirmation)

Current gaps:

• Zapier WO automation is dead — 0 WOs created in 2026
• 179 items have negative inventory
• $4.3M in inventory worksheets as workaround
• 9 Power Up meal kits negative (assembly builds not recorded)
• 78% items missing GTIN/UPC, 71% missing case weight

Automation plan:

• Scheduled Script: Auto-create WOs from SO demand (replace dead Zapier)
• User Event: Validate inventory before SO approval
• Map/Reduce: Bulk item data cleanup (weight, UPC, temp)
• Saved Search Alert: Negative inventory items daily

W4. Pricing Management

CME/USDA Movement → Cost Update → Margin Calc → Customer Price → Quote

Touchpoints today:    100% manual spreadsheet + tribal knowledge
Touchpoints target:   Semi-automated (CME feed, margin alert, price sheet gen)

Current gaps:

• No automated CME/USDA price tracking
• Bongards pricing formula exists but is manual (CME trailing week + 35%)
• No automated margin analysis
• Customer pricing in D1 but not actionable
• 11 customers with expired pricing

Automation plan:

• Scheduled Script: USDA LMPRS API hourly price fetch → cache
• Scheduled Script: Nightly margin analysis → alert on < threshold
• Map/Reduce: Quarterly customer tier reclassification
• Dashboard view: CME Price Intelligence (from Blueprint doc 07)

W5. AR Collections

Invoice Due → Aging → Dunning → Escalation → Payment → Application

Touchpoints today:    Manual review, dual dunning system conflict
Touchpoints target:   Automated escalation with human override

Current gaps:

• Dual dunning system active (day-based AND level-based)
• Open AR: $2.3M across ~90 open invoices
• No automated escalation rules
• AR aging query in Worker has 15-line date parsing monster
• Dave Jordan $786K alignment still pending

Automation plan:

• Deactivate one dunning system (pick day-based, simpler)
• SuiteFlow: Escalation workflow (30 days → email, 60 → call task, 90 → manager alert)
• Scheduled Script: Weekly AR summary email to sales reps
• Dashboard view: AR Command Center (from Blueprint doc 07)

W6. Financial Close

Period Close → Reconcile → Adjustments → Reports → Review

Touchpoints today:    BROKEN (all 153 periods open since Jan 2018)
Touchpoints target:   Monthly close by 10th of following month

Current gaps:

• ALL 153 accounting periods open since Jan 2018
• Anyone can post to any prior period
• No period close checklist
• GL account structure exists (152 accounts) but no close discipline

Automation plan:

• Immediate: Close all periods through Dec 2025
• Process: Monthly close checklist (day 1-10 of each month)
• Saved Search Alert: Transactions posted to closed periods
• Role restriction: Only Controller can reopen periods

PART 5 — CONSOLIDATED COMMAND CENTER

Problem: 3 Dashboards, 2 Design Systems

Overlap: All three show system architecture, API endpoints, and platform status. The executive dashboard is the only one pulling live data. The infrastructure dashboard hardcodes values that are already in the API.

Solution: Single Command Center

Merge into one dashboard with tab navigation:

GFS COMMAND CENTER
├── Tab: Executive       KPIs, revenue bars, monthly chart, top customers
├── Tab: AR Center       Aging table, overdue alerts, collection status
├── Tab: Sales Pipeline  Open SOs, customer ranking, recent invoices
├── Tab: Vendor Spend    Top vendors, PO status, bill analysis
├── Tab: Items           Performance, allergen filter, pricing
├── Tab: Infrastructure  Service health, DB counts, API endpoints, sync status
└── Tab: System Guide    → Link to gfs-system-guide.pages.dev

Design system: Dark monospace (consistent with system guide, professional, data-dense). The light executive dashboard was a separate experiment — merge its data views into the dark system.

Shared code:

• One CSS file (from guide/styles.css, already 7KB and comprehensive)
• One API client module (auth, fetch, format, error handling)
• One component library (stat cards, tables, bar charts, status rows, checklists)

Implementation: 1 File → dashboard/index.html

• Pulls live data from all existing API endpoints
• Auth modal on load (like current executive-dashboard.html)
• Tab navigation (like current index.html pattern)
• Auto-refresh every 5 minutes
• Mobile responsive (existing media queries already work)

PART 6 — WORKER MODULARIZATION

Current: 517 Lines in One File

The single src/index.ts does everything:

• CORS handling
• Security headers
• Auth middleware
• Input validation
• 21 route handlers
• 2 cron handlers
• Date formatting helpers

This is maintainable at 21 endpoints. At 40+ endpoints (which $100M will need), it becomes a liability.

Target: Route Modules

Split into focused files. Each route module exports a handler function that takes (request, env, params) and returns Response.

Router pattern:

// src/index.ts — thin router (~60 lines)
import { handleCustomers } from './routes/customers'
import { handleItems } from './routes/items'
// ... etc

const routes: [RegExp, Handler][] = [
  [/^\/api\/customers/, handleCustomers],
  [/^\/api\/items/, handleItems],
  // ...
]

Shared utilities in src/lib/:

• auth.ts — Bearer token validation (extracted from main handler)
• cors.ts — getCorsHeaders + securityHeaders (lines 14-51)
• validate.ts — safeInt, safeString, allowlists (lines 55-71)
• db.ts — Common query patterns (paginated list, single record, aggregation)
• types.ts — Env interface, route handler type, response helpers

Net change: Same functionality, but each file is < 100 lines. New endpoints can be added without touching the router.

PART 7 — SYNC ARCHITECTURE (ELIMINATE LAPTOP DEPENDENCY)

Current: Laptop-Based Sync

sync.sh (launchd every 15 min on Mac)
  → curl Chartstone localhost:56411
    → python3 parse JSON → generate SQL
      → wrangler d1 execute --remote

Failure modes: Laptop sleep, power loss, Chartstone crash, wrangler logout, Full Disk Access denied, VPN blocking localhost.

Target: Server-Side Sync

Worker Cron (*/15)
  → fetch() SuiteAPI #2948 (HTTPS, Bearer token)
    → D1 batch INSERT OR REPLACE

Implementation:

1. SuiteAPI #2948 already deployed and accepts SuiteQL queries
2. Worker cron already fires every 15 minutes (wrangler.jsonc confirms)
3. Replace handleSync() stub with actual SuiteAPI calls
4. Query: SELECT * FROM transaction WHERE lastmodifieddate >= :lastSync
5. Batch upsert into D1 (already have the SQL pattern from sync.sh)

Chartstone remains valuable for ad-hoc queries and development — it just stops being the sync dependency.

What changes:

• sync.sh → archived (no longer needed for sync)
• handleSync() → real implementation calling SuiteAPI
• New: SuiteAPI needs a restricted role (currently runs as Administrator — NS3 gap)
• New: API key for SuiteAPI stored as Worker secret

PART 8 — SCHEMA HARDENING

Current Issues

-- No UNIQUE: duplicate tranids can be inserted
-- No FK: line items can reference non-existent transactions
-- No CHECK: any text can go in 'type' column
-- Dates as text: "5/19/2026" — no date operations without parsing

Target Schema Additions

-- Add after initial schema

-- Prevent duplicate transactions
CREATE UNIQUE INDEX IF NOT EXISTS idx_txn_tranid_type
  ON transactions(tranid, type);

-- Ensure line items reference valid transactions
-- (D1 doesn't enforce FK but the index helps queries)
CREATE INDEX IF NOT EXISTS idx_invlines_customer ON invoice_lines(customer);
CREATE INDEX IF NOT EXISTS idx_vblines_vendor ON vb_lines(vendor);

-- Add ISO date columns for performance
-- (Populate via UPDATE, then use in all new queries)
ALTER TABLE transactions ADD COLUMN trandate_iso TEXT;
-- UPDATE transactions SET trandate_iso =
--   SUBSTR(trandate,-4) || '-' ||
--   SUBSTR('0' || SUBSTR(trandate, 1, INSTR(trandate,'/')-1), -2) || '-' ||
--   SUBSTR('0' || ... );

-- Add UNIQUE on sync_log to prevent duplicate entries
CREATE UNIQUE INDEX IF NOT EXISTS idx_sync_started
  ON sync_log(started_at, sync_type);

Migration strategy:

1. Add ISO date column
2. Backfill from existing text dates (one-time SQL)
3. Update sync handler to write ISO dates on new inserts
4. Update AR aging query to use ISO dates (eliminates the 15-line monster)
5. Eventually: all queries use ISO dates

PART 9 — DOCUMENTATION CONSOLIDATION

Current State: Scattered Across 6 Locations

Target: 4 Operational Documents

Research archive: Move 9 research docs to docs/archive/. They're a treasure for context but shouldn't be the primary reference. The good parts are already extracted into the system guide.

Guide stays as-is: The deployed system guide at gfs-system-guide.pages.dev is well-audited and comprehensive. Keep it as the reference wiki.

PART 10 — SKILL AUDIT & CLEANUP

Current: 489 skills installed, 80% noise

Recommendation: Don't uninstall (they don't consume resources when not called). But stop listing 490 as a metric — it's vanity. The real number is ~52 relevant skills.

PART 11 — EXECUTION PLAN

Phase 1: Foundation (Week 1) — "Protect Everything"

Deliverable: Protected, version-controlled codebase. Immediate security gaps closed.

Phase 2: Consolidate (Weeks 2-3) — "One Dashboard, One Design"

Deliverable: Single command center, modular codebase, clean documentation.

Phase 3: Automate (Weeks 4-6) — "No Laptop Dependency"

Deliverable: Server-side sync, automated reports, CI/CD pipeline, tests.

Phase 4: Scale (Weeks 7-12) — "Build for $100M"

Deliverable: Automated workflows, data quality fixes, AI integration, NS-native hub.

PART 12 — METRICS THAT MATTER AT $100M

Operational KPIs (Dashboard)

System KPIs (Infrastructure)

APPENDIX A — IMMEDIATE WINS (DO TODAY)

These 6 items can be done in under 2 hours and close the most critical gaps:

# 1. Git init (5 min)
cd ~/Desktop/gfs-platform
git init
echo "node_modules/\nsync.log\nreport.log\n.last_sync\ndaily-report-*.md\nsync-*.log" > .gitignore
git add -A
git commit -m "Initial commit: GFS Platform — Worker + D1 + dashboards + guide + docs"

# 2. Wrangler update (2 min)
npm update wrangler

# 3. Close accounting periods (30 min — in NetSuite UI)
# Setup > Accounting > Manage Accounting Periods
# Select all periods Jan 2018 → Dec 2025 → Close

# 4. Full Disk Access (2 min — in System Settings)
# System Settings → Privacy & Security → Full Disk Access → add Terminal.app

# 5. Fix template bugs (15 min each — in NetSuite)
# Template 117: Find TEST${record@title} → ${record@title}
# Template 118: Find ${record@title}TESTING → ${record@title}
# Template 119: Compare with standard (id 45), fix content

# 6. CF Access (10 min — in Cloudflare dashboard)
# Zero Trust → Access → Applications → Add
# → Self-hosted → gfs-system-guide.pages.dev
# → Policy: Email OTP for @globalfoodsolutions.com

APPENDIX B — WHAT NOT TO BUILD

Equally important — things from the research/roadmap that should be deprioritized or skipped:

This blueprint was generated from a complete audit of:

• src/index.ts (517 lines)
• schema.sql (236 lines)
• 3 dashboard HTML files (1,542 lines)
• 15 guide files (4,524 lines)
• 18 docs files (6,709 lines)
• 45 SQL loader files (39MB)
• GAPS_TO_CLOSE.md (59 items)
• 489 installed skills
• wrangler.jsonc, package.json, sync.sh, daily-report.sh
• All memory files (26 files)