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, billing provider, 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/portalsandapps/web/app/modules/sites. - Admin route: removed from the default HiveGrid admin surface; tenant portal routes remain inventoried as plugin-candidate code.
- Tenant portal routes:
apps/web/app/routes/app.$tenant/__portals/*. - Tenant site routes:
apps/web/app/routes/app.$tenant/sites/*. - Portal billing provider services:
apps/web/app/modules/portals/services/PortalPayment provider.server.tsandapps/web/app/modules/portals/services/Payment providerConnect.server.ts. - Module-owned persistence:
apps/web/app/modules/portals/db/portals.db.server.tsandapps/web/app/modules/sites/db/sites.db.server.ts. - Site configuration types:
apps/web/app/modules/sites/site-types.ts. - Analytics coupling:
prisma/schema/analytics.prismapowers portal analytics; the old admin analytics route was removed from the core admin surface. - 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.prismaandprisma/schema/sites.prisma. - Environment documentation:
.env.exampleand.env.production.example. - Documentation and manifest contracts:
docs/feature-inventory.mdanddocs/feature-manifests/plugin-candidates.json.
Couplings
Portals/Sites are coupled to tenant navigation, admin management, analytics reporting, domain resolution, billing provider 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.
Billing Provider Boundary
Portals/Sites include billing-provider behavior through the portal pricing and subscription persistence boundary. Later implementation must preserve or explicitly decide provider checkout 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 subscription flows remain in HiveGrid, while portal-specific payment-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
- 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.
- Audit dependencies across routes, modules, billing provider services, analytics, domains, environment examples, sidebar tests, Prisma schema, and docs/manifests.
- 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/app.$tenant/__portals/*, andapps/web/app/routes/app.$tenant/sites/*. - 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. - Define the billing/env boundary for portal-specific Payment provider Connect, customer billing portal behavior, dynamic site API keys, and
.env.example,.env.production.exampleupdates. - Align analytics, domains, sidebar, docs, inventory, and plugin manifest references so retained Core behavior remains coherent after extraction.
- 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 billing provider/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.