Route Management & Compliance – User Guide

Welcome to the internal Router Dashboard! This system acts as mission control for all web traffic, ad routing, structural compliance, and deployment topology. This guide covers how to set up new pages, secure them, achieve compliance, and take them live.

1. Creating a New Route (The Configuration Wizard)

To successfully deploy a new page to production, you must build its proxy configuration through the Route Layout Wizard.

Click the Create Route button at the top of the dashboard to open the Wizard.

Step 1: Core Setup

This stage defines the actual physical location of the server and where customers will navigate.

  1. Target Path: Decide the URL customers will actually visit (e.g., /promos/spring-sale).
  2. Origin Platform: Where does this page physically live?
    • Shopify Native: Select whether this points to the UK or US storefront. The system handles the redirect natively.
    • Lovable Builder: If you are using the Lovable low-code builder, simply paste the Lovable deployment URL. The system will auto-extract the platform variables.
    • Custom Proxy Endpoint: For pointing traffic to an external headless application.
  3. Advanced Toggles: Define whether this proxy should natively strip Shopify's /checkout URLs ("Ignore Checkout") or whether it's an ephemeral A/B test instance ("Is this a test?").

Step 2: Tracking & Operations

This stage attaches your marketing intelligence to the physical route infrastructure without needing to write any HTML tracking codes.

  1. UTM Attribution: Pre-fill global utm_source, utm_medium, utm_campaign, and utm_content values. Any ad traffic hitting your route will inherently log against these vectors natively inside our Analytics engine.
  2. Global Pixels: Select exactly which tracking instances (e.g., Meta Pixel, Google Tag Manager, TikTok) should fire natively onto your deployed page by selecting the associated checkboxes.
  3. Internal Documentation: Keep your assets rigidly organized. Paste the Lovable Builder Project URL or the Github Repository URL into the provided boxes. If another developer needs to edit your proxy later, they can instantly locate the raw codebase.
  4. Custom Meta-Tags: (For advanced users). Dynamically push unique Key/Value key-pairs straight into the route metadata.

Step 3: Checkout Link Builder (Optional)

If your route utilizes native Shopify checkouts instead of Headless APIs, this built-in wizard generates complex Shopify Cart URLs instantly without needing to manually copy links from the Shopify Admin interface.

  1. Store Selection: Pick the target store (e.g., Shopify UK or US). The interface safely queries the live database via our Proxy APIs.
  2. Product Sync: The dropdown will instantly populate with live Shopify products. You can search by text or toggle "Require Subscription" to filter exclusively to products with active selling plans.
  3. Variant Selection: Choose the exact product variant.
  4. Selling Plans: If applicable, select the Subscription frequency to automatically attach the required recurring billing variables.
  5. Auto-Save: The system calculates and constructs the lengthy https://store.myshopify.com/cart/variant:1?selling_plan=xyz payload implicitly. When you complete the Wizard, it automatically saves this checkout block into the database and binds it cleanly to your new route!

Once all stages are complete, you can click Save Route Options directly from within any menu to officially commit the route pipeline!

2. Editing & Configuring Routes

If you need to change where a URL points, update a UTM, or manage embedded Analytics:

  1. Find your route on the main dashboard.
  2. Open the ⚙️ Options dropdown.
  3. Click Configure Route.
  4. You can re-enter the configuration wizard to dynamically edit paths, change the physical origin destination, or manipulate attached Custom Meta-tags seamlessly. Changes take effect instantly upon saving.

3. Securing Routes (Locking)

To prevent accidental outages or unauthorized changes to high-value live production routes, you should immediately Lock them.

  1. Open the ⚙️ Options dropdown.
  2. Click Lock Configuration.
  3. Supply a secure password.
  4. Cryptographic Effect: When you supply your password, the backend encrypts it using an irreversible SHA-256 hashing algorithm. Once locked, it becomes physically impossible to Edit, Toggle, Archive, Delete, Health Check, or Push Code against this URL natively! The backend APIs rigidly check the authentication block natively and mathematically refuse unauthorized interactions.
  5. To make changes later, select Unlock Configuration and supply your password string. The backend will compute its hash and validate it against the locked checksum natively!

