TenantAtlas/specs/183-website-workspace-foundation/spec.md

Feature Specification: Website / Workspace Foundation

Feature Branch: 183-website-workspace-foundation Created: 2026-04-08 Status: Proposed Input: User description: "Introduce the first real multi-app foundation after the platform move to apps/platform by adding a public website app, minimal root orchestration, a clear command/workspace model, and strict separation between website, platform, and repo-wide meta-structures."

Spec Scope Fields (mandatory)

• Scope: workspace
• Primary Routes: Public website entry pages in the new website app; existing platform entry routes under /admin and /system remain unchanged; the root README and local development entry flow become the documented repo starting point.
• Data Ownership: No new tenant-owned or workspace-owned application records are introduced; this slice adds repo/workspace configuration artifacts and a new website app source tree only.
• RBAC: Public website pages are anonymous; existing platform and tenant membership/capability rules remain unchanged.

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: Yes. The repo root becomes the canonical multi-app workspace entry point for orchestration and discovery.
• New persisted entity/table/artifact?: Yes. The feature adds root workspace manifests/configuration and a new website app as versioned repository artifacts, but no new runtime business tables or persisted domain records.
• New abstraction?: Yes. The feature introduces an explicit root orchestration model for multiple apps.
• New enum/state/reason family?: No.
• New cross-domain UI framework/taxonomy?: No.
• Current operator problem: The product now needs a public website surface, but the repo still behaves like a single-app workspace. That makes website introduction ad hoc, hard to document, and easy to couple accidentally to the platform app.
• Existing structure is insufficient because: apps/platform is now correctly isolated, but there is no official root command model, no second app boundary, and no repo-level convention that tells contributors how multiple apps coexist or how to run them safely in parallel.
• Narrowest correct implementation: Add one real website app, one explicit workspace/orchestration model, and only the minimum root files and commands needed to run the platform, the website, or both.
• Ownership cost: The repo gains one more app to maintain, one more local run/build flow, root-level documentation upkeep, and a small amount of multi-app tooling review and smoke-test surface.
• Alternative intentionally rejected: Embedding the website into the platform app or introducing shared packages, docs, customer, or API surfaces immediately was rejected because those approaches either couple runtimes prematurely or add speculative structure without current-release value.
• Release truth: Current-release truth. The public website is the next concrete surface the product needs; this is not future-only preparation.

User Scenarios & Testing (mandatory)

User Story 1 - Start the Repo From One Clear Entry Model (Priority: P1)

A contributor needs to open the repository and immediately understand how to start the platform app, the website app, or both from one official documented entry path.

Why this priority: Without an official root entry model, every follow-up multi-app change becomes inconsistent, slows onboarding, and increases the risk of divergent local workflows.

Independent Test: A contributor can clone or open the repo, follow the root documentation, and use the official commands to start the platform, the website, or both without needing undocumented steps.

Acceptance Scenarios:

1. Given a contributor is at the repo root, When they follow the documented workspace entry flow, Then they can identify the official commands for platform-only, website-only, and parallel local development.
2. Given both apps exist in the repo, When a contributor starts them through the official model, Then each app boots through its own app-local execution path while the root only orchestrates.

---

User Story 2 - Work on the Website Independently (Priority: P2)

A contributor focused on the public website needs a real standalone website app that can run and build without requiring the platform runtime, shared sessions, or platform templating.

Why this priority: The website is the first new product surface after the platform extraction, so it must be able to evolve independently instead of being treated as a sidecar inside the platform app.

Independent Test: The website app can be started and built on its own, and the resulting public pages do not depend on the platform app being booted.

Acceptance Scenarios:

1. Given the platform app is not running, When a contributor starts the website app, Then the website is locally reachable and serves its public pages without requiring platform authentication or server-side platform rendering.
2. Given the website app is built, When the platform app remains untouched, Then the platform build/runtime outputs are unchanged and do not depend on website artifacts.

---

User Story 3 - Preserve Platform Stability During the Multi-App Transition (Priority: P3)

A platform contributor needs the new multi-app setup to leave apps/platform functionally stable while documenting how the platform fits into the broader repo layout.

Why this priority: The workspace foundation is only useful if it enables expansion without destabilizing TenantPilot itself.

Independent Test: Existing platform startup and smoke checks continue to work after the workspace changes, and contributors can still use app-local platform commands while understanding the new root entry model.

Acceptance Scenarios:

1. Given the repo has adopted the multi-app structure, When a contributor runs the documented platform workflow, Then the platform starts and behaves as before.
2. Given the platform and website are developed in parallel, When both are started locally, Then there are no obvious runtime or build collisions between them.

Edge Cases

• A contributor has not installed the official workspace/package manager: the root documentation must identify the supported standard clearly and avoid leaving parallel unsupported root workflows ambiguous.
• A default website port or platform-adjacent port is already in use: the official local-development guidance must make the conflict visible and describe the supported override path.
• A contributor builds the website while stale platform frontend assets already exist: the build outputs must remain app-local and must not overwrite or rely on platform artifacts.
• The platform app is temporarily unavailable: the website app must still start and build independently.
• The website app is unavailable or not being worked on: the platform app must continue to support its established app-local workflow.

Requirements (mandatory)

Constitution alignment (required): This feature introduces repo-level orchestration and a new public application surface, but it does not add Microsoft Graph calls, new tenant/workspace business persistence, OperationRun workflows, or authorization-plane changes. The key constitutional obligations are proportionality, explicit ownership of root-versus-app responsibilities, preservation of platform stability, and testable proof that the new multi-app structure remains intentionally narrow.

Scope

In scope

