TGK 2.0 · SOLUTION DESIGN · DOC-SD-001 · REV 2026-04-30

Solution Design — TGK 2.0 Reference Architecture

A composable, data-driven demo platform that resolves 28 source files into one branded, sales-ready Docusign story per vertical — without writing code.

Status: Approved
Owner: P. Meyer
Audience: Sales · SE · Eng
Repo: jnimbles03/tgk-2.0
Hosting: Replit + Pages

Executive summary What TGK 2.0 is, why it exists, and what it produces.

1 demoper click

TGK 2.0 is a demo authoring platform that composes a small number of locked Docusign scene templates into a sales-ready customer journey, branded for any of 21 verticals, on a live URL. The 28 source files in the repo never change between demos — only the VERTICALS[v] data row does.

The system is intentionally a five-tier funnel: 28 source files → 8 capabilities → 4 use case patterns → 21 verticals → 1 demo. Each tier reduces the surface area until what reaches the prospect is a single, focused story.

This document is the reference architecture. It is the canonical place to look for: what files exist, how they compose, what data drives them, where they run, and how to extend them. All other TGK 2.0 docs (CANONICAL.md, INTEGRATION.md, individual READMEs) defer to this one for architectural questions.

Objectives & design principles The non-negotiable goals and the rules that follow from them.

5principles

Objectives

What success looks like

Sales velocity

Any AE or SE can spin up a branded, on-message demo for a named prospect in under five minutes — without engineering involvement.
Story integrity

Every demo tells the same Docusign IAM narrative spine, regardless of vertical. Customers see one Docusign, not 21 inconsistent ones.
Maintainability

Adding a vertical is a data change, not a code change. Updating brand or product UI is a single-file edit that propagates everywhere.

Design principles

Rules of the road

Data over code

Verticals, tenants, customers, brand colors, narration — all authored as JSON. Templates and shells are inert; the data moves.
One shell, many stories

A single 5-scene shell renders every demo. Use case patterns reorder/swap scenes via URL parameters; they never fork the shell.
Composition, not duplication

Capabilities compose 1–3 templates. Patterns sequence capabilities. New behavior comes from new compositions of existing parts.
URL is the API

Vertical, use case, splash, and tokenized custom configs are all URL parameters. State is shareable, bookmarkable, and stateless on the server.
Invisible orchestration, visible proxy

Maestro is the actor; Agreement Desk is its visualizer. Every capability scene shows what the workflow is doing without exposing workflow plumbing.

Reference architecture The five-tier composition pipeline at a glance.

5tiers

Figure 01 · Composition pipeline

Source files → capabilities → patterns → verticals → result

28 → 8 → 4 → 21 → 1

Source fileTemplates and flipbooks in the repo.

CapabilityNamed scene composing 1–3 templates.

PatternUse case selectable via URL parameter.

ResultThe one branded demo.

Tier 1 — Source files 15 story templates and 13 product flipbooks. The atomic units of the system.

28files

Story templates

15 · /story-templates/ · compose into the 5-scene shell

Category	N	Templates
Intake	2	webform·webform-intake
Identity	1	clear-idv
Workflow	3	maestro-loop·maestro-package·agents
Signing	1	signing-ceremony
Agreement Desk	2	agreement-desk·agreement-desk-chain-of-custody
Intelligence	1	navigator
Workspaces	2	workspace·mastercard-workspace
Embed Hosts	3	portal-shell·ehr-desktop·portal

Product flipbooks

13 · /flipbooks/ · surface in Headless IAM tray

Category	N	Flipbooks
Intake	1	Web_Forms_Demo_Tally_Bank
Identity	3	CLEAR_IAL2_Returning_User·ID_me_Member_Authentication_IAL2·IDVerse_Demo
Workflow	1	Maestro_Workflow_Templates
Intelligence	2	Navigator_Demo_Video·Docusign_AI_Assisted_Review_in_IAM_Promo_Video
Workspaces	1	Workspaces_Demo_Video
Monitor	1	Docusign_Monitor
Data Verification	1	Data_Verification_External_Demo
CLM	2	DocuSign_CLM_Procurement_Demo_Video·Vendor_Agreement_Management_Renewals_Demo
Sales	1	IAM_for_Sales_and_Agentforce_Demo

