A transparent, quality-attribute-driven decision-support tool for choosing software architecture — and always explaining why.
The same project, two audiences. Guided mode gives newcomers plain-language explanations ("Speed & quick response", a "what this means for you" narrative); Expert mode gives architects the technical attribute names, editable weights, per-attribute contribution bars, and a Professional analysis section (cost & ops, fitness functions, risk register, methodology, a C4 stub, glossary). Both run from the same engine — toggle with one click.
▶ Try it live: programmershinobi.github.io/architecture-advisor — or run it with npm run dev.
| Guided mode (newcomers) | Expert mode (architects) |
|---|---|
 |
 |
Prefer no build step? Open the static UI prototype — it mirrors the app and opens in Expert mode (switch to Guided with the header toggle).
Choosing how to build a system — the deployment model, how services talk, how data is managed — is decided early, hard to reverse, and disproportionately shapes the system's quality. In practice these decisions are too often made by trend rather than by an explicit trade-off analysis.
Architecture Advisor is a planned, fully client-side web app that turns that decision into a transparent pipeline:
PROJECT FACTORS ─► QUALITY-ATTRIBUTE PRIORITIES ─► ARCHITECTURE FIT ─► ANALYSIS
(drivers & (a weighted "utility tree" of (how well each option (trade-offs, risks,
constraints) quality attributes, grounded satisfies the sensitivity, fitness
in ISO/IEC 25010:2023) prioritized QAs across functions, ADR/report)
5 orthogonal dimensions)
You answer a handful of questions about your project; the tool recommends an architecture across five dimensions, ranks the alternatives, and — critically — shows the full calculation: which factor raised which quality attribute, and how that produced the score. Experts get auditable numbers and editable weights; newcomers get plain-language explanations.
It adapts established methods — ISO/IEC 25010:2023, ATAM, Attribute-Driven Design, and evolutionary-architecture fitness functions — into an interactive tool, and is honest about uncertainty: scores are tunable heuristics, not facts.
The built-in Guide (the “Panduan / Guide” button) is a genuine deep-dive: alongside the full
scoring walkthrough it now explains every architecture the Advisor evaluates (all five
decisions) in plain language for newcomers and experts — What / When it fits / What it costs /
Deeper per option — backed by a cited bibliography (Bass, Newman, Kleppmann, Fowler, Richards &
Ford, SEI, and peer-reviewed surveys). Canonical source:
docs/03-blueprint/architecture-reader.md.
An Insights area (top nav: Advisor · Insights) covers every architecture the Advisor
evaluates through four lenses — Catalog (discover it), Playbook (implement it, step by
step), Review (evaluate it: pros/cons, performance, scalability, DX, verdict), and Library
(reference: definition, concepts, patterns, terminology) — data-driven from the frozen model, so
coverage can never be partial or drift (a unit test asserts 21×4 parity). Each architecture carries
several cited, trusted references (books + peer-reviewed journals); no content is duplicated across
lenses — a per-page lens nav walks the Catalog → Playbook → Review → Library knowledge journey. The
sections also list hand-authored, English-first Markdown guides under content/, each
bound to the model and gated by content:validate. Three more sections build on top of the
lenses: Roadmap (guided learning paths), Academy (client-side quiz modules that link back to
the page that teaches each answer), and Lab (hypothesis experiments whose prepared scenarios
load into the live scoring engine) — each covering all 21 architectures too (unit-tested
parity, matching the lenses). The area is client-rendered, lazy-loaded, and
dependency-free (a small XSS-safe Markdown renderer); search engines get a build-time SEO
layer (sitemap, robots, JSON-LD, static crawlable article snapshots) without any SSG/router —
see the content rollout plan.
v1.0 MVP implemented. The repository holds both the full specification/design set and the implemented, client-side application (Vite + React + TypeScript). It covers the four-step flow across all five dimensions — factors → priorities → recommendation → export — with the trade-off radar, anti-pattern detection, sensitivity & migration paths, fitness functions, guided/expert modes, EN/ID, dark mode, and ADR / report / CSV / JSON / share exports. The scoring engine is a TypeScript twin of the verified model (
scripts/verify-model.mjs). See the evolution roadmap for what's deferred beyond v1.0.
Prerequisite: Node 24 (LTS) — the version is pinned in
.nvmrcand used by all CI workflows (node-version-file), so local and CI always match.
npm install
npm run dev # start the dev server (fully client-side)
npm run test # unit + component + a11y tests (engine, exporters, UI, axe)
npm run lint # ESLint (strict)
npm run build # production build (static; deploys to GitHub Pages)npm install && npm run dev is all you need. To tailor the model see EXTENDING.md;
for the build-time choices see DECISIONS.md.
The project is organized along the software development lifecycle (SDLC) — one numbered folder per phase, each with a concrete deliverable — so the flow of work is explicit and traceable:
| # | Phase | Output | Status |
|---|---|---|---|
| 1 | Discovery & Planning | Project charter / product vision | ✅ Complete |
| 2 | Requirement Analysis | SRS | 🔬 In progress |
| 3 | Blueprint (Design) | Design spec + Model Data Sheet + Architecture Reader + Content Rollout Plan + UI prototype | 🔬 In progress |
| 4 | Development | Source code (src/, scoring engine, components) |
✅ v1.0 implemented |
| 5 | Testing / QA | Test plan — 99 Vitest + Playwright E2E + 3 model guards + content guard; CI gates size/audit; 14/16 AC automated | 🔬 In progress |
| 6 | Deployment / Release | Live on GitHub Pages via deploy.yml (CI/CD) |
✅ Live |
| 7 | Maintenance & Iteration | Changelog, Dependabot, issue/PR templates, security policy | 🔄 Ongoing |
Cross-cutting references — the Build Spec v3 and the execution playbooks — support multiple phases. The full map, with an SDLC flow diagram, is in docs/README.md.
Recommended: the latest two stable versions of Chrome, Edge, Firefox, or Safari — desktop and mobile. The app is responsive down to a 360 px viewport and is verified for WCAG AA in both light and dark themes.
- Baseline (the "evergreen" verification target): ES2020 +
localStorage. Internet Explorer is not supported. - Older or non-conforming browsers (or with JavaScript disabled) get a readable message
recommending a modern browser, not a blank page (SRS
FR-EDGE-4). - Automated E2E runs on Chromium (Playwright); Safari iOS / Firefox are covered by the shared evergreen standards — a quick manual look is advised before a release.
The canonical statement is SRS §2.3 — Operating Environment.
- Vite + React + TypeScript (strict), Tailwind CSS — dark by default, Inter + JetBrains Mono, Tabler icons
- Hand-built SVG/CSS visuals (trade-off radar, score bars, C4-style diagram stub) — no chart or diagram library
- React hooks only; state persisted to
localStorageand encoded in the URL hash (shareable links) - Lightweight i18n (ID/EN), Vitest + Testing Library, ESLint + Prettier
- Pure client-side — no backend, database, accounts, or AI calls
- Responsive to 360px; WCAG AA in both themes — names/roles/ARIA, keyboard, and color-contrast verified by axe + Playwright (test plan)
- Intellectual honesty — decision support, not an oracle. Surface uncertainty, close calls, and a permanent disclaimer.
- Transparency — every score is traceable from factor → QA weight → option fit.
- Methodological grounding — cite ISO/IEC 25010:2023, ATAM, ADD, fitness functions.
- Approachable yet deep — guided mode for newcomers, expert mode for architects.
- Actionable & shareable — export an ADR (MADR) and a full report; share via URL.
- Open & evolving — community-built, improving across versions.
Contributions are welcome — code, documentation, translations, and model review. Start with CONTRIBUTING.md and the Code of Conduct. Governance, roles, and the contribution flow are described in Section 14 of the discovery charter.
Faqih Pratama Muhti, B.Sc. Computer Science — Product Owner, Maintainer.