Docs / System Architecture

Wahab Waypoint — system architecture

Wahab Waypoint is a product line of three browser-based tools — Domain Context Learner, Architect, and Reviewer — published as a static site. There is no backend, no database, no authentication, and no build step. Everything a user does, from learning a domain to scoring an architecture, happens in their own browser; the only state shared between tools is a small JSON profile stored in localStorage.

0 backend servers 3 browser tools 1 shared store 3 external integrations 10 architectures · 18 workloads · 8 criteria

High-level topology

The diagram below shows the system at a glance. A browser loads the static origin serving wahab2.com, runs all logic client-side, persists state to local storage, and — for two optional features — reaches out to Google Fonts, the jsPDF CDN, and the Google Gemini API.

User / Browser No account · no install All logic runs in-browser Static HTML · CSS · JS Static Origin — wahab2.com CDN-backed · zero server-side code Landing page index.html Waypoint hub waypoint/index.html Docs overview · guides · tour Domain Context Learner domain-context-learner.html Architect architecture-explorer-v1.html Reviewer architecture-reviewer.html Browser localStorage — shared state domain profile · theme · optional Gemini key Google Fonts Inter typeface · web CSS jsPDF 2.5.1 (CDN) ADR export → PDF Google Gemini API Optional Q&A · free tier Key stored in browser only read / write
Every request is served as static files. The only runtime dependencies are Google Fonts, the jsPDF CDN (used for ADR PDF export), and — if the visitor opts in — the Google Gemini API.

Detailed topology

Zooming in: each tool is a self-contained page with its own stylesheet and JavaScript modules. The three tools deliberately share a small set of knowledge and engine modules so the numbers stay consistent — Architect and Reviewer evaluate against the same architectures, scenarios, and weights.

Domain Context Learner domain-context-learner.html 1 · Business domain 12 domains 2 · Priorities 8 qualities · pick up to 4 3 · Data shape volume · realtime · integration · sensitivity 4 · Save profile writes wahab-waypoint.domain-profile domain-learner.js journey state · profile build · persistence Output: a reusable domain profile Architect architecture-explorer-v1.html Workload → Weights → Engine → Ranking Blueprint · ADR · Q&A scenarios.js 18 workload scenarios architectures.js 10 reference architectures domain-context.js reads profile → weight deltas engine.js weighted scoring + ranking diagrams.js blueprint DAG → SVG adr.js ADR text · copy · PDF export qa.js + genai.js local KB · optional Gemini app.js UI state · orchestration Output: winner · tradeoffs · blueprint · ADR Reviewer architecture-reviewer.html reviewer.js fit score · verdict · gaps architectures.js shared with Architect scenarios.js shared with Architect engine.js shared scoring domain-context.js same weight adjustments architecture-reviewer.css tool styles Output: fit score · strengths · gaps wahab-waypoint.domain-profile — shared context browser localStorage · read by Architect & Reviewer External services Google Fonts · jsPDF CDN · Gemini save profile pre-tunes sliders same requirements handoff compare
Colored boxes (violet fill) are modules shared verbatim between Architect and Reviewer, which is what keeps the two tools' verdicts consistent. Arrows show the cross-tool journey: the learner writes the profile, Architect and Reviewer both read it, and the tools hand off to each other through URL query parameters.
Tool / page Shared state or entry point Module shared by Architect & Reviewer External / out-of-scope

Tech stack

The entire product line is plain web technology. No framework, no bundler, no server runtime, no package manager — the deployed files are the source files.

Layer Technology Notes
Language Vanilla JavaScript (ES6+) No TypeScript, no frameworks, no jQuery in the tools
Markup HTML5 Semantic elements, ARIA roles, keyboard-navigable cards
Styling CSS3 with custom properties Theme variables switch light/dark via data-theme
Build None Files deploy as-is; no compile or bundling step
Hosting CDN-backed static hosting wahab2.com, HTTPS
Typeface Google Fonts — Inter Loaded once per page from fonts.googleapis.com
PDF export jsPDF 2.5.1 (cdnjs) Optional; falls back to a .md download
AI Q&A Google Gemini API (optional) Free tier; key stored in the visitor's browser
Persistence Browser localStorage Domain profile, theme, optional Gemini key
🧩

The personal landing page (repo root) is built with Bootstrap and jQuery vendor assets. The Wahab Waypoint product line — the three tools, the hub, and the docs — uses none of that; it is pure vanilla JavaScript.

Shared state & data model

All persistent state lives in the browser. There is exactly one product-level piece of state — the domain profile — plus two per-page preferences.

localStorage key Written by Read by Purpose
wahab-waypoint.domain-profile Domain Context Learner Architect, Reviewer The shared business context that tunes both tools
ate-theme Every page Every page Light / dark preference
ate-gemini-key Architect (Q&A) Architect (Q&A) Optional Google Gemini API key — never committed

Domain profile schema

Produced by Domain Context Learner, versioned for future migration, and validated before it is used:

