Files
HiveGrid-Wireframes/hivegrid-cloud/docs/feature-decisions/portals-sites-decision-report.md
T

9.1 KiB

Portals/Sites Decision Report

Decision

Decision: extract-plugin

Portals/Sites are classified by D007 as an optional plugin candidate, not as Boilerplate Core and not as an immediate removal target. This report is the canonical Portals/Sites lifecycle source for Feature Decision/S03 and carries forward the D006 deferral that kept Portals/Sites persistence in module-owned DB files until the Feature Decision feature decision was made. The current code surfaces are retained as plugin-candidate inventory, while default core route registration disables the portal/site route trees. Later implementation work must preserve or explicitly remove the retained schema, Stripe billing, analytics, domains, sidebar, docs, environment, and verification boundaries atomically.

No runtime code is changed in this slice. This slice only records the decision report and prepares the later static verifier/execution plan so downstream agents do not blindly alter retained Portals/Sites surfaces or mistake disabled plugin routes for active core routes.

Scope

The scoped feature group covers customer portal and site-builder functionality across tenant routes, admin routes, module services, Prisma schema, billing provider behavior, analytics filters, domains configuration, sidebar command docs, environment examples, and feature inventory/manifests.

The canonical inventory and manifest references are docs/feature-inventory.md and docs/feature-manifests/plugin-candidates.json. They must continue to classify Portals/Sites as a plugin candidate and should reference this report once inventory alignment lands. The decision does not reclassify Portals/Sites as Core, and it does not instruct executors to remove or change runtime code during Feature Decision/S03.

Current Code Surfaces