4. The Route Sign-Off Pipeline

Before any new route can be toggled "Live", it must be officially "Signed Off" by four distinct entities. This ensures quality control and strict regulatory compliance.

Under ⚙️ Edit Route, you will see the Route Sign-Offs section:

  • Page Author: Officially validates that the page content and structure are complete. (Only the Author or a Superadmin can tick this).
  • Growth Representative: Validates tracking pixels, UTM configurations, and traffic alignment. (Requires Growth role).
  • Tech Representative: Validates performance, mobile responsiveness, and load capabilities. (Requires Tech role).
  • AI Evaluation (CAP Code): An automated system layer that scans your page for CAP code compliance.

5. Making a Route Live

Once all four Sign-Off checkboxes map to True, the route is officially cleared for production traffic!

  1. On the main dashboard, locate the Status column for your route.
  2. Click the central Toggle Switch.
  3. The row will illuminate green and read Active. Live Ad Traffic will now securely route to the origin server. (Note: If you attempt to toggle a route before all 4 sign-offs are completed, the system will reject the flip with an error).

6. Archiving & Decluttering

To keep your dashboard clean without destroying historic analytics or URLs:

  1. Open the ⚙️ Options dropdown.
  2. Click Archive.
  3. The route immediately vanishes from the default view.
  4. If you need to restore or view historic locked routes, simply change the main table filter at the top right from Active Status to Archived Routes.

7. Running AI Compliance Scans

Rather than manually ticking the AI Evaluation sign-off box, you should ask the system to automatically analyze your page structure.

  1. Find your route on the main dashboard.
  2. Click ⚙️ Options -> Check Compliance.

The background AI system will parse the fully rendered page.

  • If it Passes: The system natively grants approval, logs the pass, and automatically checks the AI Evaluation box for you.
  • If it Fails: The system refuses to grant the sign-off, leaving the box unchecked.

Warnings vs. Critical Failures

The AI evaluates issues on a sliding scale:

  • Warnings (Medium / Low Risk): Issues like poor heading structures or slightly heavy images (>500KB) are treated as Warnings. Warnings will not fail the compliance check. Instead, they are quietly compiled and sent to the Tech Team in the Daily 9 AM Slack summary report.
  • Failures (High Risk / Critical): Severe regulatory violations (e.g., unsubstantiated claims, missing CAP disclosures) will strictly fail the AI scan and block the route from going live.

Important: If your route is already actively serving traffic and suddenly fails a routine background compliance scan, the system will not brutally disable your live traffic. It will simply strip its compliance validation and alert the team on Slack to immediately patch the vulnerability.

8. Manually Overriding an AI Failure

If the AI mistakenly flags a legitimate page, or if executive management has explicitly approved an exception, Growth Reps and Superadmins can manually override the AI system.

How to Execute an Override:

  1. Open the ⚙️ Edit Route menu for the failed route.
  2. Manually tick the [ ] AI Evaluation checkbox from off to on.
  3. Click Save Sign-Offs.
  4. The system will immediately pause the save and prompt you:
    "Overriding this AI cap scan requires a reason. Why are you overriding it?"
  5. Type your explicit business justification or exception reference.
  6. Press OK.

Audit Trailing
When you submit an override natively, your username, timestamp, and exact justification are permanently embedded into the database's strictly-protected audit logs. This guarantees total historical transparency for the regulatory team. If you subsequently untick the box, the override is wiped perfectly cleanly.

9. Connecting Routes & Deploying Origins (GitHub / Shopify / Cloudflare)

To seamlessly funnel your standalone React widgets or generic pages directly into our headless infrastructure without manual coding, you must explicitly connect a Github Repository to your route.

Linking a Github Repository:

  1. You can link your codebase link either during Route Creation (Step 2) or by clicking ⚙️ Options -> Configure Route.
  2. Paste the URL of your raw repository into the Github Repository URL field. This binds your physical source code to your traffic route.