Read: categories are how Tier 2 capability scenes are derived. Each chip is a template file checked into the repo.

Tier 2 — Capability scenes 15 templates roll up into 8 named Docusign capabilities. The unit a sales narrative refers to.

8capabilities

2.1 · 2 templates

Intake

Webform-first capture. Sender-led or self-service. Selections drive what the workflow packages downstream.

webform · webform-intake

2.2 · 1 template

Identity

Biometric identity verification. Fires at session-start (fraud-fabric) or at the transaction (canonical).

clear-idv

2.3 · 3 templates

Workflow

Workflow orchestration. The invisible engine — risk-detect, IDV-invoke, identity-bind, form-serve, package-fan-out.

maestro-loop · maestro-package · agents

2.4 · 1 template

Signing

Docusign eSignature ceremony. Envelope assembled by the workflow, signed in one continuous flow.

signing-ceremony

2.5 · 2 templates

Agreement Desk

The workflow's proxy interface. Two variants render different lenses: intake fan-out vs chain-of-custody.

agreement-desk · agreement-desk-chain-of-custody

2.6 · 1 template

Agreement Intelligence

Agreement Repository + AI assistant. Extraction, search, retrieval. Writes structured data back to system-of-record.

navigator

2.7 · 2 templates

Workspaces

Multi-party post-signing collaboration. Tenant-branded; members, tasks, summary all preset-driven.

workspace · mastercard-workspace

2.8 · 3 templates

Embed Hosts

Authenticated portal shells where Docusign embeds headlessly. Hosts the customer's native UI around the agreement flow.

portal-shell · ehr-desktop · portal

Tier 3 — Use case patterns 8 capabilities sequenced into 4 reusable narrative patterns. Each selectable via URL parameter.

4patterns

Parameter	Pattern	Scene sequence	Workflow lens
?usecase=<none>Default	Onboarding · canonical	5 scenes — Intake → Identity → Signing → Intelligence → Workspace	Intake fan-out
?usecase=fraud-fabric	Fraud Fabric — IDV-at-the-door	3 scenes — Embed Host → Identity → Webform → Chain-of-custody	Chain-of-custody binding
?usecase=intake	Intake-Mechanics — webform → workflow	3–4 scenes — Webform → Workflow Package → Signing (→ Workspace)	Package fan-out
?usecase=maintenance	Maintenance — sensitive change	3 scenes — Identity (step-up) → Webform → Approval queue	Sensitive-change orchestration

Read: a use case is the contract between Tier 2 capabilities and the rendered story. Same shell, different scene order.

Tier 4 — Vertical applied A vertical's data is applied to the chosen pattern. Tenant brand, customer, narration — all JSON, no code.

21verticals

The shell looks up VERTICALS[v] and PRESETS[v] and applies them. Brand color cascades. Narration replaces. Customer name swaps. The same six locked files do the rendering.

wealthHillside

wealth-discoveryCypress

bankingMeridian

banking-depositsCedar

insuranceSentinel

insurance-lifeBeacon

insurance-pcNorthgate

providerRiverside

provider-roiCatalina

lifesciencesHelix

payorUnity

fedgovDOL

slgovSpringfield

slgov-311Greenhaven

slgov-benefitsEastside

slgov-recertCascade

slgov-vendorRidgeview

slgov-emp-onbCascade Co.

slgov-licensingNorthbrook

educationMaple Ridge

nonprofitHarbor

Tier 5 — Result · worked example A live, branded URL. Sales-ready. Authored without writing code.

1demo

Worked example

Hillside × Aster Capital — IRA rollover

/stories/story-wealth/?usecase=canonical

Vertical: wealth
Pattern: Onboarding · canonical
Tenant: Hillside
Shell files: 6 (1 + 5 scenes)

"$5M household opened in 15 minutes, fully paperless."

Why this works

Same shell rendered the demo. Same six locked files (1 shell + 5 scene templates) did the rendering. The only thing that changed from any other vertical is the VERTICALS.wealth data row — tenant, brand color, customer, narration, preset.