{ "version": 1, "updatedAt": "2026-08-16T12:00:00.000Z", "domain": { "id": "ecommerce", "name": "E-Commerce & Retail" }, "qualities": [ { "id": "scalability", "name": "Scalability" }, { "id": "resilience", "name": "Resilience & uptime" } ], "data": { "volume": { "id": "high", "name": "High" }, "sensitivity": [ { "id": "cardholder", "name": "Cardholder data" } ], "realtime": { "id": "high", "name": "High" }, "integration": { "id": "complex", "name": "Complex" } } }

Domain profile → priority weights

The bridge between the tools lives in domain-context.js. When a profile exists, its domain, ranked qualities, and data shape are converted into per-criterion weight deltas. Architect adds these to each scenario's baseline requirement, so the priority sliders start pre-tuned; Reviewer adds the same deltas before scoring, so its verdict uses the identical context. The table below shows a representative subset.

Profile input Weight deltas applied
Domain: Financial Services compliance +15, reliability +10
Domain: Healthcare compliance +20, reliability +10, latency +5
Domain: E-Commerce & Retail scalability +10, latency +10, reliability +5
Domain: Media & Streaming scalability +15, latency +10
Domain: SaaS & Multi-tenant scalability +10, simplicity +10
Domain: Public Sector compliance +20
Quality: Cost control costEfficiency +20, simplicity +5
Quality: Time-to-market simplicity +20, latency +5
Quality: Regulatory compliance compliance +25, reliability +10
Quality: Resilience & uptime reliability +25, compliance +5
Quality: Scalability scalability +25
Data: High volume scalability +20, costEfficiency +5
Data: High real-time need latency +20
Data: Complex integration simplicity +10
Data: PII / PHI / Cardholder compliance +10 / +15 / +15

Deltas are summed across every selected quality and data flag, then clamped to the 0–100 slider range. The full mapping is defined in DOMAIN_DOMAIN_WEIGHTS, DOMAIN_QUALITY_WEIGHTS, and DOMAIN_DATA_WEIGHTS in tools/architecture-explorer/js/domain-context.js.

Scoring engine

Architect and Reviewer share one routine (engine.js). Each reference architecture carries a fixed capability score (0–100) for the eight criteria. Given a requirement vector w — the eight priority weights — each architecture receives:

finalScore = clamp( round( 100 × Σ(wᵢ × capabilityᵢ) / Σ(wᵢ) ), 0, 100 )
  • Architect sorts every architecture by this score and returns the winner, the next three as alternatives, and the full ranking. Slider defaults are the scenario baseline plus the domain deltas, snapped to 5-point steps.
  • Reviewer computes per-criterion coverage: min(capability, requirement) ÷ requirement × 100, classifies each criterion as strong / partial / gap / not critical, and derives the verdict from the same weighted score.
Reviewer verdict Fit score
Strong fit≥ 85
Good fit70 – 84
Moderate fit55 – 69
Weak fit40 – 54
Poor fit< 40

Cross-tool handoffs

The products are linked end to end. Architect's recommendation carries a deep link into Reviewer with the chosen architecture pre-selected, and Reviewer links back to Architect for comparison — both via URL query parameters that the pages read on load.

From Deep link What happens on load
Architect → Reviewer ?scenario=<id>&arch=<id> Reviewer pre-selects the workload and the winning architecture
Reviewer → Architect ?scenario=<id> Architect selects the workload and generates a recommendation
Direct scenario link ?scenario=<id> Skips to the result for shareable, bookmarkable URLs

Because Reviewer loads the very same scenarios.js and architectures.js as Architect, scenario and architecture ids always align between the two tools.

Integrations

Integration Type Direction Details
Static hosting / CDN Hosting Inbound Serves the static origin at wahab2.com over HTTPS
Google Fonts Web fonts Outbound Inter, loaded via fonts.googleapis.com
jsPDF (cdnjs) Client library Outbound ADR export to PDF; graceful fallback to .md
Google Gemini API AI (optional) Outbound Enhanced Q&A answers; gemini-flash-latest, temperature 0.4, 2048 max tokens
📡

There is currently no analytics, no comments, no email capture, and no cookie banner anywhere in the product line — no third-party code runs on the page except the three integrations above.

Security & privacy model

  • No backend. There is nothing to breach — no server, database, API of our own, or user account store.
  • Data stays on-device. Domain profiles and theme preferences never leave the browser; they live in localStorage.
  • Optional AI key. The Gemini API key is entered by the visitor, stored only in their own browser, and sent only to Google's endpoint — it is never committed to the repository and never sent anywhere else.
  • No tracking. No analytics, no cookies, no fingerprinting.
  • Hardening notes. The site is served over HTTPS; a future hardening pass could add a Content-Security-Policy header and Subresource Integrity (SRI) attributes to the jsPDF and Google Fonts includes.

Deployment

  • The product line is published as a static origin at wahab2.com, served over HTTPS.
  • A CNAME record maps the custom domain wahab2.com, with automatic HTTPS.
  • robots.txt and sitemap.xml cover crawling and indexing; 404.html provides a styled fallback for unknown paths.
  • clean-url.js hides the .html suffix in the address bar via history.replaceState, giving shareable, readable URLs while the underlying files remain plain static pages.
  • Shipping a change is a commit and a push — the updated static files go live within a minute.