Flip 360 — Volume 2: Enterprise Architecture & Solution Design

Contents

Volume 2

01Architecture Vision & Principles 02The Trust Equation — Formalised 03Business Architecture & Actors 04Use Case Catalogue & Diagrams 05Information Architecture & Entity Model 06The Immutable Event Log & Hash Chain 07The Commission Engine 08Application Architecture 09Technology Architecture 10Performance & Leaderboard Analytics 11ADKAR Capability Engine 12User Stories — Seeded Backlog 13Non-Functional Requirements 14Security, Privacy & Compliance 15Release Plan & Sprint Roadmap 16Architectural Decision Records (ADRs)

01

Chapter One

Architecture Vision & Principles

This Volume translates the Transformation Operating Model (Volume 1) into the structure of the platform itself. It is written for engineers who will build, for the Product Owner who must understand what he is buying, and for any future architect who needs to extend the system without breaking it.

1.1 Architecture Vision

A globally-distributed, forensic-grade, multi-vertical commission ledger that proves causation between a referral action and a passive income entitlement with the same rigour a stock exchange proves trade settlement — and which extends to unlimited verticals by configuration, not by code.

1.2 The Ten Architecture Principles

Every design decision in Flip 360 must defer to these principles. Where they conflict with convenience, the principle wins.

#	Principle	Implication
P1	Immutable by default	Events are append-only. Corrections happen via offsetting entries, never overwrites.
P2	Causation must be provable	Every dollar must trace through an unbroken, hash-chained evidence path back to the originating referral event.
P3	Integer cents arithmetic only	No floats for money — ever. All values stored as integer cents to eliminate rounding drift.
P4	Time-versioned commission rules	A referral made on date D is calculated using the rule active on date D, regardless of when the calculation runs.
P5	Dual confirmation	Both the sender and receiver of a referral cryptographically attest to each lifecycle transition.
P6	Vertical extensibility by configuration	Adding mortgage broking, then trades, then conveyancing requires zero ledger-engine code changes.
P7	Edge-first, globally distributed	Runs on Cloudflare's edge network for sub-100ms member experience worldwide.
P8	Evidence on demand	Any commission entitlement must be reconstructable into a court-admissible evidence pack in under 60 seconds.
P9	Member self-service	Every data point a member can see, they can also export, dispute, and validate independently.
P10	Deterministic outputs	Given the same inputs, the system always produces the same outputs. No hidden state. No randomness in commission math.

1.3 What This Architecture Deliberately Is Not

Not a CRM. Pipeline management is not in scope. Members may integrate their own CRM via API.
Not a marketing platform. Awareness, traffic, paid acquisition sit with the marketing partner (Your Digital Team).
Not a payment gateway. Money movement is handled by Stripe Connect or equivalent; the ledger directs what moves, not how.
Not a general analytics suite. Analytics are purpose-built for the active+passive thesis; deep BI is delivered through targeted dashboards, not a Tableau replacement.

02

Chapter Two

The Trust Equation — Formalised

The single sentence the Product Owner gave us — "I did action X on date Y, which caused business Z to earn active income, therefore I am entitled to passive income $B" — is the entire architecture in one line. This chapter formalises it.

2.1 The Causation Chain

