203 lines
21 KiB
Markdown
203 lines
21 KiB
Markdown
# Feature Specification: Website Information Architecture / Core Pages
|
|
|
|
**Feature Branch**: `215-website-core-pages`
|
|
**Created**: 2026-04-19
|
|
**Status**: Draft
|
|
**Input**: User description: "Define the initial information architecture and core public pages for `apps/website`, including required pages, page roles, navigation, route model, optional surfaces, trust/legal/update rules, and explicit exclusion of `apps/platform` and page-level design."
|
|
|
|
## Spec Candidate Check *(mandatory - SPEC-GATE-001)*
|
|
|
|
- **Problem**: `apps/website` currently risks inheriting its page inventory from theme defaults or ad hoc page requests instead of from a deliberate buyer journey and product-truth model.
|
|
- **Today's failure**: Early website work can produce too many thin pages, unclear navigation, buried trust signals, and premature prominence for pricing, docs, or content hubs before product understanding is solid.
|
|
- **User-visible improvement**: Visitors can understand what the product is, why it matters, why it is credible, and what to do next without navigating a bloated or immature sitemap.
|
|
- **Smallest enterprise-capable version**: Define a website-local information architecture with required public pages, clear page jobs, a small navigation model, route priorities, and explicit rules for optional and later surfaces.
|
|
- **Explicit non-goals**: Visual page design, hero or section composition, final copy, SEO strategy, CMS decisions, detailed docs IA, Filament or platform theming, platform IA, auth or app routing, pricing-model decisions, and full content drafting.
|
|
- **Permanent complexity imported**: A website-local IA vocabulary for core surfaces, optional surfaces, deferred surfaces, primary navigation, footer navigation, outcome explanation, trust claims, and discoverability rules.
|
|
- **Why now**: The website is early enough that route and navigation decisions can still be shaped before empty prestige pages and template-driven structure become expensive defaults.
|
|
- **Why not local**: Solving IA one page at a time cannot prevent cross-site navigation drift, cannot prioritize trust and buyer understanding consistently, and cannot stop placeholder routes from becoming normalized.
|
|
- **Approval class**: Core Enterprise
|
|
- **Red flags triggered**: New website-local taxonomy for public surfaces; risk of drifting into design-detail work; risk of accidental bleed into `apps/platform` expectations.
|
|
- **Score**: Nutzen: 3 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 1 | Wiederverwendung: 2 | **Gesamt: 11/12**
|
|
- **Decision**: approve
|
|
|
|
## Spec Scope Fields *(mandatory)*
|
|
|
|
- **Scope**: workspace
|
|
- **Primary Routes**: Required core routes are `/`, `/product`, `/trust`, `/changelog`, the primary conversion route `/contact`, `/privacy`, and `/imprint`; the optional initial content surface for this feature is `/resources`; retained secondary supporting routes may include `/legal`, `/terms`, `/solutions`, and `/integrations` without core prominence; deferred route families include later `/pricing`, `/docs`, and any expanded dedicated solutions-hub structure.
|
|
- **Data Ownership**: Website-owned public IA contract only: page taxonomy, route priorities, navigation model, and public-surface rules. No tenant-owned records, platform data, or shared persistence are introduced.
|
|
- **RBAC**: None. This feature applies to public website surfaces and introduces no authorization model.
|
|
|
|
## Proportionality Review *(mandatory when structural complexity is introduced)*
|
|
|
|
- **New source of truth?**: yes
|
|
- **New persisted entity/table/artifact?**: no
|
|
- **New abstraction?**: yes
|
|
- **New enum/state/reason family?**: no
|
|
- **New cross-domain UI framework/taxonomy?**: yes, but only within `apps/website`
|
|
- **Current operator problem**: Website contributors and reviewers do not yet have a shared rule set for which public pages deserve prominence, which routes are mandatory, and how product, trust, and next-step surfaces should relate to each other.
|
|
- **Existing structure is insufficient because**: Theme-provided pages and page-local decisions optimize local convenience but do not guarantee a coherent buyer journey, do not prevent empty prestige pages, and do not protect website work from drifting into platform concerns.
|
|
- **Narrowest correct implementation**: A website-only IA specification that defines required pages, optional pages, deferred pages, route priorities, and public-surface rules without prescribing page design or implementation details.
|
|
- **Ownership cost**: Future website work must align with this IA before adding routes, promoting new top-level links, or surfacing public claims that require supporting trust context.
|
|
- **Alternative intentionally rejected**: Allowing page inventory to emerge from theme defaults or from page-by-page requests was rejected because it would prioritize breadth over clarity and create avoidable credibility problems.
|
|
- **Release truth**: Current-release truth for `apps/website`; this spec must not be interpreted as a shared website-platform contract.
|
|
|
|
## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)*
|
|
|
|
- **Test purpose / classification**: Browser
|
|
- **Validation lane(s)**: fast-feedback
|
|
- **Why this classification and these lanes are sufficient**: This spec governs public route composition, navigation behavior, and discoverability on a static website surface. Build proof plus browser smoke coverage of representative public routes is the narrowest honest proof; no database, auth, tenant, or platform runtime setup is required.
|
|
- **New or expanded test families**: Focused website smoke coverage for required core routes, global navigation, footer navigation, primary CTA reachability, and optional-surface suppression when content is absent.
|
|
- **Fixture / helper cost impact**: low; browser smoke helpers may expand slightly, but no backend fixtures, seeds, memberships, providers, or session setup are needed.
|
|
- **Heavy-family visibility / justification**: none; validation stays in fast-feedback only.
|
|
- **Special surface test profile**: N/A
|
|
- **Standard-native relief or required special coverage**: Route-level smoke coverage is sufficient; no platform or operator-surface coverage is required.
|
|
- **Reviewer handoff**: Reviewers should confirm that required routes exist, trust remains top-level visible, one primary conversion path is obvious, optional content hubs are not promoted when empty, and no route or navigation obligation leaks into `apps/platform`.
|
|
- **Budget / baseline / trend impact**: none beyond small website smoke-suite growth.
|
|
- **Escalation needed**: document-in-feature
|
|
- **Active feature PR close-out entry**: Smoke Coverage
|
|
- **Planned validation commands**: `corepack pnpm build:website` and `cd apps/website && corepack pnpm exec playwright test`
|
|
|
|
## User Scenarios & Testing *(mandatory)*
|
|
|
|
### User Story 1 - Understand the product and next step quickly (Priority: P1)
|
|
|
|
A first-time evaluator can land on the website, understand what TenantPilot / TenantAtlas is, find the most relevant deeper pages, and identify a clear next step without being forced through pricing, docs, or thin placeholder pages.
|
|
|
|
**Why this priority**: Product understanding and next-step clarity are the primary purpose of the public website and the strongest reason to keep the IA small.
|
|
|
|
**Independent Test**: Review the homepage and global navigation and confirm that a first-time visitor can identify the product surface, trust surface, changelog surface, and primary conversion surface without needing any deferred routes.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a first-time visitor lands on `/`, **When** they review the homepage and primary navigation, **Then** they can identify what the product is, where to validate trust, and how to take the next step.
|
|
2. **Given** a visitor enters directly on `/product`, **When** they want more confidence or a sales path, **Then** they can reach `/trust` and the primary contact surface without navigating through unrelated pages.
|
|
|
|
---
|
|
|
|
### User Story 2 - Validate trust and technical seriousness (Priority: P1)
|
|
|
|
A technical decision maker or security stakeholder can find a dedicated trust surface that supports public claims about security, isolation, hosting, and operating discipline without relying on vague marketing copy.
|
|
|
|
**Why this priority**: Trust is a first-class purchase filter for this product category and must be structurally visible, not buried as footer-only material.
|
|
|
|
**Independent Test**: Review `/trust` and confirm that public trust, hosting, or residency claims have one explicit supporting surface and are not scattered or implied without context.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a visitor sees a public claim about hosting region, isolation, or operational discipline, **When** they open `/trust`, **Then** they find that claim explained, bounded, or explicitly limited on that page.
|
|
2. **Given** the homepage keeps trust content intentionally concise, **When** a technical evaluator needs deeper reassurance, **Then** the IA routes them to `/trust` rather than forcing them to infer trust from unrelated marketing sections.
|
|
|
|
---
|
|
|
|
### User Story 3 - See visible product progress (Priority: P2)
|
|
|
|
A returning visitor or existing follower can verify that the product is evolving by using a dedicated changelog surface instead of hunting across product pages or editorial content.
|
|
|
|
**Why this priority**: Visible product motion helps credibility, but it comes after basic product and trust understanding.
|
|
|
|
**Independent Test**: Review the core IA and confirm that a returning visitor has a direct route to dated product updates without depending on a blog or resource hub.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a returning visitor wants to know what changed recently, **When** they open `/changelog`, **Then** they see dated, concrete progress signals in one dedicated surface.
|
|
2. **Given** optional resources or later editorial content is not yet substantive, **When** the visitor uses primary navigation, **Then** the IA does not elevate an empty content hub in place of the changelog.
|
|
|
|
### Edge Cases
|
|
|
|
- Optional `/resources` content is not ready yet, and the later editorial `articles` collection is still unpublished, so the website must remain coherent without promoting either surface in primary navigation.
|
|
- A public hosting or data-residency claim exists, but no supporting trust explanation is available yet; the claim must be removed or the trust surface must support it before publication.
|
|
- A separate `/solutions` hub is not launched initially, so homepage and product surfaces must still carry buyer-oriented outcome explanation.
|
|
- A future `/demo` route may exist eventually, but `/contact` remains the clear primary next-step path in the initial IA.
|
|
- Docs or pricing material may exist in partial form, but they must not be promoted as primary navigation until they are mature enough to support honest public expectations.
|
|
|
|
## Requirements *(mandatory)*
|
|
|
|
**Constitution alignment (required):** This feature introduces no Microsoft Graph calls, no queueing, no long-running operations, no authorization changes, and no Filament operator surfaces. Its contract is explicitly local to `apps/website` and must not create obligations for `apps/platform`.
|
|
|
|
**Constitution alignment (UI-SEM-001 / LAYER-001 / BLOAT-001):** This feature intentionally introduces a website-local IA and surface-priority layer because ad hoc route growth and theme-driven page inventories are insufficient to produce a coherent enterprise website. The layer is scoped narrowly to public website surfaces and must not expand into platform IA or a shared website-platform taxonomy without a separate spec.
|
|
|
|
**Implementation boundary:** Any implementation under this specification MUST preserve the existing website working contract by keeping `@tenantatlas/website`, `WEBSITE_PORT`, and the root `dev:website` / `build:website` workflows intact, and it MUST NOT introduce runtime or package coupling to `apps/platform`.
|
|
|
|
### Functional Requirements
|
|
|
|
- **FR-001**: The specification MUST define an initial public information architecture for `apps/website` that is explicitly local to the website and explicitly excludes `apps/platform`, platform IA, Filament theming, and app-auth routing decisions.
|
|
- **FR-002**: The initial required core surfaces MUST be Home, Product, Trust, the primary conversion surface `/contact`, Privacy, and Imprint.
|
|
- **FR-003**: The initial IA MUST classify Changelog as a strongly recommended public surface with a named role in the website journey.
|
|
- **FR-004**: The IA MAY classify `Resources` as an optional initial surface, but only when substantive content exists and the route is not a placeholder; any later blog/editorial surface MUST remain unpublished until a separate spec activates it.
|
|
- **FR-005**: Pricing, Customers or Case Studies, Careers, Compare or Alternatives, Status, a full Docs portal, and a dedicated Solutions hub MUST be treated as deferred surfaces rather than initial core requirements.
|
|
- **FR-006**: The homepage at `/` MUST act as a routing, positioning, and trust hub that explains the product at a high level and opens clear paths to Product, Trust, Changelog, and the primary conversion surface.
|
|
- **FR-007**: The homepage MUST include buyer-oriented outcome or use-case explanation and MUST NOT rely on feature taxonomy alone to explain why the product matters.
|
|
- **FR-008**: The product surface at `/product` MUST explain what TenantPilot / TenantAtlas is, what it is not, how its capability areas are grouped, and how those capabilities relate to buyer outcomes.
|
|
- **FR-009**: The product surface MUST cover, at an appropriate public level, Backup, Restore, Versioning, Audit, Inventory or Drift Detection, and Governance topics such as Baselines, Findings, Exceptions, Evidence, and Reviews.
|
|
- **FR-010**: The trust surface at `/trust` MUST exist as a first-class public page and MUST cover security and operating principles, a public-safe architecture overview, tenant isolation, credential or access handling, protection measures, update and operating discipline, and a path for deeper trust or security questions.
|
|
- **FR-011**: Any public claim about hosting region, data residency, tenant isolation, or security posture MUST be supported, bounded, or contextualized on `/trust`, and the website MUST NOT make absolute legal-compliance claims that it cannot responsibly qualify.
|
|
- **FR-012**: The changelog surface at `/changelog` MUST show dated, concrete product progress and MUST NOT be treated as a replacement for the product page or for long-form editorial content.
|
|
- **FR-013**: The website MUST expose `/contact` as the clear, low-friction primary conversion surface, and if a demo option exists later, it MUST remain secondary unless a future spec changes the primary conversion route.
|
|
- **FR-014**: The initial top-level navigation MUST remain intentionally small and SHOULD default to Product, Trust, Changelog, optional `Resources` only when substantive, and Contact, plus one primary CTA.
|
|
- **FR-015**: The brand or logo MUST route visitors to `/`.
|
|
- **FR-016**: No top-level navigation item or other prominent public link MAY point to a placeholder, thin-content, or template-only page.
|
|
- **FR-017**: Trust MUST remain visible in top-level navigation and MUST NOT be relegated to footer-only discoverability.
|
|
- **FR-018**: The footer MUST group product, trust or legal, contact, and optional content or docs links in a consistent public navigation model.
|
|
- **FR-019**: The initial URL model MUST use short, clear public paths and MUST avoid unnecessary early nesting, artificial segmentation, or mixing marketing routes with app routes.
|
|
- **FR-020**: The website MUST provide a buyer-oriented outcome or use-case explanation layer on the homepage, on the product page, or on both, even if a dedicated `/solutions` hub is not launched initially.
|
|
- **FR-021**: Docs MAY become discoverable once a minimal, credible documentation surface exists, but the IA MUST NOT force Docs into primary navigation before that threshold is met.
|
|
- **FR-022**: Pricing MAY be introduced later, but the IA MUST NOT force Pricing into primary navigation until packaging, expectations, and public framing are mature enough to be honest and coherent.
|
|
- **FR-023**: The page relationship model MUST support an entry route, a first-clarification phase, a deeper-exploration phase, and a clear action phase ending in Contact.
|
|
- **FR-024**: Public website language and page prioritization MUST favor product truth, trust, outcome understanding, and clear next steps over hype, fake maturity signals, or inflated enterprise theater.
|
|
- **FR-025**: The specification MUST define its deliverables explicitly: required core page list, role of each page, top-level navigation, footer navigation, route model, optional-surface rules, deferred-surface list, outcome-explanation rule, trust-claim rule, and docs-discoverability rule.
|
|
- **FR-026**: No requirement in this specification MAY be interpreted as a commitment to platform routing, platform design, or shared website-platform IA work.
|
|
- **FR-027**: Implementation work under this specification MUST preserve the website working contract by retaining `@tenantatlas/website`, `WEBSITE_PORT`, and the root `dev:website` / `build:website` workflows, and it MUST NOT introduce runtime coupling or shared-package obligations for `apps/platform`.
|
|
|
|
#### Out of Scope
|
|
|
|
- Visual design of individual pages
|
|
- Hero or section composition
|
|
- Final production copy
|
|
- SEO keyword planning
|
|
- CMS selection
|
|
- Detailed documentation IA
|
|
- Filament or `apps/platform` theming
|
|
- Platform IA
|
|
- Auth or app-routing behavior
|
|
- Pricing-model decisions
|
|
- Full content drafting for each page
|
|
|
|
#### Assumptions
|
|
|
|
- `apps/website` must work for enterprise buyers, MSPs, technical decision makers, security or governance stakeholders, and returning followers without creating separate website tracks for each audience in the initial IA.
|
|
- Outcome and use-case explanation can live inside Home and Product initially without requiring a dedicated Solutions hub.
|
|
- Legal basics must be present from the start, while Docs and Pricing can remain deferred until their public substance is strong enough.
|
|
- The initial website should favor a small number of durable public routes over a broad marketing sitemap.
|
|
- For Spec 215 execution, the optional content surface standardizes on `/resources`; the existing editorial `articles` collection remains unpublished until a later blog/editorial spec activates it.
|
|
- Existing `/legal`, `/terms`, `/solutions`, and `/integrations` pages may remain published as secondary supporting surfaces, but they MUST NOT displace the required core IA in top-level navigation or buyer flow.
|
|
|
|
### Key Entities *(include if feature involves data)*
|
|
|
|
- **Core Surface**: A required initial public page that carries one named job in the buyer journey and is part of the minimal credible website.
|
|
- **Optional Initial Surface**: A page family such as `Resources` that is allowed in the initial IA only if substantive content exists at launch.
|
|
- **Deferred Surface**: A public page family intentionally excluded from the initial core website until its content, claims, or business model are mature enough.
|
|
- **Trust Surface**: The dedicated public page that supports technical seriousness, trust claims, and bounded public statements about hosting, residency, isolation, and operating discipline.
|
|
- **Outcome Explanation Layer**: The buyer-oriented explanation of operational or business problems solved by the product, expressed without depending on a dedicated Solutions hub.
|
|
- **Primary Conversion Surface**: The main next-step path, Contact in the initial IA, that converts public understanding into a clear action.
|
|
|
|
## Success Criteria *(mandatory)*
|
|
|
|
### Measurable Outcomes
|
|
|
|
- **SC-001**: The IA defines 100% of required initial core routes: `/`, `/product`, `/trust`, `/changelog`, the primary conversion route `/contact`, `/privacy`, and `/imprint`.
|
|
- **SC-002**: 100% of top-level navigation items in the initial IA map to named core or approved optional surfaces with explicit roles, and 0 prominent links point to placeholder or thin-content pages.
|
|
- **SC-003**: From each core entry route (`/`, `/product`, `/trust`, and `/changelog`), a visitor can reach the primary conversion surface in no more than 2 clicks.
|
|
- **SC-004**: 100% of public hosting, residency, isolation, or security claims in the initial IA have a designated supporting or bounding surface on `/trust`, or the claim is excluded from the public website.
|
|
- **SC-005**: Reviewers can map the four core buyer questions - what is it, who is it for, why trust it, and what next - to explicit public surfaces without requiring an initial Pricing page, Docs portal, or dedicated Solutions hub.
|
|
- **SC-006**: The initial informational top-level navigation exposes no more than 5 public route entries plus one primary CTA, preserving a deliberately small public IA.
|
|
|
|
## Planned Follow-on Specs
|
|
|
|
- Spec 216 - Homepage Structure and Section Model
|
|
- Spec 217 - Product Page Structure
|
|
- Spec 218 - Trust Surface
|
|
- Spec 219 - Contact / Demo Flow
|
|
- Spec 220 - Changelog Surface
|
|
- Spec 221 - Blog / Resources Surface, if activated
|
|
- Spec 222 - Solutions / Use-Case Surfaces, if activated later
|
|
- Spec 223 - Pricing Surface, if activated later |