SalesFam Platform — Functional Requirements Specification (FRS)
Document Version: 1.0 Status: Draft / Active Review Core Architecture Model: Company → SalesFam → Sales Representative → Customer
Purpose: Defines the functional behavior and business rules of the SalesFam platform. This document section serves as the functional baseline for product, design, and engineering decisions.
Document Control & System Actors
System Actors
- Guest: An unauthenticated visitor interacting with publicly accessible parts of the platform.
- Company (Merchant): The party that provides products and is responsible for the associated commercial and fulfillment operations.
- Sales Representative (Promoter): An independent or company-associated party that promotes authorized products and earns commissions from attributed sales.
- SalesFam Admin (Platform Operator): The platform operator responsible for system administration, financial oversight, and operational control.
Functional Scope
SalesFam connects Companies, Sales Representatives, and Customers through a centralized platform. Companies provide products/services, Sales Representatives generate attributed sales, and Customers purchase through the platform. SalesFam manages the relationships, transaction attribution, order lifecycle, commission calculation, and settlement processes between these parties.
Core Functional Boundaries
The FRS covers the functional behavior of:
- Identity & Access
- Merchant/Business & Product Management
- Rep/User Onboarding & Commission Contracts
- Referral Attribution
- Checkout & Payment Processing
- Webhook & Order Finalization
- Financial Ledger & Settlement
- Payout Management
How this chapter is organized
Each Functional Requirement gets its own subfolder (fr-01-iam/, fr-02-merchant-product/, ...), and each individual sub-requirement inside it (FR-01.01, FR-01.02, ...) is its own page, following a fixed template: Trigger → System shall → State → Acceptance Criteria.
| FR | Name | Status |
|---|---|---|
| FR-01 | Authentication, Identity & Access Management (IAM) | Fully specified (13 sub-requirements) |
| FR-02 | Merchant & Product Management | Scope defined, sub-requirements not yet written |
| FR-03 | Rep Onboarding & Commission Contracts | Not started |
| FR-04 | Referral Attribution Engine | Not started |
| FR-05 | Checkout & Payment Processing | Not started |
| FR-06 | Webhook Processing & Order Finalization | Not started |
| FR-07 | Financial Ledger, Settlement & Payouts | Not started |
Adding a new FR
Don't hand-write the Markdown file. From the repository root, run:
npm run new:fr
This opens a local form (http://localhost:4000 by default) with one field per part of the template — Trigger, System shall items, State transition, PASS/FAIL Acceptance Criteria. On submit it:
- Figures out the next available sub-requirement number inside the FR group you pick (or creates a new FR group, e.g.
FR-03, if you're starting one). - Writes the
.mdfile in the right folder with the correct frontmatter andsidebar_positionalready set. - Leaves the file staged for you to review, edit further if needed, and commit — it never commits or pushes on its own.
See scripts/new-fr.js if you want to see exactly what it generates.