rwo-docs/docs/prototype-plan.md

Prototype Plan

Purpose

Build the smallest functional prototype that proves the core wedge for this company:

a verified customer payment can become an auditable commission balance, and a safe portion of that balance can be accessed quickly through the relevant local payout rail

This prototype should validate three things at once:

• employers trust the platform to calculate and track commissions
• employees understand and value faster access to earned commissions
• the operating model works with partner-led custody and conservative availability rules

Prototype philosophy

This should be an ops-backed product prototype, not a full production fintech stack.

The prototype should be good enough to demo to design partners and, if needed, support a tightly controlled pilot with manual operations behind the scenes.

That means:

• real product flows where they matter
• mocked or manual partner workflows where regulation or integration would slow learning
• a real commission ledger and audit trail from day one
• conservative rules for reversals, reserves, and payout eligibility

Core hypothesis

If an employer with a commission-heavy team can see commissions generated from payment events in near real time, and if employees can access the available portion of those commissions through the relevant local payout rail, then the company will have a strong design-partner wedge.

Primary prototype users

Employer admin

Usually finance, operations, founder, or sales management.

Needs to:

• define a commission rule
• see payment-linked commissions
• understand current commission liability
• review payouts and adjustments
• trust the audit trail

Employee

Usually a salesperson or commission-earning worker.

Needs to:

• see what has been earned
• see what is available
• understand what is still pending or held in reserve
• request a payout to a linked bank destination
• trust that the numbers are correct

Internal ops admin

Used by the startup team during the prototype.

Needs to:

• onboard employers manually
• ingest payment events
• review KYC or employer setup issues
• approve or simulate payouts
• process reversals and adjustments

Prototype scope

In scope

1. Employer setup

• create employer account manually through an internal admin tool
• create teams or stores
• invite or upload employees through CSV
• configure one simple commission plan per team
• register employer settlement preferences

2. Payment ingestion

Support two prototype ingestion modes:

• webhook simulator for demos
• CSV upload for early design partners

Each payment event should include at minimum:

• employer
• customer payment reference
• employee or seller attribution
• gross amount
• payment status
• timestamp

3. Commission calculation

Keep rules narrow for the first prototype.

Support:

• flat percentage commission
• optional per-employee override
• optional reserve or holdback percentage for availability

Do not try to support every real-world compensation edge case yet.

4. Commission ledger

This is the most important part of the prototype.

Track balances in three states:

• earned
• available
• settled

Also track:

• payout requests
• reserves or holdbacks
• reversals
• manual adjustments
• fees, if needed for reporting

Every payment-triggered commission event should create an immutable audit trail.

5. Employee balance view

Mobile-first web experience that shows:

• current earned, available, and settled balances
• transaction history
• payout history
• current payout destination on file
• payout request button

6. Local payout flow

For the prototype, use partner-led abstractions and manual controls.

Support:

• employee submits payout request
• system checks available balance and payout limits
• ops admin approves or auto-approves based on simple rules
• payout is marked as sent and completed through a mocked or manually triggered partner adapter

7. Employer dashboard

Minimal dashboard showing:

• recent payment events
• commissions created today and this week
• current commission liability
• total already paid out
• pending adjustments or reversals
• employee-level history

8. Reversal and adjustment flow

At least one negative event flow must exist in the prototype.

Support:

• payment reversal or refund event
• system creates a negative commission adjustment
• impact is shown in employer and employee histories
• if necessary, the adjustment reduces future availability rather than trying to claw back immediately

Out of scope

Keep these out of the first prototype:

• stored balance as a major product surface
• card issuance
• employer-backed advance
• any standalone credit product
• full payroll integration
• broad ERP, CRM, or POS integrations
• multi-entity support
• sophisticated forecasting or BI
• automated labor and tax logic
• consumer-grade banking features

Prototype scenario to optimize for

Use one clear happy-path demo story.

Example

• employer: aesthetic clinic group
• employee: seller named Ana
• rule: 20 percent commission on completed payments
• availability rule: 70 percent of commission becomes immediately available; 30 percent stays held until settlement
• customer payment: 1,000 in local currency

System behavior:

• payment received: 1,000 in local currency
• commission calculated: 200 earned
• immediate availability: 140 available
• held amount: 60 pending settlement
• Ana requests a 100 payout to her linked bank destination
• employer dashboard updates liability and payout history

This single scenario should work end to end before adding more complexity.

Recommended product flows

Flow 1: Employer onboarding

1. ops creates employer
2. employer admin logs in
3. employer uploads employees or assigns seller IDs
4. employer selects a simple commission rule
5. employer confirms reserve and availability settings

Flow 2: Payment to commission

1. payment event enters through webhook simulator or CSV
2. system validates employer and seller mapping
3. commission engine calculates commission result
4. ledger records earned
5. availability policy releases eligible amount to available
6. employer and employee dashboards update

Flow 3: Employee payout