• A real apps/website application for the public website.
• A minimal root workspace and orchestration model for multiple apps.
• One official workspace/package-manager standard for root orchestration.
• One official root command model covering the platform, the website, and parallel local development.
• Clear separation of build and runtime responsibilities between the root, the platform app, and the website app.
• Documentation and tooling updates required to make the multi-app repo understandable and usable.
• Smoke validation for website boot, platform stability, parallel local development, and build separation.

Out of scope

• apps/docs
• packages/* shared packages
• Shared design-token, UI, or content packages
• Customer or auditor surfaces
• Public API or developer portal work
• CMS, blog, or content-engine expansion
• TenantPilot domain feature changes
• Large CI/CD re-architecture beyond the minimum documentation and tooling implications of this slice

Architectural Commitments

• The repository MUST use one official root workspace/package-manager standard for this slice, applied consistently across root orchestration and the website app.
• The public website MUST be introduced as a static-first standalone application under apps/website.
• Root orchestration MUST remain minimal: the root defines the workspace, documents the official commands, and coordinates multi-app entry paths, while app-specific execution logic stays inside each app.
• No shared package layer is introduced in this slice; small, local duplication between the platform and the website is acceptable until a real repeated need exists.

Functional Requirements

• FR-001: The repository MUST expose a first-class multi-app topology with apps/platform and apps/website as the only application surfaces introduced by this slice.
• FR-002: The root of the repository MUST provide the minimal workspace files required to make the official multi-app model explicit and usable.
• FR-003: The repository MUST define a single official root command model that covers starting the platform app, starting the website app, starting both apps for parallel local development, building the website app, and building the platform frontend when needed.
• FR-004: apps/website MUST be introduced as a real standalone app with its own source tree, public assets, local run flow, and build flow.
• FR-005: The website app MUST remain a public-surface runtime and MUST NOT depend on Blade, Filament, platform sessions, shared platform cookies, or embedding inside the platform app.
• FR-006: apps/platform MUST retain its existing app-local run and build workflows and MUST remain functionally stable under the new root model.
• FR-007: Root orchestration MUST describe and coordinate app workflows, but app-local execution logic MUST continue to live inside the respective app directories.
• FR-008: Website and platform local development MUST be able to run in parallel without shared build outputs, undocumented manual file shuffling, or cross-app runtime coupling.
• FR-009: Website and platform build outputs MUST remain isolated so that building or cleaning one app does not overwrite, invalidate, or implicitly require artifacts from the other app.
• FR-010: The root documentation MUST explain the repo structure, the purpose of apps/platform and apps/website, the official workspace standard, the official root commands, and the app-local command model.
• FR-011: Tooling, editor, and agent instructions that rely on root-level repo knowledge MUST be updated where needed so they reflect the multi-app structure and the official root entry path.
• FR-012: The website foundation introduced by this slice MUST remain intentionally narrow: public website pages and the supporting workspace foundation only, with no CMS or blog engine, docs surface, customer surface, API surface, or mandatory shared-package layer.
• FR-013: The feature MUST not introduce any new shared package, additional top-level application surface, or domain feature change unless separately specified in a later spec.
• FR-014: A smoke validation plan MUST verify platform stability, website boot, parallel local development, root orchestration usability, build separation, and documentation usability before the slice is considered complete.

Acceptance Criteria

• The repo has a clear multi-app structure with apps/platform and apps/website.
• A single official workspace/package-manager standard is defined and documented.
• The minimal root orchestration files and commands exist and are understandable from the repo root.
• The website app is independently runnable and buildable.
• The platform app remains stable and functionally unchanged by the workspace introduction.
• Platform and website can be developed locally in parallel.
• Root documentation explains the multi-app model and the official entry path clearly.
• No shared packages, docs surface, customer surface, or public API surface are introduced in this slice.
• Smoke validation demonstrates coexistence and build/runtime isolation.

Key Entities

• Root Workspace: The canonical repo-level contract that defines the official workspace standard, root orchestration files, and documented entry commands for the multi-app repo.
• Platform App: The existing TenantPilot Laravel application under apps/platform, which remains operationally separate and functionally stable.
• Website App: The new public-surface application under apps/website, intended for public product communication and independent local run/build workflows.
• Official Command Model: The documented set of root and app-local commands that tells contributors how to start, build, and work on the platform app, the website app, or both together.
• Build/Runtime Boundary: The separation rule that keeps dependencies, generated artifacts, ports, and runtime assumptions isolated between the platform and the website.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: A contributor can identify where the platform lives, where the website lives, and which official commands to use from the repo root within 10 minutes using only the updated root documentation.
• SC-002: Both apps can be started locally through the documented command model in the same development session with no unresolved port or runtime conflict beyond documented configuration overrides.
• SC-003: The website can be built successfully without requiring the platform app to be running, and the platform can complete its documented build workflow without requiring website artifacts.
• SC-004: Relevant existing platform startup and smoke checks continue to pass after the workspace foundation is introduced.
• SC-005: Repo review after this slice shows exactly one new first-class application surface (apps/website) and zero newly introduced shared packages or adjacent product surfaces.
• SC-006: A contributor can complete a platform-only workflow or a website-only workflow without starting the other app, except where the documentation explicitly states otherwise.

Assumptions

• The public website starts as a lightweight public information surface rather than an authenticated customer, docs, or partner portal.
• The platform application remains the canonical home for TenantPilot product logic; this slice only changes the repo and workspace foundation around it.
• Parallel local development uses separate app runtimes and separate default ports.
• Minor duplication between the platform and the website is acceptable until a real repeated need justifies a shared package.

Dependencies

• The platform extraction completed in Spec 182 remains intact and provides a stable apps/platform baseline.
• Repo-level documentation, tasks, and agent/tooling files can be updated to reflect the multi-app entry model.
• Local contributors can install the official workspace toolchain alongside the existing platform prerequisites.