Adding a 22nd vertical means writing one new VERTICALS entry and one matching PRESETS entry. Zero template changes. Zero shell changes.

Data contracts The exact JSON shapes the shell consumes. Anything that ships a demo writes to these contracts.

2tables

VERTICALS[v]

Per-vertical brand & story data

Field	Type	Notes
tenant	`string`	Brand name shown in chrome (e.g. "Hillside").
customer	`string`	Prospect-facing customer label (e.g. "Aster Capital — IRA rollover").
tenantColor	`string · hex`	Brand color cascaded into all 5 scenes via CSS custom property.
preset	`string · key`	Foreign key into `PRESETS`. Usually equals the vertical key.
scenes	`Scene[]`	Ordered scene list for the canonical pattern. Other patterns derive from this + URL.

PRESETS[v]

Per-tenant runtime configuration

Field	Type	Notes
tenant	`string`	Mirrors `VERTICALS.tenant`.
sor	`string`	System-of-record badge (e.g. "Salesforce FSC", "nCino", "Guidewire").
members	`Member[]`	Workspace participants. Driven by the customer/use case.
narration	`SceneNarration[]`	Per-scene voice-over text overrides. Optional.

Read: these two tables are the entire "API" between authoring and rendering. Anything that needs to ship a demo — manual edits, the builder UI, future automation — writes to these shapes.

Runtime & hosting Where TGK 2.0 runs, how it deploys, and the source-of-truth chain.

2targets

Concern	Resolution
Source of truth	`github.com/jnimbles03/tgk-2.0` (private). All commits go through it.
Editing surface	Cowork on Mac, working from `/Documents/Claude/Projects/TGK 2.0`. Never edit in the Repl.
Primary host	Replit — auto-deploys from `main`; serves the live demo URL.
Secondary host	GitHub Pages — workflow rewrites absolute paths at deploy time so the same source serves both targets.
Path discipline	Source uses absolute paths (`/stories/...`). Pages workflow rewrites to relative at build time.
Feedback pipeline	Public read-only endpoint `/api/feedback/public-<slug>` (CORS-open, PII stripped) for Cowork artifact.
Audit / contributor edits	`/audit.html` queues submissions to Replit DB. Reviewed at `/admin/audit`; applied locally via Python importers.
Reference videos	~7 GiB of demo MP4s under `flipbooks/vids/` — gitignored, never committed.

Read: the source-of-truth chain is Cowork edit → GitHub commit → Replit auto-deploy. GitHub Pages is a mirror, not a write target.