Deploying to Cloudflare and Shopify: Once a Github Repository is attached, you can command the CI/CD pipeline to mechanically compile your code and blast it simultaneously to Cloudflare's Edge or natively into Shopify's liquid theme as a monolithic zero-chunk bundle.

  1. On the main dashboard, ensure the route is Unlocked.
  2. Click the ⚙️ Options dropdown.
  3. Click 🚀 Set Origin.
  4. The deployment modal will appear. It will auto-detect your attached Github Repository.
  5. Check off your desired deployment targets:
    • Cloudflare Edge: Compiles and pushes directly to the global caching network.
    • Shopify Native (UK / US): Injects active proxy logic straight into the page.lovable-hub-X.liquid formats mechanically bypassing localized frontend restrictions.
  6. Click Execute Deployment. The system explicitly bridges with GitHub Actions to trigger the compilation jobs!

10. The Route Options Menu (Dropdown Reference)

Every route in the main dashboard features an interactive ⚙️ Options dropdown. Here is exactly what each button controls:

  • ⚙️ Edit Route: Opens the configuration wizard to modify the Target Path, Origin Endpoint, and UTM variables.
  • ✅ Sign-Off / ⚙️ Edit Sign-Off: Opens the 4-stage approval menu. Team members formally approve the page for active transit here.
  • ▶️ Enable / ⏸ Disable Route: Physically switches the route. If Disabled, traffic to the URL falls back to its default generic state. (Must pass all 4 sign-offs to Enable).
  • 🔒 Lock / 🔓 Unlock: Applies the hard password safeguard over the route's integrity to prevent accidental adjustments. "Unlocked" status is rigidly required before a route can be edited, toggled, deleted, or deployed to an origin.
  • ▶️ Enable / ⏸ Disable Live Ads: Configures the sending_traffic variable which allows the backend Tracking System to filter Organic vs. Advertised traffic cleanly.
  • 🚀 Set Origin: Connects the Route configuration payload with GitHub Actions to explicitly push standard React/HTML widgets out into Cloudflare Edge or Shopify Liquid environments dynamically.
  • 🩺 Test Route: Spawns a synthetic headless network ping (ignoring caches) simulating a customer visit to ensure the Route natively returns a 200 Success code instead of a 404 dead link.
  • 🖼 Image Scan: Mechanically executes an ArrayBuffer byte-download test against every <img src=""> on your rendered page. It flags any unoptimized images larger than 500 KB.
  • 🤖 CAP Code Scan: Automatically fires the page payload explicitly into the backend AI Evaluation system to instantly parse it for regulatory infractions and updates your AI Sign-Off checkbox status natively.
  • 📝 View Logs: Prints the complete route_audit_logs trace directly to the screen. Every Edit, Toggle, AI Scan, or manual AI Override justification is immutably logged chronologically here.
  • 📦 Archive / Restore Route: Relocates the route into the hidden Archived status pool, removing it from your dashboard without destroying its analytics.
  • 🗑 Delete: Permanently strips the route mapping, pixels, and structural history from the proxy database permanently! (Restricted to Author/Superadmin).

11. Automated Monitoring & Slack Reporting (The Monitor Worker)

Protecting your ad traffic natively is our background service called Monitor. It perpetually executes a chron job across the proxy every passing hour strictly hitting every Active Route.

What does Monitor test?

  1. HTTP Status Codes: Are your routes throwing 404/500 errors downstream?
  2. Pixel Integrity: Are the globally assigned Meta/Google tracking pixels securely firing on the page?
  3. Checkout Routing Links: Does the page correctly map back to the Shopify /checkout native engine?
  4. AI Vulnerabilities & Heavy Images: Are there bloated >500KB images slowing customer performance, or medium-severity AI warnings on the active page?
  5. Locked Route Tamper Engine: If you have cryptographically locked a route, Monitor aggressively extracts the live <head> bundles searching for unpermitted deployments. If another developer pushes headless updates over an active locked route bypassing the proxy Admin dashboard, Monitor dynamically diffs the lovable_version_hash and instantly throws a 🔒🚨 LOCKED ROUTE OVERRIDE intrusion alert into Slack natively.