1. employee opens mobile web app
2. employee sees available balance
3. employee requests payout to the registered bank destination
4. payout request is validated
5. payout is sent through mocked or manual partner adapter
6. ledger records the payout and reduces available

Flow 4: Refund or reversal

1. refund event is posted
2. system creates negative adjustment against commission
3. held reserve absorbs the loss first
4. if reserve is insufficient, future availability is reduced
5. employer and employee both see the adjustment trail

Product decisions for the prototype

Source of truth

Use the customer payment event as the default trigger for commission creation whenever possible.

Availability policy

Do not make all earned commissions instantly withdrawable.

For the prototype, choose one conservative rule such as:

• 50 to 70 percent of a commission becomes available immediately
• remaining amount stays held until a defined settlement event or time window

Money movement model

Do not represent the startup as directly holding funds.

The prototype should frame all custody and regulated movement as partner-led, even if the integration is mocked.

Rule complexity

Support only the smallest useful rule set first.

Good first version:

• one flat commission percentage per team
• employee-specific overrides
• reserve percentage

Avoid tiers, quotas, split commissions, and retroactive accelerators in v0.

Technical shape of the prototype

A simple but durable architecture is enough.

Suggested stack

• frontend: Next.js + TypeScript + Tailwind
• backend: TypeScript API routes or a small Node service
• database: PostgreSQL
• auth: magic link or OTP-based login
• hosting: Vercel, Render, or Fly.io
• file upload: CSV upload for payment events and employee imports

Core modules

• employer management
• employee management
• payment ingestion
• commission engine
• commission ledger
• payout orchestration
• admin ops console
• audit log

Integration adapters

Define adapters even if they are mocked.

• PaymentProviderAdapter
• LocalPayoutAdapter
• KycProviderAdapter

This keeps the prototype aligned with the long-term partner-led model and avoids hard-coding demo logic everywhere.

Minimal data model

The first version likely needs these core entities:

• employers
• employees
• commission_plans
• payment_events
• commission_results
• ledger_accounts
• ledger_entries
• payout_requests
• adjustments
• audit_events

Balance logic

At minimum, model separate balances for:

• employee earned
• employee available
• employee settled
• employer liability
• reserve or holdback balance

Prototype screens

Employer-facing

• login
• employer overview dashboard
• employee list
• commission rule setup
• payment event feed
• commission history by employee
• payout history
• adjustments view

Employee-facing

• login
• balance home
• transaction history
• payout request screen
• payout receipt or status screen

Internal ops

• employer creation
• employee import support
• payment event simulator
• payout approval queue
• adjustment and reversal tool

Success criteria

The prototype is successful if it can demonstrate all of the following in one controlled flow:

• an employer can be configured in under 30 minutes
• a payment event generates a commission and updates balances automatically
• an employee understands earned versus available
• an employee can request a payout from the available balance
• a refund or reversal creates a visible adjustment without breaking the ledger story
• an employer can view liability, payouts, and audit history without relying on spreadsheets

What should be faked or manual at first

To move faster, these can be manual in the first prototype:

• KYB and KYC review
• employer contract setup
• payment provider onboarding
• actual payout movement through a partner
• exception handling and customer support
• settlement reconciliation edge cases

Manual operations are acceptable as long as the product surface still teaches the right workflow.

Build sequence

Week 1: definition and UX

• lock target design-partner vertical
• write product requirements for the prototype
• define the event model
• sketch employer and employee screens
• finalize one default commission and reserve policy

Week 2: domain and ledger

• implement payment event ingestion
• implement commission calculation
• implement balance state transitions
• implement audit trail
• seed one demo employer with sample data

Week 3: employer product surface

• employer login
• employee upload
• commission rule setup
• payment and commission dashboards

Week 4: employee product surface

• employee login
• balance screen
• payout request flow
• payout history

Week 5: ops and failure paths

• payout approval queue
• reversal and adjustment flow
• webhook simulator
• CSV imports

Week 6: polish and design-partner readiness

• improve copy and onboarding
• add demo data scripts
• record a product walkthrough
• prepare pilot runbook and support checklist

Open questions before building

• which vertical should the first demo represent: clinics, education, franchise retail, or another segment?
• will the first prototype use only simulated payments, or one real payment source?
• what immediate availability percentage is safe enough for the first demo?
• should commission be recognized on payment authorization or only on confirmed settlement?
• how will seller attribution be supplied in the first design-partner workflow?
• what is the first refund and chargeback policy the employer can accept?

Recommended next deliverables

After this plan, the next useful documents would be:

• a short product requirements doc for the prototype
• wireframes for employer and employee flows
• an event model spec for payments, commissions, payouts, and adjustments
• a partner-interface spec for mocked local payouts, KYC, and payment ingestion

Bottom line

The right prototype is not a broad fintech app.

It is a narrow commission infrastructure demo that proves one loop extremely well:

payment event -> commission calculation -> earned and available balance -> local payout -> employer visibility and audit trail