Page Routing and SEO — SPEC

Start here → AGENTS.md · SPEC_INDEX.md · ARCHITECTURE.md.

Metadata

Evidence Rules

Behavioral claims cite current route/config/test files. Preserved migration specs supplied route intent and acceptance cases, but do not override the Astro file tree.

Source Material Register

Overview

Astro file-based routing under src/pages/ owns public pages, same-origin APIs, operational endpoints, authentication callbacks, media proxies, robots policy, and sitemap output. Shared layouts apply metadata and page chrome; src/lib/seo.ts centralizes title, description, canonical URL, and social-image construction.

Purpose / Responsibility

Owns URL-to-handler mapping and indexable metadata for the current Astro application; it does not own external data normalization or browser interaction state.

Stack

Astro 6 SSR routes, TypeScript endpoint handlers, Astro layouts, Vitest route/SEO tests, Playwright higher-tier checks.

Folder / Package Structure

src/pages/
├── *.astro                 # public SSR pages
├── applications/[appId]   # dynamic app detail
├── category/[category]     # category listing
├── api/                    # same-origin JSON/action routes
├── auth/                   # App Hub OAuth
├── integration/            # native integration OAuth
└── sitemap*.ts, robots.txt.ts, ping.ts, getImage.ts

Key Files (source of truth)

Public Surface

Compatibility notes:

• File paths define URLs; removal/rename requires redirect and contract updates.
• Dynamic app/category URLs must remain canonical and sitemap-safe.

Requires (dependencies)

Synchronized catalog/category data, Redis, page layouts/components, SEO helpers, middleware redirects/security, and configured site host.

Requirements

Design Overview

Routes are declarative files. Pages obtain server data before rendering and pass serializable initial state to islands. Static sitemap discovery is configured in Astro; the custom sitemap merges static pages with synchronized app/category URLs, normalizes/escapes them, caches the result, and serves compressed bytes when supported.

Data Flow

flowchart LR
  Request --> Middleware --> Route["Astro route"]
  Route --> Data["sync/SEO helpers"]
  Data --> Render["layout + components"]
  Render --> Response
  Data --> Sitemap["XML generation/cache"]

Sequence Diagram(s)

sequenceDiagram
  participant B as Browser
  participant M as Middleware
  participant P as Astro page
  participant R as Redis/sync helpers
  B->>M: GET page
  M->>P: next()
  P->>R: read normalized data
  alt route entity exists
    R-->>P: data
    P-->>B: SSR HTML + metadata
  else missing/invalid
    R-->>P: null
    P-->>B: 404/empty contract
  end

sequenceDiagram
  participant C as Crawler
  participant S as Sitemap route
  participant R as Redis/sync readers
  C->>S: GET /sitemap.xml
  S->>S: check process cache
  alt cache miss
    S->>R: read apps and categories
    R-->>S: current snapshot or unavailable subset
    S->>S: merge static/dynamic, normalize, escape, compress
  end
  S-->>C: XML or gzip XML

Class / Component Relationships

classDiagram
  class AstroRoute
  class Layout
  class SeoHelpers
  class SyncReaders
  AstroRoute --> Layout
  AstroRoute --> SeoHelpers
  AstroRoute --> SyncReaders

Use Cases

• UC-1 Browse listing: visitor navigates to a static listing route → server fetches synchronized apps → listing layout renders. Evidence: src/pages/asp-apps.astro, src/lib/fetch-synced-data.ts.
• UC-2 Open app: visitor uses /applications/:appId → identifier lookup → detail or not-found response. Evidence: src/pages/applications/[appId].astro.
• UC-3 Crawl: crawler requests robots/sitemap → environment policy and current public URLs are returned. Evidence: src/pages/robots.txt.ts, src/pages/sitemap.xml.ts.

Business Rules & Invariants

• API/auth/error/search/private pages are not indexable; enforced in astro.config.mjs and robots/sitemap code.
• Canonical URLs use the configured origin; do not trust arbitrary request/query origins.
• Route removal requires a redirect or approved incompatibility.

Concurrency & Reactive Flow

• Sitemap generation may reuse process-local cached XML/compressed bytes; generation must remain deterministic.
• SSR reads do not mutate browser stores; hydration occurs after server output.

UI Flow

• Listing routes render loading-free SSR content when synchronized data is present.
• Empty/missing states remain route-specific; dynamic missing applications resolve to the current not-found behavior.
• Search is a separate page/API flow and is excluded from sitemap indexing.

Error Handling & Failure Modes

Pitfalls

• Static Astro sitemap integration does not automatically include dynamic application/category records.
• Current URLs come from src/pages/, not the legacy API inventory.
• site is derived from configured host in astro.config.mjs; wrong environment host produces wrong canonicals.

Module Do’s / Don’ts

• DO add redirects and metrics labels with route changes.
• DO validate dynamic identifiers before lookup.
• DON’T expose API/auth routes in sitemap output.
• DON’T add a route only to documentation.

Key Design Trade-off

File-based routing keeps route ownership visible and build-checked, while custom sitemap generation accepts extra runtime complexity to include Redis-backed dynamic catalog URLs.

Test-Case Strategy (module)

Unit-test SEO normalization, redirects, robots, sitemap escaping/deduplication/compression, and route helpers. Use build and visual/E2E suites for representative SSR routes and navigation.

Traceability

• Architecture: ARCHITECTURE.md
• Contracts: CONTRACTS.md
• Coverage/contracts baseline: .sdd/manifest.json