diana/specification/02-architecture-decisions.md

Architecture Decisions (ADRs) — Diana Website (v1)

This file records stable architectural decisions and their rationale. Items here should remain valid even as implementation details evolve.

ADR-001 — Static website (SSG or plain static HTML) as the delivery model

• Status: Accepted
• Context: Site is primarily informational/lead-capture, needs strong SEO, and is expected to change infrequently.
• Decision: Build as a static website (pre-rendered HTML) suitable for hosting behind a reverse proxy.
• Rationale:
  • SEO-friendly (indexable content)
  • Fast and reliable on mobile
  • Low maintenance
• Alternatives considered:
  • WordPress/CMS: easier editing but higher maintenance/security surface
  • SPA-only: SEO/performance risks and complexity
• Consequences:
  • Contact form delivery must be handled via a static-compatible approach (see ADR-002, TBD)

ADR-002 — Quote request form submission mechanism

• Status: Proposed (blocked)
• Context: Form is required (FR-1..FR-4), but the mechanism (email service, server endpoint, third-party form backend) is not yet selected.
• Decision: TBD.
• Options to evaluate (non-exhaustive):
  1. Static form backend service (e.g., Netlify Forms / Formspree / Basin)
  2. Self-hosted lightweight endpoint behind Caddy (out-of-scope per C-2 unless already existing)
  3. Email link fallback (mailto) — likely insufficient for qualified leads
• Drivers:
  • Qualified lead capture
  • Spam protection
  • GDPR/cookie implications
  • Operational simplicity
• Next step: Resolve in 99-open-questions.md and specify in 38-lead-capture-spec.md.

ADR-003 — Mobile-first, performance-first design

• Status: Accepted
• Context: Most traffic is expected on mobile; SEO and conversion depend on usability and speed.
• Decision: Adopt a mobile-first layout and performance budget mindset.
• Rationale:
  • Improves conversion
  • Supports SEO (Core Web Vitals)
• Consequences:
  • Images must be optimized; avoid heavy JS
  • Ensure accessible typography and tap targets

ADR-004 — SEO information architecture: one page per service

• Status: Accepted
• Context: SEO is important and services are distinct.
• Decision: Create separate service pages for each service category listed in FR-8.
• Rationale:
  • Supports service-intent keywords
  • Improves internal linking and topical relevance
• Consequences:
  • Requires unique content per page (avoid duplicate/thin pages)
  • Requires a services hub and internal navigation