leads4less/TODO-pricing.md

TODO: LocaleScope Pricing & Packaging Design

Goals

• Position LocaleScope as a local market intelligence platform, not a scraper/export commodity.
• Align pricing, packaging, product capabilities, and billing enforcement to a single plan model.
• Protect infrastructure with quotas, credits, throttling, and priority processing.
• Preserve room for future AI, enrichment, API, collaboration, and enterprise expansion.

Open Questions

• What is the initial break-glass process if all app admins are disabled or misconfigured (seed command, SQL playbook, or deployment-time bootstrap)?
• Should app-admin permissions launch as full-access first, or start with explicit scopes (e.g., billing.read, analytics.read) from day one?
• Will research capacity be marketed as runs, credits, or both?
• Which collaboration/team features are truly launch-ready?
• Should workspace limits be hard-enforced at launch or soft-gated initially?
• Which add-ons launch on day one vs later?
• Is founder/LTD part of launch or a separate campaign?
• What exact enterprise triggers require custom sales instead of self-serve?
• Which plan data belongs in the canonical catalog versus presentation metadata?

1) Product & Marketing Alignment

• Decide whether to update historical/internal naming artifacts separately:
  • CHANGELOG.md historical branding references
  • package.json package name

2) Canonical Plan Definitions

• Follow-up recommendation: clarify whether getPlanByCode should stay active-catalog-only or be renamed to make reserved-code behavior explicit.
• Follow-up recommendation: revisit whether planFamily should remain separate from tier or be consolidated later.
• Follow-up recommendation: consider moving shared plan price/period formatting helpers into the billing domain once account and pricing UI expand.
• Follow-up recommendation: extend readiness modeling beyond feature flags if later steps need readiness for support, processing, or add-on availability.

3) Packaging & Entitlement Model

• Future note: evaluateActionEntitlement() is policy-only and later steps must provide real remaining-usage inputs from subscription/account state.
• Future note: missing readiness metadata currently implies launch_ready; keep readiness annotations current as new gated features are added.
• Future note: api_requests and enrichments are modeled ahead of full product implementation; do not treat them as launch-ready by default.
• Future note: deep research costing should stay aligned with preview-derived estimates and should not diverge into a second billing algorithm.
• Future note: export policy is defined, but reliable export enforcement requires a future backend export endpoint.
• Future note: usage subject remains user until workspace-scoped ownership and pooled usage are ready.
• Future note: territoryMapping currently carries deep-research capability semantics and may need a dedicated capability later if gating becomes more granular.

4) Feature Gates by Plan

• Future note: make upgrade recommendations readiness-aware so users are not prompted to upgrade into tiers where the target feature is still coming_soon.
• Future note: consolidate action ↔ feature mapping into one canonical source shared by entitlements.ts and feature-gates.ts to avoid drift between UI gating and backend action policy.
• Future note: for Enterprise plans, included-but-not-ready features should usually resolve to coming_soon instead of contact_sales.
• Future note: revisit the fallback coming_soon state for unavailable or unmapped features before broad UI rollout so hidden vs upgrade vs future behavior stays intentional.

5) Billing & Data Model Design

• Future note: remaining = 0 for not_available resources is intentional and should stay aligned with entitlement semantics.
• Future note: expired billing periods should fail closed for current usage-window resolution until subscription lifecycle automation can advance billing periods reliably.
• Future note: consider exposing usagePeriodId later if enforcement, debugging, or admin tooling needs period-level traceability.
• Future note: add transactional workflows around billing-account updates, usage updates, and add-on purchase/balance mutations once real payment flows are introduced.
• Future note: plan_code is currently unconstrained text in the database; keep application-side validation strict unless a later migration adds stronger DB validation.
• Future note: usage ownership is workspace-scoped in storage, but current operational enforcement is still catching up to that model.

6) Enforcement Architecture

• Future note: the current enforcement slice should be treated as the core entitlement/runtime gate, not the full operational control layer.
• Future note: the default Starter bootstrap is a pre-payments usability policy and should be revisited when real subscription lifecycle automation is implemented.