Actioning Faults (Critical vs. Warnings):

  • Critical Failures: If a Live Route suffers a critical event (e.g., throwing a hard 404 server error or a broken pixel matrix halts tracking), the Monitor assigns a fault. If a Route predictably fails three sequential hourly checks, the Monitor forcefully drops its Active state, terminating the broken route and immediately alerting the Slack Webhook to sound a critical alarm!
  • Warnings (Images / Medium AI Tags): If the Monitor detects heavy images (>500KB) or minor compliance flaws, it rigidly protects live traffic and will NOT disable your route! Instead, those minor issues are seamlessly aggregated into a solitary diagnostic dump passed strictly to the Tech Team Slack channel during the daily 9:00 AM Daily Run!

12. The Global Pixel Manager

Instead of hardcoding messy Javascript tracking snippets directly into source code, the system orchestrates pixels entirely via the backend Edge network.

Managing Pixels: Navigate to the 🎯 Pixel Manager tab at the top of the interface. Here, admins can define high-level tracking entities (e.g., Meta Purchase Pixel UK, GA4 Northbeam). You supply the precise <script> configuration blocks locally within the manager.

Assigning Pixels to Routes: Because pixels are managed globally, assigning them to a Route is completely trivial:

  1. When generating a route in Step 2: Tracking, simply check off the global pixels you wish to fire on that specific URL.
  2. The proxy worker intuitively dynamically injects the physical <script> payloads natively into the <head> of the DOM right at the edge server just milliseconds before it transmits to the customer's browser.

13. System Analytics & Traffic Routing

Unlike traditional web views, the Dashboard inherently understands the structural topography between Organic Traffic and Active Ad Spends.

The Analytics Portal: Navigate to the 📈 Analytics tab. The dashboard inherently queries the global D1 telemetry tables populated safely by our background queue ingestors mapping directly to your explicitly defined UTM paths.

  • By default, high-level metrics are natively grouped explicitly by Source / Medium.
  • By clicking the (+) drill-down toggle on any data row, the UI visually expands the sub-components, surfacing the exact downstream performance data organized explicitly at the granular Campaign level inline!

Live Ad Signals: If you require testing organic conversions, explicitly toggle a route's ▶️ Enable Live Ads dropdown configuration to ⏸ Disable Live Ads. The analytics system intelligently segments the resultant traffic metrics securely shielding organic behavior trails from polluting high-dollar attribution statistics mechanically.

14. Architecture Governance & User Management

To secure the stability of the global traffic array, granular access control matrices isolate deployment actions exclusively amongst explicitly authorized administrators.

Navigate to the 👥 User Management tab (Only visible to Global Superadmins):

  • Creating Profiles: Superadmins natively generate generic credentials assigning usernames and default passwords securely. Standard users can seamlessly update their proxy passwords explicitly from the overarching My Account home panel without administrative bottlenecking.
  • Role Binding (Sign-Off Chains): Explicit checkboxes strictly authenticate who can physically check specific Sign-Off boxes:
    • Growth Representative
    • Tech Representative
    • AI Evaluator
  • Access Control Metrics (Administrative Power): Superadmins manually gate restricted execution commands preventing junior staff from triggering potentially unstable UI elements:
    • Can Manage Routes (Allows creation and toggling)
    • Can Delete Routes (Exposes the strict hard-delete actions natively protecting database entries)
    • Can Deploy / Set Origin (Grants access to push structural codebase updates directly into Shopify Liquid Native structures or Cloudflare caching mechanics)
    • Can Archive Routes
  • Regional Bounds: Staff can be structurally bound natively to isolated stores (UK or US). They exist effectively locked securely into those localized environments and gracefully remain blind to opposing regional route deployments organically securing brand matrices.