Initial commit: specs and assets

specification/02-architecture-decisions.md

@@ -0,0 +1,54 @@
+# 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