7) Workspace, User, and Collaboration Readiness

• Future note: before true collaboration is sold as real runtime behavior, core domain entities need workspace_id ownership and repository/query updates.
• Future note: users included and workspace limits should remain soft-gated until multi-workspace UX and shared data ownership mature.
• Future note: shared lists, tagging/notes, and collaboration permissions should not be treated as hard-enforceable features until the workspace migration is complete.

8) Pricing Page & Account UX

• Future note: the pricing comparison table should stay aligned with workspace-readiness decisions as collaboration and shared asset features move toward workspace ownership.
• Future note: upgrade CTAs are present, but actual checkout/subscription management should remain tied to the post-payments hardening step.
• Future note: pricing and account UX should keep users included, workspace limits, and collaboration-adjacent promises explicitly soft-gated until workspace-owned shared data and hard enforcement are ready.
• Future note: replace placeholder upgrade CTAs in the account billing UI with a real upgrade path, pricing-page jump, contact-sales flow, or explicit coming soon behavior before broader rollout.

9) Add-On Strategy

• Future note: launch active add-ons should stay limited to one-time export packs until enrichment delivery and payments lifecycle handling are live.
• Future note: recurring feature add-ons should not be sold until the underlying capabilities and subscription management flows exist end-to-end.

10) Payments Integration

• Future note: Stripe is now the active integration path; keep the internal plan/add-on catalog as the canonical packaging source and treat Stripe price IDs as environment-specific mappings.
• Future note: the current customer-facing integration supports self-serve subscriptions, export-pack checkout, and the Stripe billing portal, while enterprise invoicing remains a manual sales workflow.
• Future note: webhook idempotency currently relies on the billing_webhook_events store; keep Stripe event processing centralized there as billing lifecycle coverage expands.
• Future note: post-payments hardening should tighten downgrade, cancellation, retry, and grace-period policy before broad rollout so Stripe portal actions and runtime entitlements stay aligned.

11) Post-Payments Hardening & Admin Visibility