Concrete Portals/Sites surfaces that later work must audit before any runtime change. Route paths listed here are retained plugin-candidate code surfaces, not active default core route registrations:

  • Modules: apps/web/app/modules/portals and apps/web/app/modules/sites.
  • Admin route: apps/web/app/routes/admin/portals.tsx.
  • Tenant portal routes: apps/web/app/routes/app.$tenant/__portals/*.
  • Tenant site routes: apps/web/app/routes/app.$tenant/sites/*.
  • Portal Stripe services: apps/web/app/modules/portals/services/PortalStripe.server.ts and apps/web/app/modules/portals/services/StripeConnect.server.ts.
  • Module-owned persistence: apps/web/app/modules/portals/db/portals.db.server.ts and apps/web/app/modules/sites/db/sites.db.server.ts.
  • Site configuration types: apps/web/app/modules/sites/site-types.ts.
  • Analytics coupling: apps/web/app/routes/admin/analytics/page-views.tsx and prisma/schema/analytics.prisma.
  • Domains coupling: apps/web/app/modules/domains/services/Domains.server.ts.
  • Sidebar coverage: apps/web/app/application/sidebar/AppSidebar.test.tsx.
  • Prisma schema surfaces: prisma/schema/portals.prisma and prisma/schema/sites.prisma.
  • Environment documentation: .env.example, .env.production.example, and .env.fly.example.
  • Documentation and manifest contracts: docs/feature-inventory.md and docs/feature-manifests/plugin-candidates.json.

Couplings

Portals/Sites are coupled to tenant navigation, admin management, analytics reporting, domain resolution, Stripe billing flows, Prisma schema, and environment configuration. The retained route code spans both hidden portal paths under apps/web/app/routes/app.$tenant/__portals/* and visible site-builder paths under apps/web/app/routes/app.$tenant/sites/*, while default core route discovery excludes those plugin trees. Extraction must preserve route ownership and user-visible navigation behavior if the plugin is enabled, or remove the retained surfaces atomically.

Analytics portal filters and site page-view behavior must be explicitly preserved, redesigned, or removed during later implementation. Domains behavior in apps/web/app/modules/domains/services/Domains.server.ts must also be treated as part of the feature boundary because public site routing and domain lookup can become broken if the module is moved without corresponding domain configuration.

Stripe Billing and Provider Boundary

Portals/Sites include Stripe-specific behavior through apps/web/app/modules/portals/services/PortalStripe.server.ts and apps/web/app/modules/portals/services/StripeConnect.server.ts. Later implementation must preserve or explicitly decide Stripe Connect behavior, customer billing portal behavior, provider initialization, webhook expectations, environment variables, and failure handling before moving or removing any portal billing route.

This report keeps Billing/Subscriptions Core separate from the Portals/Sites plugin candidate. Core Stripe subscription flows may remain in the boilerplate, while portal-specific Stripe Connect and customer portal behavior must be isolated behind a plugin/provider boundary if Portals/Sites are extracted.

Schema and Data Impact

D006 deferred Portals/Sites DB ownership and accepted temporary module-owned DB files at apps/web/app/modules/portals/db/portals.db.server.ts and apps/web/app/modules/sites/db/sites.db.server.ts. D007 resolves the lifecycle classification but does not move data access in this slice. Later implementation must preserve or decide the module-owned DB boundary before changing persistence.

The schema surfaces prisma/schema/portals.prisma, prisma/schema/sites.prisma, and prisma/schema/analytics.prisma must be audited together. Extraction or removal must include an explicit schema/data migration plan for portal records, site records, analytics relations, foreign keys, seeds or fixtures, and rollback behavior.

Sidebar Command Docs Impact

The app sidebar and its tests must stay aligned with the feature classification. apps/web/app/application/sidebar/AppSidebar.test.tsx should continue to prove that retained navigation does not expose removed plugin surfaces and that optional plugin entries are gated or documented consistently.

Docs and command/playbook surfaces must point executors to this report before runtime work. Inventory and manifest alignment must update docs/feature-inventory.md and docs/feature-manifests/plugin-candidates.json so future static checks can detect drift between human-readable documentation and machine-readable plugin classification.

Execution Plan

  1. Land this report and a static verifier for required sections, exact decision token, D007 reference, D006 deferral, path references, manifest alignment, unresolved placeholders, and no runtime-change instructions in this slice.
  2. Audit dependencies across routes, modules, Stripe services, analytics, domains, environment examples, sidebar tests, Prisma schema, and docs/manifests.
  3. Implement route/module extraction or removal only after the dependency audit proves a safe order for apps/web/app/modules/portals, apps/web/app/modules/sites, apps/web/app/routes/admin/portals.tsx, apps/web/app/routes/app.$tenant/__portals/*, and apps/web/app/routes/app.$tenant/sites/*.
  4. Create the schema/data migration plan for prisma/schema/portals.prisma, prisma/schema/sites.prisma, prisma/schema/analytics.prisma, and the module-owned DB files before moving persistence or deleting data models.
  5. Define the Stripe/env boundary for portal-specific Stripe Connect, customer billing portal behavior, dynamic site API keys, and .env.example, .env.production.example, .env.fly.example updates.
  6. Align analytics, domains, sidebar, docs, inventory, and plugin manifest references so retained Core behavior remains coherent after extraction.
  7. Add or update focused tests and static scans that protect route coverage, manifest classification, schema/data expectations, provider boundaries, and placeholder-free documentation without browser or E2E execution in this documentation slice.

Verification Plan

The Feature Decision/S03 verifier must fail with explicit diagnostics when required sections are missing, the exact decision token is absent, D007 or the D006 deferral is not cited, required path references drift, placeholders appear, manifest classification no longer matches extract-plugin, the inventory does not reference the canonical report, or the report suggests runtime code changes in this slice.

Task-level verification for this report is static: the file must be non-empty and must contain Decision: extract-plugin``. Slice-level verification later runs scripts/verify-portals-sites-decision-report.mjs without browser, Playwright, Cypress, or other E2E execution.

Risks

Missing any route, schema, provider, analytics, domains, environment, sidebar, inventory, or manifest surface would let a later implementation handle Portals/Sites incompletely. Reclassifying Portals/Sites as Core would conflict with D007, while immediate removal would conflict with the extract-plugin action and the D006 ownership deferral.

The highest implementation risk is partial extraction: moving routes without Stripe/customer portal decisions, deleting schema without data migration, or changing analytics/domains behavior without preserving public site expectations. Downstream work must therefore treat this report as the decision boundary and use static verification before runtime code changes.