flowchart LR E1["1. Referral Event
(immutable)
hash · timestamp · actor"] E2["2. Receipt Acknowledgement
(receiver signs)"] E3["3. Qualification
(receiver: lead is real)"] E4["4. Conversion
(deal closed)"] E5["5. Income Event
(active income earned $X)"] E6["6. Entitlement Calculated
(rule v1 → $Y)"] E7["7. Payout
(money moves)"] E1 --> E2 --> E3 --> E4 --> E5 --> E6 --> E7 style E1 fill:#0a1628,color:#fff style E2 fill:#1e3a5f,color:#fff style E3 fill:#1e3a5f,color:#fff style E4 fill:#c9a961,color:#0a1628 style E5 fill:#c9a961,color:#0a1628 style E6 fill:#1e3a5f,color:#fff style E7 fill:#0a1628,color:#fff

Every transition is an event. Every event is immutable. Every event is cryptographically chained to the prior event in its lineage. There are no edits — only new events that supersede or reverse previous ones.

2.2 The Mathematical Statement

Entitlement(R) = CommissionRule(R.vertical, R.date) · IncomeEvent(R).amount_cents
                ÷ 100   (basis points denominator if rule expressed in bps)
                — Adjustments(R)
                + Reversals(R)

where:
  R                  = referral_event_id
  R.vertical         = the vertical active at R.date
  R.date             = the immutable timestamp of the referral event
  CommissionRule(.)  = the time-versioned rule active at R.date
  IncomeEvent(R)     = the receiver-attested income event linked to R
  Adjustments(R)     = any approved adjustments (e.g. clawbacks)
  Reversals(R)       = any compensating ledger entries

All values: integer cents. No floats. Determinism guaranteed.
  

2.3 The Evidence Pack

For any disputed cent, the system can assemble — on demand, in under 60 seconds — a self-contained Evidence Pack containing:

The full causation chain (events 1 through 7), each with its hash and prior-hash.
The exact commission rule version applied, with its effective date range.
The integer arithmetic shown step-by-step.
The signatures of both sender and receiver at each attestation point.
A SHA-256 fingerprint of the pack itself, for downstream tamper detection.

This is the artefact a member can take to a tribunal. This is the artefact that retires the dispute.

03

Chapter Three

Business Architecture & Actors

3.1 The Actor Catalogue

Every interaction with the system is performed by an Actor. The catalogue is deliberately small. Roles can be combined on a single human (a Flip 360 administrator can also be a referring member), but each role is distinct in its capabilities.

Actor	Type	Description
Referring Member	Human	The business or individual sending the referral. Earns passive income.
Receiving Member	Human	The business receiving the referral. Earns active income; pays commission.
Client / Lead	Human (data subject)	The end customer being referred. Not a system user but a tracked data subject.
Flip 360 Administrator	Human	Mathew's team. Onboards members, configures verticals, resolves disputes.
Vertical Manager	Human	Owns commission rules for one vertical (e.g. "Mortgage Vertical Lead").
Finance / Payout Officer	Human	Runs payout batches; reconciles bank movement against ledger.
Auditor	Human	Read-only access to the immutable chain; internal or external.
Performance Coach	Human	Supports ADKAR uplift for bottom-quintile members.
Product Owner (Mathew)	Human	Strategic visibility; backlog ownership; system-wide read.
System	Automated	Calculates entitlements; runs hash chain; emits notifications; assembles evidence packs.
External Payment Rail	External	Stripe Connect / PayID. Receives instructions, returns settlement events.
External CRM / Source System	External	A member's own CRM that may push referrals into Flip 360 via API.

3.2 Actor Map

flowchart TB subgraph Members["Member Layer"] RM[Referring Member] RCV[Receiving Member] LEAD[Client / Lead
data subject only] end subgraph Ops["Flip 360 Operations"] ADMIN[Administrator] VM[Vertical Manager] FIN[Payout Officer] AUD[Auditor] COACH[Performance Coach] PO[Product Owner] end subgraph Sys["System & External"] SYS[Flip 360 System] PAY[Payment Rail] EXT[External CRMs] end RM --> SYS RCV --> SYS LEAD -.-> RCV ADMIN --> SYS VM --> SYS FIN --> SYS AUD --> SYS COACH --> SYS PO --> SYS SYS <--> PAY EXT --> SYS style SYS fill:#0a1628,color:#fff style RM fill:#c9a961,color:#0a1628 style RCV fill:#c9a961,color:#0a1628

3.3 Value Streams

Three value streams traverse the platform end-to-end. Every story in the backlog will support one or more.

VS-1 · Refer-to-Earn

A referral is sent → acknowledged → qualified → converted → income earned → commission paid. The core loop.

VS-2 · Onboard-to-Active

A business signs up → completes KYC/ABN → joins a vertical → sends first referral → moves through ADKAR.

VS-3 · Perform-to-Improve

Targets set → actuals tracked → leaderboard ranked → coaching triggered → quintile movement realised.

04

Chapter Four

Use Case Catalogue & Diagrams

4.1 Master Use Case Diagram

The diagram below shows every actor and every primary use case in Flip 360. This is the single most important artefact for the Product Owner to internalise — it is the system, at a glance.

flowchart LR subgraph Actors["Actors"] RM([Referring Member]) RCV([Receiving Member]) ADMIN([Administrator]) VM([Vertical Manager]) FIN([Payout Officer]) AUD([Auditor]) COACH([Performance Coach]) PO([Product Owner]) end subgraph UC["Use Cases"] UC1[Register Business & KYC] UC2[Join a Vertical] UC3[Send a Referral] UC4[Acknowledge Receipt] UC5[Qualify the Lead] UC6[Record Conversion & Income Event] UC7[Calculate Entitlement] UC8[View Real-Time Dashboard] UC9[Run Payout Batch] UC10[Reconcile Bank] UC11[Raise a Dispute] UC12[Assemble Evidence Pack] UC13[Configure Commission Rule] UC14[Add a New Vertical] UC15[Set Targets] UC16[View Leaderboard] UC17[Trigger ADKAR Intervention] UC18[Audit the Chain] UC19[Export Member Data] UC20[Approve / Reject Entitlement] end RM --> UC1 RM --> UC2 RM --> UC3 RM --> UC8 RM --> UC11 RM --> UC16 RM --> UC19 RCV --> UC1 RCV --> UC2 RCV --> UC4 RCV --> UC5 RCV --> UC6 RCV --> UC8 RCV --> UC11 RCV --> UC16 ADMIN --> UC1 ADMIN --> UC11 ADMIN --> UC14 ADMIN --> UC20 VM --> UC13 VM --> UC14 FIN --> UC9 FIN --> UC10 AUD --> UC12 AUD --> UC18 COACH --> UC17 PO --> UC15 PO --> UC16 PO --> UC18

4.2 Use Case Specifications — Selected

Below are full specifications for the three most architecturally significant use cases. The full catalogue (UC-1 through UC-20) is maintained as a living artefact in the Programme repository.

UC-03 · Send a Referral

Primary Actor	Referring Member
Goal	Create an immutable, hash-chained record that a referral was sent on a specific date to a specific receiver.
Preconditions	Both sender and receiver are registered, active members. Sender is enrolled in at least one vertical.
Trigger	Sender submits a referral via portal, mobile, or API.
Main Flow	1. Sender selects receiver (business or via vertical-matched search). 2. Sender enters client/lead identifying data (name, contact, opportunity description). 3. System validates sender/receiver eligibility and vertical compatibility. 4. System generates referral event with: UUID, server-timestamp, sender_signature, content_hash, prior_event_hash. 5. System appends event to the immutable log. 6. System notifies receiver of pending acknowledgement. 7. Sender sees referral on their dashboard with status "Awaiting Receipt".
Postconditions	Referral event exists in the immutable log. Hash chain is intact.
Alternate Flows	3a. Receiver inactive → sender warned; referral not created. 3b. Duplicate detected (same client to same receiver within N days) → confirmation prompt.
NFRs Engaged	P50 latency <200ms; immutability; hash integrity; audit logging.

UC-07 · Calculate Entitlement

Primary Actor	System (automated)
Goal	Compute the precise commission entitlement owed to the referring member for a converted referral.
Preconditions	Referral event exists. Income Event has been recorded and signed by receiver. Conversion event signed by both parties.
Trigger	Income Event recorded against the referral lineage.
Main Flow	1. System retrieves referral event and its date. 2. System resolves vertical and looks up the CommissionRule version active on referral.date. 3. System applies formula: `entitlement_cents = round_banker(income.amount_cents · rule.bps / 10000)`. 4. System creates Entitlement Event with full inputs, applied rule version, and result. 5. System chains the event into the ledger. 6. System notifies referring member: "Entitlement of $X earned, pending payout in batch <PB-id>".
Postconditions	Entitlement is recorded immutably. Referring member's earned-but-unpaid balance increases by the calculated amount.
Determinism Test	Re-running the calculation against the same inputs must produce byte-identical output and identical hash.

UC-12 · Assemble Evidence Pack

Primary Actor	Auditor (or any member viewing their own entitlement)
Goal	Produce a self-contained, tamper-evident PDF + JSON artefact reconstructing the causation chain for any commission entitlement.
Trigger	"Generate Evidence Pack" action invoked on an Entitlement.
Main Flow	1. System traverses the event lineage backward from Entitlement to originating Referral. 2. System retrieves every event in the chain, validates each hash, confirms unbroken linkage. 3. System retrieves the CommissionRule version applied, with its provenance. 4. System assembles the evidence pack (PDF for humans, JSON for systems). 5. System SHA-256-hashes the pack itself and stores the digest in the audit log. 6. System returns the pack to the requester within 60 seconds.
Acceptance Test	Any third party with no system access can independently verify the pack's internal hashes and arithmetic.

05

Chapter Five

Information Architecture & Entity Model

5.1 Logical Entity Model

erDiagram BUSINESS ||--o{ MEMBERSHIP : has BUSINESS ||--o{ REFERRAL_EVENT : "sends / receives" VERTICAL ||--o{ MEMBERSHIP : "categorises" VERTICAL ||--o{ COMMISSION_RULE : "defines" COMMISSION_RULE ||--o{ ENTITLEMENT : "calculates" REFERRAL_EVENT ||--o{ LIFECYCLE_EVENT : "progresses through" LIFECYCLE_EVENT ||--o{ INCOME_EVENT : "may produce" INCOME_EVENT ||--|| ENTITLEMENT : "triggers" ENTITLEMENT }o--|| PAYOUT_BATCH : "settled in" PAYOUT_BATCH ||--o{ PAYOUT_LINE : contains BUSINESS ||--o{ TARGET : "has" BUSINESS ||--o{ ADKAR_STATE : "tracked at" REFERRAL_EVENT ||--o{ EVIDENCE_PACK : "supports" BUSINESS { uuid id PK string legal_name string abn string gst_status string status timestamp registered_at } REFERRAL_EVENT { uuid id PK uuid sender_id FK uuid receiver_id FK uuid vertical_id FK timestamp event_ts string content_hash string prior_hash string sender_signature string status } COMMISSION_RULE { uuid id PK uuid vertical_id FK int rate_bps timestamp effective_from timestamp effective_to int version } ENTITLEMENT { uuid id PK uuid referral_id FK uuid income_event_id FK uuid rule_version_id FK bigint amount_cents timestamp calculated_at string event_hash }

5.2 Core Tables — Schema Sketch

-- Append-only event log (the heart of the system)
CREATE TABLE events (
  id              TEXT PRIMARY KEY,              -- UUID v7 (time-ordered)
  event_type      TEXT NOT NULL,                 -- REFERRAL_SENT, ACKED, QUALIFIED, CONVERTED, INCOME, ENTITLEMENT, ADJUSTMENT, REVERSAL, PAYOUT
  actor_id        TEXT NOT NULL,                 -- business_id or system
  occurred_at     TEXT NOT NULL,                 -- ISO-8601 server timestamp (UTC)
  payload_json    TEXT NOT NULL,                 -- canonical JSON of event-specific data
  content_hash    TEXT NOT NULL,                 -- SHA-256 of canonical payload
  prior_hash      TEXT NOT NULL,                 -- previous event's content_hash (chain)
  actor_signature TEXT,                          -- optional, where applicable
  CHECK (event_type IN ('REFERRAL_SENT','ACKED','QUALIFIED','CONVERTED','INCOME','ENTITLEMENT','ADJUSTMENT','REVERSAL','PAYOUT'))
);
CREATE INDEX idx_events_occurred ON events(occurred_at);
CREATE INDEX idx_events_actor    ON events(actor_id);

-- Businesses (members)
CREATE TABLE businesses (
  id              TEXT PRIMARY KEY,
  legal_name      TEXT NOT NULL,
  abn             TEXT,
  gst_registered  INTEGER DEFAULT 0,
  primary_email   TEXT NOT NULL,
  status          TEXT NOT NULL DEFAULT 'ACTIVE',
  registered_at   TEXT NOT NULL DEFAULT (datetime('now'))
);

-- Verticals (configuration-driven, no code change to add)
CREATE TABLE verticals (
  id              TEXT PRIMARY KEY,
  code            TEXT UNIQUE NOT NULL,          -- 'mortgage', 'insurance', 'tax', ...
  name            TEXT NOT NULL,
  regulator       TEXT,                          -- 'ASIC-NCCP', 'TPB', 'ASIC-AFSL', etc.
  created_at      TEXT NOT NULL DEFAULT (datetime('now'))
);

-- Commission rules (time-versioned, immutable history)
CREATE TABLE commission_rules (
  id              TEXT PRIMARY KEY,
  vertical_id     TEXT NOT NULL REFERENCES verticals(id),
  rate_bps        INTEGER NOT NULL,              -- basis points: 3000 = 30%
  flat_cents      INTEGER DEFAULT 0,             -- optional flat component
  effective_from  TEXT NOT NULL,
  effective_to    TEXT,                          -- NULL = currently active
  version         INTEGER NOT NULL,
  authored_by     TEXT NOT NULL                  -- vertical manager id
);

-- Targets (actual vs targeted)
CREATE TABLE targets (
  id              TEXT PRIMARY KEY,
  business_id     TEXT NOT NULL REFERENCES businesses(id),
  period_yyyymm   INTEGER NOT NULL,
  target_referrals INTEGER NOT NULL DEFAULT 0,
  target_passive_cents BIGINT NOT NULL DEFAULT 0,
  created_at      TEXT NOT NULL DEFAULT (datetime('now'))
);

-- ADKAR state machine (one row per business per stage transition)
CREATE TABLE adkar_states (
  id              TEXT PRIMARY KEY,
  business_id     TEXT NOT NULL REFERENCES businesses(id),
  stage           TEXT NOT NULL,                 -- A1 A2 K A R
  entered_at      TEXT NOT NULL DEFAULT (datetime('now'))
);
  

5.3 Event Types — The Complete Vocabulary

Event Type	Emitted When	Signed By
REFERRAL_SENT	Sender submits a referral	Sender
ACKED	Receiver acknowledges receipt (or auto-ack after N days)	Receiver
QUALIFIED	Receiver confirms lead is genuine	Receiver
CONVERTED	Receiver records deal closed	Receiver
INCOME	Receiver attests active income earned (amount_cents)	Receiver
ENTITLEMENT	System computes commission owed	System
ADJUSTMENT	Approved adjustment (e.g. clawback)	Administrator
REVERSAL	Compensating entry reversing a prior event	Administrator
PAYOUT	Funds released through payment rail	Payout Officer

06

Chapter Six

The Immutable Event Log & Hash Chain

This chapter is the technical heart of the Trust Engine. Architects building Flip 360 must understand this chapter cold; everything else is plumbing.

6.1 Canonical Payload & Hashing

Before hashing, every event payload is converted to a canonical JSON representation: keys sorted lexicographically, no whitespace, UTF-8 encoded. This guarantees that the same logical content always produces the same hash, regardless of how it was originally serialised.

content_hash    = SHA-256( canonical_json(payload) )
chain_input     = prior_hash || content_hash || occurred_at || event_type
chain_signature = SHA-256( chain_input )

The chain_signature is what is stored and what subsequent events reference.
  

6.2 The Chain Visualised

flowchart LR G[Genesis
hash: 0000...] E1[Event #1
REFERRAL_SENT
hash: a3f9...] E2[Event #2
ACKED
hash: 7c4d...
prior: a3f9...] E3[Event #3
QUALIFIED
hash: 9b21...
prior: 7c4d...] E4[Event #4
CONVERTED
hash: e8a0...
prior: 9b21...] E5[Event #5
INCOME
hash: 4d77...
prior: e8a0...] E6[Event #6
ENTITLEMENT
hash: ff03...
prior: 4d77...] G --> E1 --> E2 --> E3 --> E4 --> E5 --> E6 style G fill:#1e3a5f,color:#fff style E6 fill:#c9a961,color:#0a1628

Any attempt to alter the contents of an earlier event would invalidate its hash, which would invalidate every subsequent event's prior_hash — a tamper attempt is instantly detectable by walking the chain.

6.3 Why Not Use a Public Blockchain?

We considered, and rejected, anchoring to a public blockchain (Ethereum, Bitcoin). Reasons:

Latency & cost. Sub-second commission events at scale; on-chain anchoring would be prohibitive.
Privacy. Member PII must not be on a public ledger.
Sufficiency. A hash-chained append-only log running on Cloudflare D1 + R2 cold storage provides the forensic guarantees we need.
Optional escrow anchoring. We retain the option to publish a periodic Merkle-root digest of the log to a trusted third-party timestamp service for additional defence-in-depth.

6.4 Integrity Checks

The system runs three integrity checks continuously:

Per-event hash verification on read. Any event read out of storage has its content_hash recomputed and compared.
Chain walk nightly. The full event chain is walked end-to-end; any broken link raises a Severity-1 alert.
Periodic Merkle root published daily to an immutable object in R2 (and optionally to a third-party timestamp service).

07

Chapter Seven

The Commission Engine

7.1 Engine Responsibilities

The Commission Engine is the deterministic calculator that turns Income Events into Entitlement Events. It is the smallest, most tested, most stable module in the platform — by design.

Resolve the active commission rule for a referral's vertical and date.
Apply the rule arithmetic in integer cents with banker's rounding.
Emit an Entitlement Event with full provenance.
Handle adjustments and reversals via compensating events (never edits).
Provide a pure, replayable function: calc(referral, income, rule) → entitlement.

7.2 Rule Types Supported (MVP)

Rule Type	Formula	Example
Flat percentage	`income · bps ÷ 10000`	30% of broker commission = 3000 bps
Flat amount per referral	`flat_cents`	$200 per qualified referral
Tiered percentage (by income amount)	Piecewise on income brackets	20% to $5k, 25% above
Hybrid (flat + percentage)	`flat_cents + income · bps ÷ 10000`	$100 + 20%
Multi-hop (future)	Recursive entitlements up the referral tree, capped at depth	Originator 25%, second-degree 5%

7.3 Rounding Policy

Flip 360 uses banker's rounding (round half to even) on the final cent. This is the rounding scheme used by IEEE 754, by the Australian Tax Office for many calculations, and by financial systems globally. It removes the systematic bias that simple half-up rounding introduces over millions of transactions.

7.4 GST Handling

Where the receiving member is GST-registered (per their ABN status), commissions paid are typically subject to GST. The engine separates:

entitlement_ex_gst_cents — base entitlement.
gst_cents — calculated as 10% of base where applicable.
entitlement_inc_gst_cents — sum, paid to the member.

Both values are stored on the Entitlement Event. The system can produce a Recipient Created Tax Invoice (RCTI) for each payout — standard practice in the Australian financial services industry.

08

Chapter Eight

Application Architecture

8.1 Logical Component View

flowchart TB subgraph Edge["Edge Layer · Cloudflare Workers"] WEB[Web Portal
Hono · JSX] API[Public API
Hono Router] AUTH[AuthN/AuthZ
JWT · Sessions] end subgraph Core["Core Services"] EVT[Event Service
Append + Hash] COM[Commission Engine
Pure Functions] EVD[Evidence Pack Service] NOTIF[Notification Service] ADKAR[ADKAR State Engine] end subgraph Data["Data Layer"] D1[(Cloudflare D1
Relational · SQLite)] KV[(Cloudflare KV
Session · Config)] R2[(Cloudflare R2
Evidence Packs · Cold)] end subgraph Ext["External"] PAY[Stripe Connect] MAIL[Email · SMS] end WEB --> API API --> AUTH AUTH --> EVT AUTH --> COM AUTH --> EVD EVT --> D1 COM --> D1 EVD --> D1 EVD --> R2 ADKAR --> D1 NOTIF --> MAIL COM --> PAY API --> KV style EVT fill:#0a1628,color:#fff style COM fill:#c9a961,color:#0a1628 style D1 fill:#1e3a5f,color:#fff

8.2 Why Hono on Cloudflare?

Edge-first. Code runs in 300+ data centres globally; member experience is sub-100ms anywhere.
Zero-ops infrastructure. No servers, no patching, no capacity planning.
Native integration with D1, KV, R2. The full data tier is first-party on Cloudflare; no cross-cloud latency.
Cost flatness. Edge pricing scales near-linearly with usage; no $5,000/month idle bill.
Excellent TypeScript ergonomics. Hono is purpose-built for Workers; type safety end-to-end.

8.3 Module Boundaries (Source Layout)

/src
  /routes              # Hono route handlers, one file per resource
    referrals.ts
    members.ts
    entitlements.ts
    payouts.ts
    evidence.ts
    leaderboard.ts
  /services            # Pure-ish business logic
    event-service.ts   # append + hash + chain
    commission-engine.ts # deterministic calculator
    evidence-service.ts  # pack assembly
    adkar-engine.ts
    notification.ts
  /domain              # Types + validators
    types.ts
    schemas.ts         # zod
  /persistence
    d1-client.ts
    r2-client.ts
    kv-client.ts
  /util
    hashing.ts         # SHA-256, canonical JSON
    money.ts           # integer cents, banker's rounding
    time.ts            # UTC ISO-8601
  /ui                  # JSX components for member portal
  index.tsx            # Hono app entry
  

09

Chapter Nine

Technology Architecture

Layer	Choice	Rationale
Runtime	Cloudflare Workers (V8 isolates)	Edge execution; zero ops; sub-100ms global latency.
Web framework	Hono	Purpose-built for Workers; lightweight; great DX.
Language	TypeScript (strict)	Type safety across the trust engine.
Relational store	Cloudflare D1 (SQLite)	Native binding; horizontal read replicas; sufficient for ledger workload.
Key-value store	Cloudflare KV	Sessions, configuration, hot dashboards cache.
Object store	Cloudflare R2	Evidence packs, exports, long-term cold ledger snapshots.
Authentication	JWT (signed at edge); OAuth (Google/MS) for SSO	Standards-based; member self-service.
Payments	Stripe Connect (Express accounts)	Australian-supported; KYC/AUSTRAC handled by Stripe.
Email / SMS	Resend (email), Twilio (SMS)	Reliable transactional delivery.
Observability	Cloudflare Analytics + Workers Logs; Sentry for errors	Out-of-the-box edge telemetry.
CI/CD	GitHub Actions → Wrangler deploy	Trunk-based, sprint-cadence releases.
Front-end	Hono JSX (server-rendered) + Tailwind CDN + lightweight Alpine.js where needed	No SPA bloat; member portal feels instant.

9.2 Deployment Topology

flowchart LR DEV[Developer Laptop
wrangler dev] GH[GitHub
main branch] CI[GitHub Actions
build + test] STG[Cloudflare Pages
staging.flip360] PROD[Cloudflare Pages
app.flip360] DEV --> GH --> CI --> STG --> PROD style PROD fill:#c9a961,color:#0a1628

10

Chapter Ten

Performance & Leaderboard Analytics

Analytics in Flip 360 are deliberately narrow and deliberately deep. We do not compete with Tableau on breadth — we beat it on fit. Every metric the platform exposes is a metric that drives the active+passive walking thesis.

10.1 The Member Dashboard — The Core Five

Metric	What It Tells the Member
Passive Income — Actual vs Target	Are you on track this month to hit your right-leg target?
Referrals Sent — Actual vs Target	Are you taking enough right-leg steps?
Conversion Rate	Of the referrals you sent, what % became income?
Reciprocity Score	For every $1 you generated for others, how much active income returned to you?
ADKAR Stage	Where are you on the capability curve?

10.2 Leaderboard — Top 20% / Bottom 20%

Leaderboard is computed daily across three windows: rolling 30 days, current quarter, all-time. Members opt in to be visible by name; otherwise displayed as "Member #1247". The leaderboard surfaces:

Top quintile — celebrated publicly; their stories feed the Volunteer Army (Kotter Step 4).
Middle three quintiles — given quintile-relative coaching nudges.
Bottom quintile — automatically flagged for Performance Coach outreach (ADKAR intervention).

10.3 Reciprocity — The Walking Metric

The thesis predicts that active referrers attract reciprocal active income. We measure this directly:

reciprocity_ratio = (active_income_received_via_inbound_referrals)
                  ÷ (passive_income_generated_for_others)

A ratio > 1 means the member earns more active income from being a Flip 360 member
than they pay out in commissions for outbound referrals.
This is the empirical proof of the walking metaphor.
  

11

Chapter Eleven

ADKAR Capability Engine

Volume 1 established ADKAR as the change framework. Volume 2 makes it a first-class engine of the platform. Every member has a current ADKAR stage; transitions are event-driven; interventions are automated.

11.1 Stage Transition Logic

Stage	Entry Trigger	Exit Criteria	System Action
A — Awareness	Sign-up	Member views walking-thesis content + first leaderboard	Welcome sequence; orientation
D — Desire	Awareness complete	Member explicitly opts in to a vertical	Surface peer case studies in their vertical
K — Knowledge	Vertical join	Member completes onboarding training	Push training; quiz checkpoints
A — Ability	Training complete	Member sends 3 referrals, 1 of which qualifies	Coaching nudges; "send your first" prompts
R — Reinforcement	First commission received	Sustained 90 days at or above quintile target	Leaderboard recognition; targets advance

11.2 Intervention Triggers

Member stuck at any stage for > 30 days → automated coach outreach.
Member regresses to a lower quintile for two consecutive periods → human Performance Coach assigned.
Member hits target → public leaderboard recognition + next-tier target set.

12

Chapter Twelve

User Stories — Seeded Backlog

The 30 user stories below seed the Product Backlog. Each is in canonical "I am... I need... so I can..." form, with priority (Must/Should/Could) and the actor identified. The squad will refine these at the first Backlog Refinement session.

Epic 1 — Member Onboarding (VS-2)

US-001

Register a Business

Referring MemberMUST

I am a prospective member, I need to register my business with legal name, ABN, GST status, primary contact and bank details, so I can begin sending and receiving referrals under a verifiable identity.

Acceptance: ABN validates against ABR; duplicate registration blocked; welcome email issued; ADKAR set to "A".

US-002

Join a Vertical

MemberMUST

I am a registered member, I need to join one or more verticals (e.g. mortgage broking, conveyancing) relevant to my business, so I can receive vertical-appropriate referrals and have the right commission rules applied to my activity.

Acceptance: Vertical eligibility validated; membership event written to the chain; ADKAR moves to "D" then "K".

US-003

Complete Onboarding Training

MemberSHOULD

I am a newly joined member, I need to complete a short onboarding module on how Flip 360 works, so I can confidently send my first referral and understand my entitlement.

US-004

Connect Bank Account via Stripe Connect

MemberMUST

I am a registered member, I need to securely connect my Australian bank account via Stripe Connect, so I can receive commission payouts without sharing raw bank details with the platform.

Epic 2 — The Trust Engine (VS-1, core)

US-005

Send a Referral

Referring MemberMUST

I am a referring member, I need to create a referral by selecting a receiving member and providing client/lead details, so I can establish an immutable, time-stamped, hash-chained record of my action.

Acceptance: Event appended; content_hash + prior_hash verified on read; receiver notified within 60s.

US-006

Acknowledge a Referral

Receiving MemberMUST

I am a receiving member, I need to acknowledge that I have received the referral, so the sender has cryptographic proof I am in possession of the lead.

US-007

Qualify a Lead

Receiving MemberMUST

I am a receiving member, I need to mark a lead as qualified or unqualified after contact, so the system understands which referrals are in the conversion pipeline.

US-008

Record a Conversion & Income Event

Receiving MemberMUST

I am a receiving member, I need to record that the referral converted into a deal and attest to the active income amount earned, so the system can deterministically calculate the commission owed.

Acceptance: Income event signed; entitlement auto-calculated; sender notified of entitlement amount.

US-009

Calculate Entitlement (System)

SystemMUST

I am the Commission Engine, I need to apply the time-versioned commission rule active at the referral's date to the income event amount, so I can produce an entitlement that is deterministic, replayable, and provable.

Acceptance: Re-running calc against same inputs produces byte-identical output; banker's rounding applied; GST split correct where applicable.

US-010

Verify the Hash Chain

System / AuditorMUST

I am an auditor, I need to walk the full event chain and verify every hash linkage, so I can confirm the integrity of the ledger has not been compromised.

Epic 3 — Payouts & Reconciliation

US-011

Run a Payout Batch

Payout OfficerMUST

I am the Payout Officer, I need to assemble all earned-but-unpaid entitlements into a single payout batch for a given period, so I can release member commissions in a controlled, reconciliable cycle.

US-012

Reconcile Bank Movement

Payout OfficerMUST

I am the Payout Officer, I need to reconcile actual bank transfers against the payout batch line-by-line, so I can confirm zero variance between ledger and money.

US-013

Generate Recipient Created Tax Invoice (RCTI)

SystemMUST

I am the system, I need to generate an RCTI for each GST-registered member's payout, so the member meets ATO documentation obligations without manual paperwork.

Epic 4 — Dispute & Evidence

US-014

Raise a Dispute

MemberMUST

I am a member, I need to raise a dispute against any referral, entitlement or payout I believe to be incorrect, so I can have my concern formally examined with full ledger evidence.

US-015

Generate an Evidence Pack

Auditor / MemberMUST

I am an auditor or affected member, I need to generate a self-contained, tamper-evident evidence pack for any entitlement, so I can resolve disputes from system evidence alone in under 60 seconds.

US-016

Issue an Adjustment or Reversal

AdministratorMUST

I am an administrator, I need to issue a compensating adjustment or reversal event to correct an entitlement, so the ledger remains immutable while still allowing legitimate corrections.

Epic 5 — Configuration & Verticals

US-017

Add a New Vertical

AdministratorMUST

I am an administrator, I need to add a new vertical (e.g. "Builders") with regulator metadata and default commission rule, so the network expands without code change.

US-018

Author a Commission Rule

Vertical ManagerMUST

I am a Vertical Manager, I need to author a new commission rule with an effective_from date, so future referrals in my vertical use the new rate while past referrals retain their original rate.

Epic 6 — Performance & ADKAR

US-019

View My Dashboard

MemberMUST

I am a member, I need to see my actual-vs-target passive income, referrals sent, conversion rate, reciprocity score and ADKAR stage on a single screen, so I can understand at a glance whether I am walking or hopping.

US-020

View Leaderboard

MemberMUST

I am a member, I need to see how I rank in the top/bottom 20% across rolling 30-day, current-quarter and all-time windows, so I can compete and benchmark within my vertical and across the network.

US-021

Set Targets

Product Owner / MemberMUST

I am the Product Owner (or a member setting personal targets), I need to set monthly referral and passive-income targets per member or per cohort, so the actual-vs-target measurement has a denominator.

US-022

Trigger an ADKAR Intervention

System → CoachSHOULD

I am the ADKAR engine, I need to flag members stuck at a stage >30 days or regressing into the bottom quintile, so a human Performance Coach is automatically routed to them with context.

Epic 7 — Audit, Compliance & Export

US-023

Export My Data

MemberMUST

I am a member, I need to export all my referrals, entitlements and payouts as CSV plus evidence packs, so I can maintain my own records and meet my own audit obligations.

US-024

Audit the Chain

AuditorMUST

I am an auditor, I need to walk the full hash chain and receive a signed integrity certificate, so I can attest to the integrity of the ledger for a given audit period.

US-025

Publish Daily Merkle Root

SystemSHOULD

I am the system, I need to publish a daily Merkle root of the event log to immutable R2 storage, so the chain has an additional tamper-evident anchor independent of the live database.

Epic 8 — Integrations

US-026

Receive Referrals from External CRM

External CRMCOULD

I am an external CRM (member-owned), I need to POST referral events into Flip 360 via authenticated API, so the member's existing workflow surfaces the referral without double-entry.

US-027

Settle Payout via Stripe Connect

Payout Officer / SystemMUST

I am the system, I need to instruct Stripe Connect to transfer payout amounts to member accounts, so money movement is initiated automatically from the reconciled payout batch.

Epic 9 — Governance & Product Owner

US-028

Product Owner — System-Wide Read

Product OwnerMUST

I am the Product Owner, I need to see every member, every referral, every entitlement and every payout in one read-only console, so I can understand the health of the entire network at a glance.

US-029

Capture an Idea (Idea Inbox)

Product OwnerSHOULD

I am the Product Owner, I need to capture any new idea I have on-the-fly via a single-field web inbox, so no idea is ever lost and every idea enters the formal triage flow.

US-030

Programme Dashboard

Steering CommitteeSHOULD

I am the Steering Committee, I need to see velocity, burndown, RAG status and top RAID items on a single page, so I can govern the programme with one page per month, not a deck.

13

Chapter Thirteen

Non-Functional Requirements

NFRs are the qualities of the system: how fast, how safe, how recoverable, how trustworthy. In a financial-grade system, NFRs are first-class citizens, not afterthoughts.

Category	Requirement	Target	How Measured
Performance	Member dashboard load	P95 < 800ms global	RUM (Real User Monitoring) via Cloudflare
Performance	Referral submission	P95 < 400ms	API metrics
Performance	Evidence Pack assembly	P95 < 60s	Server timing
Availability	Member portal uptime	99.9% monthly (≤ 43 min downtime)	Synthetic monitoring
Durability	Event log retention	100% of events retained for life of programme; daily R2 snapshot	Snapshot verification
Integrity	Hash chain unbroken	Zero broken links	Nightly chain walk
Integrity	Determinism	Re-calc produces byte-identical entitlement	Property-based tests
Security	Authentication	JWT with short-lived access tokens; refresh via secure cookie	Pen-test
Security	PII at rest	Encrypted via Cloudflare-managed keys	Cloudflare audit
Recoverability	RPO (data loss tolerance)	< 5 min	D1 + R2 backup cadence
Recoverability	RTO (time to restore)	< 4 hours	DR rehearsal quarterly
Auditability	Every state change logged	100%	Coverage report
Accessibility	WCAG 2.1 AA	Conformance on all member-facing surfaces	Automated + manual audit
Privacy	Australian Privacy Principles (APP 1-13)	Full compliance	Privacy Impact Assessment

14

Chapter Fourteen

Security, Privacy & Compliance

14.1 The Compliance Landscape

Regulator / Framework	Applicability	Posture
Australian Privacy Act 1988 / APPs	All personal information held about members and leads	Privacy Policy + Collection Statement; APP-compliant by design
ASIC — NCCP Act	Mortgage broking referrals	Member-level disclosure of referral fees; conflict-of-interest tooling
ASIC — Corporations Act / AFSL	Financial advice / insurance referrals	Referrals only, not advice; statement-of-referrer wording
ATO — GST & RCTI	Commission payments to GST-registered members	RCTI generation; GST split on Entitlements
AUSTRAC	Money movement	Handled by Stripe Connect (regulated entity)
TPB	Tax agent referrals	Member-level disclosure

14.2 Security Principles

Defence in depth — WAF (Cloudflare) → AuthN → AuthZ → Validation → Persistence → Encryption.
Least privilege — every role has the minimum permissions to do its job; no shared admin accounts.
Zero trust on inbound — every request authenticated and authorised at the edge.
Secrets management — all keys in Cloudflare Workers Secrets / Wrangler; never in source.
Audit on every privileged action — admin actions append events to the chain just like member actions.

14.3 Data Classification

Class	Examples	Storage / Treatment
Public	Vertical names, marketing copy	Cacheable at edge
Member-internal	Targets, dashboards, leaderboard rank	D1; member-scoped read
Sensitive	Client/lead contact details, ABN, deal value	D1 with field-level encryption for PII
Restricted	Bank account references (tokenised by Stripe)	Never stored raw; Stripe references only

15

Chapter Fifteen

Release Plan & Sprint Roadmap

The first six sprints (12 weeks) take Flip 360 from empty repository to first commission paid through the platform with full evidence. Each sprint produces a working, demonstrable Increment.

Sprint	Goal	Key Stories	Definition of Success
Sprint 1	Trust foundations	US-009, US-010, US-024, US-025	Append-only event log live; hash chain walks clean end-to-end; nightly Merkle root publishes.
Sprint 2	Members & verticals	US-001, US-002, US-017, US-018	First three pilot businesses registered; one vertical (mortgage) live with v1 commission rule.
Sprint 3	The referral loop	US-005, US-006, US-007, US-008	First end-to-end referral: sent → acked → qualified → converted → income recorded.
Sprint 4	Entitlement & evidence	US-009 (deepen), US-015, US-016	First entitlement calculated and an evidence pack assembled for it in <60s.
Sprint 5	Payout & reconcile	US-004, US-011, US-012, US-013, US-027	First payout batch settled via Stripe Connect; RCTI issued; bank reconciled to zero variance.
Sprint 6	Member portal & leaderboard	US-019, US-020, US-021, US-029	Members see their own dashboard, leaderboard rank, and targets; Mathew's Idea Inbox live.

Post-MVP Increments (Sprints 7+)

Sprints 7–8: ADKAR engine, intervention triggers, performance coach console (US-022).
Sprints 9–10: External CRM API (US-026), advanced rule types (tiered, hybrid).
Sprints 11–12: Second vertical onboarded (Conveyancing or Insurance) as the extensibility proof.
Sprint 13: HubSpot decommission cutover after three clean payout cycles.

16

Chapter Sixteen

Architectural Decision Records (ADRs)

Every architecturally-significant decision is captured as a short ADR (Michael Nygard format). Below are the seven foundational ADRs adopted at programme inception. New ADRs accumulate in the repository as the system evolves.

ADR-001 · Accepted

Edge-first runtime on Cloudflare Workers

Context: Global member base needs sub-100ms latency; zero-ops preferred. Decision: Cloudflare Workers + Pages with Hono. Consequences: No Node-specific APIs; embrace Web Platform.

ADR-002 · Accepted

Append-only event log as the system of record

Context: Forensic accuracy non-negotiable. Decision: All state derives from an immutable, hash-chained event log; relational tables are materialised projections. Consequences: Higher write discipline; massive audit benefit.

ADR-003 · Accepted

Integer cents for all monetary values

Decision: No floats anywhere in the money path. Consequences: All UI formats from integer cents at the boundary.

ADR-004 · Accepted

Cloudflare D1 as the primary relational store

Decision: Use D1 (SQLite) at edge. Consequences: Constraints on transaction model; mitigated by event-sourcing pattern.

ADR-005 · Accepted

Stripe Connect for payouts

Decision: Stripe Connect Express accounts; KYC/AUSTRAC offloaded to Stripe. Consequences: Stripe fees in unit economics; faster compliance posture.

ADR-006 · Accepted

No public blockchain anchoring at MVP

Decision: Use internal hash chain + daily Merkle root in R2; reconsider third-party timestamping post-MVP. Consequences: Privacy preserved; performance preserved.

ADR-007 · Accepted

Server-rendered JSX over SPA

Decision: Hono JSX rendering with progressive enhancement; no React SPA. Consequences: Faster TTI; simpler architecture; less front-end churn.

Enterprise Architecture & Solution Design

Volume 2

Architecture Vision & Principles

1.1 Architecture Vision

1.2 The Ten Architecture Principles

1.3 What This Architecture Deliberately Is Not

The Trust Equation — Formalised

2.1 The Causation Chain

2.2 The Mathematical Statement

2.3 The Evidence Pack

Business Architecture & Actors

3.1 The Actor Catalogue

3.2 Actor Map

3.3 Value Streams

VS-1 · Refer-to-Earn

VS-2 · Onboard-to-Active

VS-3 · Perform-to-Improve

Use Case Catalogue & Diagrams

4.1 Master Use Case Diagram

4.2 Use Case Specifications — Selected

UC-03 · Send a Referral

UC-07 · Calculate Entitlement

UC-12 · Assemble Evidence Pack

Information Architecture & Entity Model

5.1 Logical Entity Model

5.2 Core Tables — Schema Sketch

5.3 Event Types — The Complete Vocabulary

The Immutable Event Log & Hash Chain

6.1 Canonical Payload & Hashing

6.2 The Chain Visualised

6.3 Why Not Use a Public Blockchain?

6.4 Integrity Checks

The Commission Engine

7.1 Engine Responsibilities

7.2 Rule Types Supported (MVP)

7.3 Rounding Policy

7.4 GST Handling

Application Architecture

8.1 Logical Component View

8.2 Why Hono on Cloudflare?

8.3 Module Boundaries (Source Layout)

Technology Architecture

9.2 Deployment Topology

Performance & Leaderboard Analytics

10.1 The Member Dashboard — The Core Five

10.2 Leaderboard — Top 20% / Bottom 20%

10.3 Reciprocity — The Walking Metric

ADKAR Capability Engine

11.1 Stage Transition Logic

11.2 Intervention Triggers

User Stories — Seeded Backlog

Epic 1 — Member Onboarding (VS-2)

Epic 2 — The Trust Engine (VS-1, core)

Epic 3 — Payouts & Reconciliation

Epic 4 — Dispute & Evidence

Epic 5 — Configuration & Verticals

Epic 6 — Performance & ADKAR

Epic 7 — Audit, Compliance & Export

Epic 8 — Integrations

Epic 9 — Governance & Product Owner

Non-Functional Requirements

Security, Privacy & Compliance

14.1 The Compliance Landscape

14.2 Security Principles

14.3 Data Classification

Release Plan & Sprint Roadmap

Post-MVP Increments (Sprints 7+)

Architectural Decision Records (ADRs)

The blueprint is set.