• Application admin model: define app-wide admin as a separate identity domain from workspace memberships (owner/member).
• Implement DB-backed app-admin identities as the primary source of truth (active/disabled status, normalized email principal, optional scoped permissions, audit fields).
• Add migration path for current internal admin access: keep temporary env fallback only during rollout, then remove once DB-seeded admins are verified.
• Centralize admin authorization middleware (requireAdmin) and replace route-local billing-admin checks so /admin/* authorization semantics are consistent.
• Add admin audit visibility: log admin route access and key admin support actions with actor, route/action, target workspace, and timestamp.
• Define explicit downgrade behavior:
  • effective timing for scheduled vs immediate plan changes
  • entitlement/usage treatment when the target plan is below current usage
  • account messaging for pending downgrade state

12) Admin Dashboard / Console Incremental Plan

• Phase A (Read-only Admin Console foundation): Create dedicated admin page(s) separate from Account page and gate all access to app-admin users only.
• Phase A (Read-only Admin Console foundation): Add admin navigation entry/tab visible only to app-admin users.
• Phase A (Read-only Admin Console foundation): Move existing admin billing visibility tools (workspace search + workspace detail) from Account page to admin page.
• Phase A (Read-only Admin Console foundation): Add admin analytics summary panel on admin page powered by /admin/analytics/summary.
• Phase A (Read-only Admin Console foundation): Keep server-side requireAdmin as the source of truth (UI checks are convenience only).
• Phase B (Admin Access Management): Add admin-only APIs for listing, adding, disabling, and re-enabling application admins.
• Phase B (Admin Access Management): Add admin UI for managing app-admin identities with status visibility (active/disabled).
• Phase B (Admin Access Management): Prevent accidental lockout with guardrails (e.g., disallow disabling the last active admin).
• Phase B (Admin Access Management): Add explicit audit entries for admin identity mutations.
• Phase C execution split (implementation sequencing)
  • Sub-step 1 (Backend foundations): ship admin audit list API + security posture API + diagnostics aggregate API, plus shared types/client contracts.
  • Sub-step 2 (Admin Console UI): add audit explorer table/filters, security posture card, and diagnostics widgets with drill-down links.
  • Sub-step 3 (Hardening & operations): normalize audit action taxonomy, tune indexes/query performance, and finalize runbook/alerts for repeated failures.
• Phase C (Audit & Support Operations): Add admin audit log page/table with filters (actor, action, workspace, date window).
  • Add backend admin audit-list endpoint with filters for actor email, action, workspace ID, date range, and pagination.
  • Review audit-log query performance and indexes to ensure efficient filtering and default sorting by occurred_at DESC.
  • Implement admin audit table UI with filter controls plus clear loading, empty, and error states.
  • Normalize admin audit action taxonomy so admin-route events use consistent action names.
• Phase C (Audit & Support Operations): Expose bootstrap/security posture checks in admin UI (bootstrap enabled state, fallback allowlist usage warnings).
  • Add backend admin security-posture endpoint returning bootstrapRequired, bootstrapEnabled, and fallback allowlist usage status.
  • Add warning semantics when deprecated BILLING_ADMIN_EMAILS fallback is active.
  • Add admin UI security-posture card with explicit remediation guidance for risky states.
  • Document post-bootstrap hardening checklist: disable bootstrap, rotate bootstrap token, and verify at least two active admins.
• Phase C (Audit & Support Operations): Add support-oriented diagnostics widgets (recent webhook issues, billing sync errors, timeline anomalies).
  • Add backend diagnostics endpoint aggregating recent failed webhook events, stale billing-sync accounts, and recent timeline-anomaly counts.
  • Define timeline-anomaly heuristics (for example: repeated payment_failed, pending plan effective date in the past, and stale sync threshold breaches).
  • Add admin diagnostics widgets with counts and drill-down links to existing workspace detail views.
  • Define alerting and runbook follow-up tasks for repeated failures surfaced by diagnostics.
• Phase D (Safe Mutations, later): Keep initial admin console read-only for billing data; defer write/mutation actions until policies and runbooks are defined.
  • Pilot: add constrained billing resync admin mutation with non-destructive intent and explicit operator guidance.
• Phase D (Safe Mutations, later): For future write actions, require explicit confirmations, actor attribution, and rollback guidance.
  • Pilot guardrails in place: required reason, typed confirmation (RESYNC), optional ticketRef, and admin audit attribution.

13) [DEFER] Operational Enforcement Follow-Up

• Add queue prioritization by plan tier.
• Add throttling/fair-usage controls.
• Add export-route enforcement once CSV/export generation moves to a backend endpoint.
• Add enrichment-route enforcement once enrichment actions/routes are implemented.
• Future note: queue prioritization is deferred until async worker routing or higher-volume queued execution becomes an active runtime path.
• Future note: throttling/fair-usage controls are deferred until higher-volume execution patterns require operational protection.
• Future note: export enforcement remains deferred until CSV/export generation moves to a backend endpoint.
• Future note: enrichment-route enforcement remains deferred until enrichment actions/routes are implemented.

14) [DEFER] Founder / LTD Strategy

• Decide whether to launch founder LTD at all.
• If yes, define strict quantity cap (e.g. first 100-250 customers).
• Define founder SKUs:
  • Founder Plan = $249 one-time
  • Founder Pro = $499 one-time
• Ensure founder plans have monthly quotas and exclude unlimited compute/API.
• Define which future features are excluded from LTD plans.

15) Rollout Plan

• Phase 1: finalize canonical plan definitions, presentation metadata boundaries, and entitlement model.
• Phase 2: implement usage ledger and backend enforcement.
• Phase 3: review workspace, user, and collaboration readiness before expanding team/workspace promises.
• Phase 3a: execute workspace-role migration (owner/member only), convert legacy workspace admins to members by default, and validate owner-only management paths.
• Phase 3b: launch DB-backed app-admin identity management and migrate /admin/* authorization to centralized app-admin middleware.
• Phase 4: update pricing page and account/billing UI based on the workspace/collaboration readiness decisions.
• Phase 5: finalize add-on strategy before wiring payment products.
• Phase 6: integrate payments and subscription lifecycle handling.
• Phase 7: harden post-payments lifecycle handling, wire real billing CTAs, and add pragmatic admin billing visibility before broader commercialization work.
• Phase 7a: ship dedicated read-only admin console and migrate existing admin billing tools out of the account page.
• Phase 7b: ship app-admin identity management APIs/UI with last-admin lockout protection and audit logging.
• Phase 7c: ship admin audit explorer and support diagnostics views (Phase C from section 12).
• Phase 7d: evaluate controlled admin write-actions only after policy/runbook readiness.
• Phase 7e: MinIO/object-storage foundation + dataset registry schema.
• Phase 7f: postal ingestion worker pipeline + admin APIs.
• Phase 7g: admin console postal dataset operations and activation workflow.
• Phase 8: expand analytics, ops, and revenue instrumentation around the live billing and upgrade flows.
• Phase 9: launch collaboration, API, enrichment, and enterprise features as architecture matures.
• Phase 10: complete deferred operational enforcement work such as queue prioritization, throttling, and backend export enforcement when runtime scale justifies it.
• Phase 11: decide and implement founder/LTD strategy only after the app/site, billing lifecycle, admin/support visibility, analytics, and broader product maturity work are in place.

16) Multi-Country Postal Dataset Onboarding (MinIO-backed)

• Architecture decision
  • Standardize on self-hosted MinIO (S3-compatible) for postal dataset storage and processing.
  • Retire host-mounted files and manual CLI-only import as primary onboarding paths.
• Infrastructure/bootstrap
  • Add MinIO service to Docker deployment with persistent volume and health checks.
  • Define credential bootstrap/rotation expectations and automated bucket creation for postal datasets.
  • Document backup/restore expectations (RPO/RTO target, snapshot cadence, and restore verification).
• Config/env
  • Add and document S3_ENDPOINT, S3_REGION, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_FORCE_PATH_STYLE, and S3_BUCKET_POSTAL_DATASETS.
  • Wire S3-compatible config into both API and worker runtime boot paths.
• Data model
  • Add postal_datasets schema for object metadata, versioning, and activation status lifecycle.
  • Add postal_dataset_runs schema for run tracking, timing, actor/source metadata, and run types.
  • Add postal_country_support schema/state fields for per-country readiness, coverage, and active dataset linkage.
  • Define lifecycle states and transitions (draft, uploaded, validated, processing, ready, active, failed, archived) and enforce transition guards.
• API/admin flows
  • Add admin-authenticated dataset register + upload URL flow for object ingest.
  • Add validate/process/activate endpoints and dataset run history/read APIs.
  • Require admin authorization and audit logging for all mutating dataset actions.
• Worker pipeline
  • Implement queued jobs: postal.validate, postal.import, postal.neighbors, postal.check, postal.activate.
  • Enforce idempotency keys and per-country mutex/locking to prevent conflicting runs.
  • Track progress checkpoints and standard retry/backoff policy with terminal failure states.
• Country adapters
  • Implement pluggable country-specific validation/normalization profiles.
  • Enforce country geometry/topology constraints (bounds, shapes, adjacency expectations) during validation.
• Safety/operability
  • Keep activation behind an explicit admin gate after successful checks.
  • Preserve previous active dataset for rollback and support fast re-activation.
  • Add alerts and runbook steps for failed, stalled, or long-running jobs.
• UX/admin console
  • Add postal dataset list with status, country, version, and activation markers.
  • Add run logs/error visibility and filtered run history in admin console.
  • Add activation controls with confirmation guardrails and rollback visibility.
  • Add per-country readiness visibility so operators can see launch coverage at a glance.