Architecture Reference
A technical walkthrough of FanSignal OS: how it is designed, how the data model works, how modules integrate, and the engineering decisions behind the implementation.
The Platform Operating Loop
Every module in FanSignal OS feeds a five-stage loop: Signal → Intelligence → Action → Measurement → Decision. The loop is not a diagram. It is the integration contract every module must satisfy. A module that captures signals but does not feed the intelligence layer is a dead end. A module that creates actions but does not close measurement is unaccountable.
- 01Signal: fan behavior captured across ticketing, bot, events, surveys, and content interactions
- 02Intelligence: signals classified by lifecycle stage, persona archetype, and commercial urgency
- 03Action: CRM journeys, content briefs, and partner interventions triggered automatically from intelligence layer output
- 04Measurement: dashboard KPIs tracking conversion, retention, and attribution per signal source
- 05Decision: prioritized recommendations surfacing the next business decision, not just the next report
Design Intent
The loop is stateless per turn but stateful across time. Each pass through the loop updates the fan's lifecycle stage, which changes the intelligence output on the next pass. This is the core feedback mechanism: behavior changes classification, classification changes action, action changes behavior.
Engineering Decisions
Key decisions with rationale and acknowledged tradeoffs.
Decision
Contract-first data design
Rationale
TypeScript interfaces defined before any data was written. Shape is the contract: data generation, page rendering, and component props all import from the same interface.
Tradeoff
Slightly more upfront work defining interfaces before generating data. In return: zero silent schema drift, full type safety across the stack, and a searchable schema.
Decision
Synthetic data over mock APIs
Rationale
All platform data lives in lib/ TypeScript files compiled into the build. No runtime fetching, no external dependencies, no PII compliance questions.
Tradeoff
Data is static; no real-time updates. In return: the platform runs anywhere, deploys in one command, and never fails due to an unavailable API.
Decision
Server components by default
Rationale
Next.js App Router server components reduce client bundle size and make the rendering model explicit. Client components are only used where interactivity is required.
Tradeoff
Some component patterns from older Next.js tutorials do not apply. In return: smaller bundles, faster initial load, and clear separation of concerns.
Decision
One module, one route
Rationale
Each platform capability has a dedicated URL. This makes every module independently linkable, deep-linkable from a walkthrough, and separately navigable by any stakeholder.
Tradeoff
More route files to maintain. In return: the platform is navigable without explanation: any stakeholder can bookmark any module and return directly.
Coming Soon: data pipeline in progress · FanSignal OS