Builder — /builder


        The live, server-backed authoring tool that turns a picker into a shareable demo URL.


      30-daytoken TTL
      +


    
      
        /builder is the live implementation of the extension model described in §12. It runs at builder.html (aliased as /builder, /builder/, /build, /build/ via server.js), and produces a shareable custom-demo URL backed by Replit DB.
      

      
        Two modes
        Selected at load time
      
      
        Mode Purpose
        
          Build mode Default. Pick industry → tenant → customer → use case → scenes. Mints a token, persists config, returns a custom URL.
          Audit mode ?mode=audit. Hydrates the canonical VERTICALS block from story-shell.html and lets an editor patch narration fields. Commits go to GitHub via the /api/audit/* routes.
        
      

      
        Build mode flow
        Picker → token → custom URL
      
      
        
          
            Stage 1 · Tenant & brand
            Pick an industry preset (auto-fills tenant name, brand color, SoR, customer, moment) or override any field. Validation enforces tenant + customer + valid hex color.
          
        
        
          
            Stage 2 · Use case & scaffold
            Pick one of the 4 patterns from §06. The scaffold seeds default scene narration that Stage 3 can override per scene.
          
        
        
          
            Stage 3 · Timeline editor
            Drag scene blocks from the library into a timeline. Click any block to edit narration. Minimum 3 scenes. Reorder is free.
          
        
        
          
            Save → mint token
            Picker POSTs the assembled config to /api/builder/save. Server validates tenant, customer, and scenes[]; mints an 8-char readable token (no 0/o/1/l); persists under builder:<token> in Replit DB.
          
        
        
          
            Custom URL served
            Returns /stories/custom-<token>/. The route looks up the cached config, injects it inline as JSON into the shell, and serves the demo. Same six locked files do the rendering.
          
        
      

      
        API surface
        All routes registered in server.js
      
      
        Route Behavior
        
          POST /api/builder/save Accepts config JSON (≤1mb to fit tenant logo dataURL + scenes). Returns { token, url, expiresInDays }.
          GET /api/builder/:token Fetch a saved config (used by async shell paths and inspection). 404 if expired.
          GET /stories/custom-:token/ Serves the shell with the cached config injected. Expired tokens return a friendly "build a new one" page.
          GET /api/me Lightweight session probe builder uses to decide whether to render the audit-mode Save button. Never prompts; never redirects.
          PATCH (audit-mode) Audit-mode commits patch narration via the /api/audit/* routes — opens a GitHub commit on behalf of the editor.
        
      

      
        Persistence & expiry
        Replit DB, token-keyed
      
      
        Field Value
        
          Storage Replit DB. Key prefix builder:.
          Token shape 8 chars, alphabet abcdefghjkmnpqrstuvwxyz23456789 (no ambiguous glyphs).
          TTL 30 days from creation (BUILDER_TTL_DAYS = 30).
          Record shape User config + _meta: { createdAt, expiresAt, version }.
          Versioning _meta.version: 1. Bump on schema changes; the serve route should reject unknown versions.
        
      

      
        Audit mode — VERTICALS editor
        ?mode=audit
      
      
        Audit mode hydrates from the canonical VERTICALS block inlined in stories/_shared/story-shell.html. The server slices the JS literal out of the source, evaluates it in an isolated VM context, and serves it as JSON to the picker.
        Editors can patch narration fields per-vertical; saving opens a GitHub commit through the audit pipeline (/api/audit/*). The Save button only renders if /api/me returns a valid editor session — there's no client-trust path to writes.
      

      
        Why this is the right boundary
        Design rationale
      
      
        
          
            Custom configs are ephemeral; verticals are permanent
            Build-mode tokens expire in 30 days because they exist for one prospect engagement. The 21 canonical verticals live in source and survive.
          
        
        
          
            Server validates the contract, not the content
            The save route only checks tenant, customer, and scenes[] are present. Whatever else the picker sends rides through to the shell — same data shape §09 already documents.
          
        
        
          
            Audit-mode is a different blast radius
            Edits to the canonical VERTICALS table commit code; gated by session and routed through GitHub. Build-mode is sandboxed in Replit DB with a TTL.

Mode	Purpose
Build mode	Default. Pick industry → tenant → customer → use case → scenes. Mints a token, persists config, returns a custom URL.
Audit mode	`?mode=audit`. Hydrates the canonical `VERTICALS` block from `story-shell.html` and lets an editor patch narration fields. Commits go to GitHub via the `/api/audit/*` routes.

Route	Behavior
POST /api/builder/save	Accepts config JSON (≤1mb to fit tenant logo dataURL + scenes). Returns `{ token, url, expiresInDays }`.
GET /api/builder/:token	Fetch a saved config (used by async shell paths and inspection). 404 if expired.
GET /stories/custom-:token/	Serves the shell with the cached config injected. Expired tokens return a friendly "build a new one" page.
GET /api/me	Lightweight session probe builder uses to decide whether to render the audit-mode Save button. Never prompts; never redirects.
PATCH (audit-mode)	Audit-mode commits patch narration via the `/api/audit/*` routes — opens a GitHub commit on behalf of the editor.

Field	Value
Storage	Replit DB. Key prefix `builder:`.
Token shape	8 chars, alphabet `abcdefghjkmnpqrstuvwxyz23456789` (no ambiguous glyphs).
TTL	30 days from creation (`BUILDER_TTL_DAYS = 30`).
Record shape	User config + `_meta: { createdAt, expiresAt, version }`.
Versioning	`_meta.version: 1`. Bump on schema changes; the serve route should reject unknown versions.



  
  
    
      12
      
        Extension model — picker mock
        A static mock of how a sales rep authors a demo without engineering involvement.
      
      0code changes
      +
    
    
      Because verticals are data, a sales rep doesn't need a developer to spin up a new demo. A small builder UI produces the exact data shape the shell already consumes — same six locked files, new story.

      
        
          Step 1 · Pick
          Drop-down picker
          IndustryWealth Management▾
          Use caseOnboarding · canonical▾
          TenantHillside — or new▾
          Brand colorMint #3FDA99▾
          CustomerAster Capital▾
          SoRSalesforce FSC▾
          Moment"$5M household opened in 15 minutes…"▾
        

        
          Step 2 · Generate
          Same data shape the shell already eats
// generated client-side · no backend write
VERTICALS["custom-a7k9"] = {
  tenant:       "Hillside",
  customer:     "Aster Capital — IRA rollover",
  tenantColor:  "#3FDA99",
  preset:       "custom-a7k9",
  scenes: [ /* 5 scenes from selected pattern */ ]
};
PRESETS["custom-a7k9"] = {
  tenant: "Hillside",
  sor:    "Salesforce FSC",
  members:[ /* derived from customer */ ]
};
        
      

      
        Step 3 · Live URL
        /stories/_shared/story-shell.html?vertical=custom&token=a7k9-mpx2-4wnz
        Share with prospect
      

      
        Why this works without rebuilding anything. The shell already loads its config from VERTICALS[v]. The builder just produces a well-formed entry — either packed into the URL hash for one-off demos, or persisted with a short token for shareable links. No new templates. No new shell. The same Tier 2 capabilities, Tier 3 patterns, and Tier 4 brand cascade do the rendering.
      
    
  

  
  
    
      13
      
        Glossary
        Terms-of-art used throughout this document.
      
      9terms
      +
    
    
      
        Term Definition
        
          Shell stories/_shared/story-shell.html — the single page that renders every demo. Reads VERTICALS[v] + PRESETS[v].
          Scene One of the 5 fixed slots in the shell: Agreement Desk · CLEAR · Signing · Navigator · Workspace.
          Story template A reusable HTML scene file under /story-templates/ consumed by the shell.
          Flipbook A product demo asset (HTML or video) that surfaces in the Headless IAM tray; a parallel family to story templates.
          Capability A named Docusign scene composing 1–3 templates (Intake, Identity, Workflow, Signing, Agreement Desk, Intelligence, Workspaces, Embed Hosts).
          Use case pattern A scene-sequence preset (Onboarding, Fraud Fabric, Intake, Maintenance) selectable via ?usecase=….
          Vertical A tenant + brand + customer data row (21 today). Lives in VERTICALS.
          Agreement Desk proxy The visible UI that represents the invisible Maestro workflow. Maestro is the actor; Agreement Desk is the visualizer.
          SoR System of record. Persistent badge in the chrome (Guidewire PAS for insurance, nCino for banking-deposits, Salesforce FSC for wealth, etc).
        
      
    
  

  
  
    story-templates/ · stories/_shared/story-shell.html · /flipbooks/
    TGK 2.0 · Solution Design · DOC-SD-001 · Rev 2026-04-30

Term	Definition
Shell	`stories/_shared/story-shell.html` — the single page that renders every demo. Reads `VERTICALS[v]` + `PRESETS[v]`.
Scene	One of the 5 fixed slots in the shell: Agreement Desk · CLEAR · Signing · Navigator · Workspace.
Story template	A reusable HTML scene file under `/story-templates/` consumed by the shell.
Flipbook	A product demo asset (HTML or video) that surfaces in the Headless IAM tray; a parallel family to story templates.
Capability	A named Docusign scene composing 1–3 templates (Intake, Identity, Workflow, Signing, Agreement Desk, Intelligence, Workspaces, Embed Hosts).
Use case pattern	A scene-sequence preset (Onboarding, Fraud Fabric, Intake, Maintenance) selectable via `?usecase=…`.
Vertical	A tenant + brand + customer data row (21 today). Lives in `VERTICALS`.
Agreement Desk proxy	The visible UI that represents the invisible Maestro workflow. Maestro is the actor; Agreement Desk is the visualizer.
SoR	System of record. Persistent badge in the chrome (Guidewire PAS for insurance, nCino for banking-deposits, Salesforce FSC for wealth, etc).