96 lines
5.6 KiB
Markdown
96 lines
5.6 KiB
Markdown
# 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
|