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 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 Caddy reverse proxy.
• Rationale:
  • SEO-friendly (fully 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)

ADR-002 — Form backend: AWS SES via API Gateway + Lambda

• Status: Accepted (endpoint details to be confirmed at implementation)
• Context: The site must collect quote request form submissions (FR-3, FR-5). The site is static, so a backend service is required.
• Decision: Use AWS SES (Simple Email Service) to deliver form submissions to Diana's inbox. The static form will POST to an AWS API Gateway + Lambda endpoint (existing infrastructure) that calls SES to send the email.
• Rationale:
  • Reuses existing AWS infrastructure
  • SES is reliable, cost-effective, and avoids third-party form service dependencies
  • API Gateway + Lambda provides a clean, CORS-friendly endpoint for the static site
• Remaining items (to confirm before 38-lead-capture-spec.md implementation):
  • Endpoint URL for the API Gateway
  • Recipient email address configured in SES
  • Spam protection approach (e.g. honeypot field, reCAPTCHA, or AWS WAF — to specify in 38-lead-capture-spec.md)
• See also: OQ-3

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 throughout.
• Rationale:
  • Improves conversion on mobile
  • Supports SEO (Core Web Vitals)
• Consequences:
  • Images must be optimized (sized, compressed, lazy-loaded); avoid heavy JavaScript
  • Ensure accessible typography and touch-friendly tap targets

ADR-004 — Service pages: grouped by search intent for SEO

• Status: Accepted

• Context: Individual pages per service produce better SEO but only if pages have sufficient unique content. Some services (carpentry/mounting, flooring/wood refinishing) share search intent and image assets.

• Decision: Organize service pages into 9 grouped pages (down from 10+ individual items), grouped by search intent:

  Page	Slug	Services grouped
  Painting	/services/painting/	Interior & exterior painting, trim
  Tile Setting	/services/tile-setting/	All tile types, all rooms
  Drywall & Sheetrocking	/services/drywall/	Drywall, sheetrocking, patching
  Minor Plumbing	/services/plumbing/	Sinks, toilets, showers
  Minor Electrical	/services/electrical/	Lights, fans, fixtures
  Carpentry & Mounting	/services/carpentry-and-mounting/	Carpentry, mounting, assembly
  Flooring & Wood Refinishing	/services/flooring/	Flooring, decks, stairs, refinishing
  Security & Safety Equipment	/services/security-safety/	Grab bars, locks, cameras
  Boat Work	/services/boat-work/	Marine woodwork, paint, hardware

• Rationale:

  • Grouped pages have richer content and avoid thin-page SEO penalties
  • Carpentry + Mounting share the installation/assembly search intent
  • Flooring touch-ups + Wood Refinishing share the surface/finishing search intent and asset library

• Consequences:

  • Each grouped page must contain enough unique content to serve its target keywords
  • Internal linking from the Services hub must cover all sub-topics

ADR-006 — Static site generator: Eleventy (11ty)

• Status: Accepted
• Context: The site has 15+ pages sharing a common nav, footer, and layout. Plain HTML would require copy-pasting these into every file, creating a maintenance burden when nav items change.
• Decision: Use Eleventy 2.x (@11ty/eleventy) as the static site generator with Nunjucks as the template language.
• Rationale:
  • Produces pure static HTML files — no runtime dependency
  • Nunjucks layout chaining and includes eliminate nav/footer duplication
  • Simple data cascade for service pages (frontmatter-driven)
  • Well-documented, widely used for exactly this use case
  • npm run build outputs to _site/ which Caddy serves directly
• Alternatives considered:
  • Plain HTML: zero tooling but nav/footer must be duplicated in every file
  • Hugo: fast but Go-based; less familiar template syntax
  • Astro: more powerful but heavier; overkill for a content/lead-gen site
• Consequences:
  • Node.js + npm required in the build environment (not at runtime)
  • Output: _site/ directory of static HTML, CSS, JS, and assets
  • Caddy should serve from _site/

ADR-005 — No analytics or tracking in v1

• Status: Accepted
• Context: Stakeholder decided against tracking for simplicity.
• Decision: No analytics scripts, no ad pixels, no cookie consent banner in v1.
• Rationale: Reduces complexity, avoids consent/privacy obligations at launch.
• Consequences:
  • No data-driven iteration on traffic or conversions at launch
  • Adding analytics later will require revisiting privacy policy needs