Ezzi Clarity Portal

ADR-1001 — Website Architecture

Field Value
Document ID ADR-1001
Title Website Architecture
Status Accepted (retrospective)
Classification Internal
Owner Ezzi Clarity Educational Consulting Services Inc.
Subject ezziclarity.ca — source: github.com/vijaybpanangi/ezziclarity
Decision Date Architecture predates this ADR; documented retrospectively 2026-08-04

Note

This ADR is retrospective. The architecture it documents was already implemented (through 18 shipped releases, v1.0.0–v3.7.0) before this document existed. Its purpose is to preserve the reasoning behind decisions already made, not to propose a new architecture. Where the original decision rationale wasn’t explicitly recorded at the time, this ADR infers it from available evidence and marks it as inferred rather than confirmed.

Contents

1. Context

Ezzi Clarity Educational Consulting Services Inc. needed a public marketing website for its educational consulting practice, serving English, French, and Arabic-speaking audiences in the Waterloo Region, Ontario. The corporation is small, pre-revenue-scale, and maintained primarily by one person (with AI pair-programming assistance) rather than a dedicated engineering team. The codebase originated as a WordPress theme and was later converted to a plain static site; full rationale for that specific migration was not found in available records.

2. Decision

The website is built and operated as follows:

  1. Static HTML/CSS/JS, no framework, no build system. Each page is a hand-authored HTML file. One global stylesheet (style.css) provides all styling via CSS custom properties.
  2. Triplicate-maintenance localization. Each of the six pages exists as three separate, independently maintained HTML files — one per language tree (en/, fr/, ar/) — with per-language URL slugs and a hard-coded cross-language navigation switcher.
  3. Cloudflare Pages hosting, git-driven deployment. Auto-deploys from main on every push; no separate CI/CD pipeline, staging environment, or automated test suite.
  4. Semantic versioning applied to the repository as a whole, with a corresponding CHANGELOG.md entry per release.
  5. No client-side framework or third-party JavaScript dependency. Small vanilla-JS blocks, duplicated per page, gated behind prefers-reduced-motion.
  6. Cloudflare-managed DNS, TLS, and email-adjacent DNS records, independently confirmed live in registers/website-technical-asset-register.md.

3. Alternatives Considered

No contemporaneous record of an alternatives analysis was found; the following are inferred, not a reconstruction of an actual documented comparison:

Alternative Why it was likely not chosen (inferred)
Static-site generator (Hugo, Eleventy, Astro) with templated localization Would eliminate triplicate-maintenance, but adds a build step and toolchain disproportionate to a six-page, three-language site maintained by one person
Headless CMS with a JS front end Adds a third-party service dependency and ongoing cost for infrequently-changing content
Client-side JS framework (React, Vue, etc.) Unnecessary for a mostly static content site with minimal interactivity
Different hosting provider (Netlify, Vercel, GitHub Pages) Cloudflare Pages was chosen; the _redirects file uses Netlify-shared syntax, suggesting portability was a minor consideration
WordPress (retained, not migrated away from) The repository’s own history shows a deliberate migration away from WordPress, with WP-era artifacts fully removed by v1.0.0

4. Consequences

Positive

Zero build-system complexity or toolchain dependency risk; effectively free hosting and bandwidth at this traffic scale; any collaborator who can write HTML/CSS can edit the site directly; deployment is simple and fast; the versioning/changelog discipline (18 clean, unbroken semver tags) gives the site a genuine audit trail despite no formal CI/CD.

Negative / Trade-offs

Triplicate-maintenance burden — any shared-pattern change must be manually applied across eighteen HTML files rather than one templated source; this is the architecture’s most significant ongoing cost and scales linearly with future page count. Duplicated inline scripts. No automated testing or CI/CD safety net. No canonical www/apex consolidation. Documentation drift risk (see knowledge/rev-1001-website-technical-review.md F-3).

5. Status and Fitness for Purpose

This architecture is judged fit for the corporation’s current scale and operating stage — the corporation remains pre-revenue with minimal commercial activity, per company/strategy/current-status.md. The trade-offs above become more costly if page count, language count, or content-update frequency increases materially, or if the site gains a backend, form processing, or e-commerce integration (relevant to this repository’s publishing/ arm, which notes a possible future Shopify Buy Button / Lulu Direct integration for book sales). Re-evaluating the no-build-system decision would be warranted at that point, not before.

7. Revision History

Version Date Status Summary
1.0 2026-08-04 Accepted (retrospective) Initial retrospective ADR, originally published in ezzi-clarity-os.
— 2026-08-24 Accepted (retrospective) Carried forward into this repository without material change.