80 lines
9.1 KiB
Markdown
80 lines
9.1 KiB
Markdown
# 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.
|