Problem
No entitlement/tiering model exists today -- every user gets identical access. The mission requires a server-enforced free/pro entitlement architecture (not client-side feature hiding) before any billing integration is even considered.
Repository evidence
No entitlement/tier/subscription concept found in server/src/db/schema.ts or auth/session code.
Risk
P2 -- valuable for the product roadmap but explicitly not release-blocking; explicitly must not be bundled with market-data/wallet/chart/backtesting work per mission instruction.
Scope
- Server-side entitlement model:
free, pro, defaulting all existing/guest users to free.
- Enforce entitlement limits server-side for whatever features already exist that map to the proposed tiering (e.g. backtest date-range/history limits, signal-history limits) -- do not gate features that don't exist yet.
docs/product/monetization.md and docs/product/entitlements.md describing the full free/pro proposal and future B2B directions, per the mission brief.- Privacy-respecting product analytics events: guest activation, chart engagement, first paper order, first completed paper trade, backtest completion, return visits, wallet connection, upgrade-view engagement -- without logging unnecessary wallet/financial detail.
Non-goals
No billing provider integration (explicit non-goal -- Stripe/etc. requires a separately authorized issue covering checkout, webhook verification, idempotency, reconciliation, refunds, tax, cancellation, privacy, security review). No hidden fees, no guaranteed-return-based upsells, no builder-code monetization while paper-only.
Dependencies
Best sequenced after BACKTEST-001/SIGNAL-SCORE-001 exist (so there's something real to gate), but the entitlement model itself has no hard technical dependency.
Proposed implementation
An entitlements column/table on the account model (wallet or guest) with a small server-side middleware/helper checking tier before allowing a gated action; client reads entitlement state for UI purposes only, never as the authorization boundary.
Acceptance criteria
A free-tier account is server-side blocked (not just UI-hidden) from any action documented as pro-only; entitlement defaults correctly for both new guest and new wallet accounts.
Definition of done
Server tests prove entitlement enforcement can't be bypassed by direct API calls even with client-side gating removed; reviewer PASS; both product docs published.
Test plan
Direct API-level tests attempting a pro-gated action as a free-tier account (expect rejection) and as a pro-tier account (expect success); analytics-event emission tests for the listed events.
Security review
Entitlement checks must happen server-side on every gated route, not trusted from client-supplied state.
Accessibility review
N/A.
Observability requirements
Log entitlement-rejection events by feature/reason.
Performance considerations
Entitlement check should be a cheap lookup, not a query storm per request.
Rollback plan
Revert PR; defaulting everyone to free with no gated features yet means no user-visible regression risk.
Documentation requirements
docs/product/monetization.md, docs/product/entitlements.md.
Completion evidence
(added on merge)
Reviewer verdict
(pending)
Problem
No entitlement/tiering model exists today -- every user gets identical access. The mission requires a server-enforced free/pro entitlement architecture (not client-side feature hiding) before any billing integration is even considered.
Repository evidence
No
entitlement/tier/subscriptionconcept found inserver/src/db/schema.tsor auth/session code.Risk
P2 -- valuable for the product roadmap but explicitly not release-blocking; explicitly must not be bundled with market-data/wallet/chart/backtesting work per mission instruction.
Scope
free,pro, defaulting all existing/guest users tofree.docs/product/monetization.mdanddocs/product/entitlements.mddescribing the full free/pro proposal and future B2B directions, per the mission brief.Non-goals
No billing provider integration (explicit non-goal -- Stripe/etc. requires a separately authorized issue covering checkout, webhook verification, idempotency, reconciliation, refunds, tax, cancellation, privacy, security review). No hidden fees, no guaranteed-return-based upsells, no builder-code monetization while paper-only.
Dependencies
Best sequenced after
BACKTEST-001/SIGNAL-SCORE-001exist (so there's something real to gate), but the entitlement model itself has no hard technical dependency.Proposed implementation
An
entitlementscolumn/table on the account model (wallet or guest) with a small server-side middleware/helper checking tier before allowing a gated action; client reads entitlement state for UI purposes only, never as the authorization boundary.Acceptance criteria
A
free-tier account is server-side blocked (not just UI-hidden) from any action documented as pro-only; entitlement defaults correctly for both new guest and new wallet accounts.Definition of done
Server tests prove entitlement enforcement can't be bypassed by direct API calls even with client-side gating removed; reviewer PASS; both product docs published.
Test plan
Direct API-level tests attempting a pro-gated action as a free-tier account (expect rejection) and as a pro-tier account (expect success); analytics-event emission tests for the listed events.
Security review
Entitlement checks must happen server-side on every gated route, not trusted from client-supplied state.
Accessibility review
N/A.
Observability requirements
Log entitlement-rejection events by feature/reason.
Performance considerations
Entitlement check should be a cheap lookup, not a query storm per request.
Rollback plan
Revert PR; defaulting everyone to
freewith no gated features yet means no user-visible regression risk.Documentation requirements
docs/product/monetization.md,docs/product/entitlements.md.Completion evidence
(added on merge)
Reviewer verdict
(pending)