Skip to content

Commit 271d739

Browse files
programmerShinobiclaude
programmerShinobi
and
claude
committed
[docs](app): Phase 6 — CI workflow, DECISIONS.md, EXTENDING.md, README run/stack update
- .github/workflows/ci.yml: lint + unit tests + production build on Node 20 (npm ci), triggered on app-path changes — alongside the existing docs-integrity workflow. - DECISIONS.md: records the build-time choices not pinned by the specs (D4/D5 from the ratified sheet, cost/ops defaults, live scores + 5 presets vs the illustrative mockup, Tabler-react vs webfont, hand-built SVG charts / recharts removed, dark-default, guided==prototype with extras gated to expert mode, authored+translated copy pending professional review). - EXTENDING.md: a config map (one file per concern), how to add a translation, setup import/export, and the guard commands to run after any model change. - README: status → "v1.0 MVP implemented" + CI badge, a "Run it locally" section, corrected tech stack (SVG charts, dark-default, Tabler/fonts), and the SDLC table Phase 4 → implemented. - docs/04-development/README: marked implemented with pointers to run/extend/decisions. Verification: links resolve; 35/35 tests; eslint 0; build clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 985e669 commit 271d739

5 files changed

Lines changed: 193 additions & 12 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'src/**'
8+
- 'index.html'
9+
- 'package.json'
10+
- 'package-lock.json'
11+
- 'tsconfig*.json'
12+
- 'vite.config.ts'
13+
- 'tailwind.config.js'
14+
- 'postcss.config.js'
15+
- '.eslintrc.cjs'
16+
- '.github/workflows/ci.yml'
17+
pull_request:
18+
paths:
19+
- 'src/**'
20+
- 'index.html'
21+
- 'package.json'
22+
- 'package-lock.json'
23+
- 'tsconfig*.json'
24+
- 'vite.config.ts'
25+
- 'tailwind.config.js'
26+
- 'postcss.config.js'
27+
- '.eslintrc.cjs'
28+
- '.github/workflows/ci.yml'
29+
30+
jobs:
31+
build:
32+
runs-on: ubuntu-latest
33+
steps:
34+
- uses: actions/checkout@v4
35+
- uses: actions/setup-node@v4
36+
with:
37+
node-version: '20'
38+
cache: npm
39+
- name: Install dependencies
40+
run: npm ci
41+
- name: Lint
42+
run: npm run lint
43+
- name: Unit tests (scoring engine + exporters)
44+
run: npm run test
45+
- name: Production build
46+
run: npm run build

‎DECISIONS.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# DECISIONS
2+
3+
Choices made while building the application that were **not** fully pinned by the specs, plus a
4+
few notable interpretations. The model values themselves are canonical — see the
5+
[Model Data Sheet](docs/03-blueprint/model-data-sheet.md) and
6+
[Scoring Algorithm Spec](docs/03-blueprint/scoring-algorithm.md); this file records the rest.
7+
8+
## Model
9+
10+
- **D4/D5 `qaFit` were not invented here.** The Build Spec left them "to assign & document," but
11+
they are already ratified in [Model Data Sheet §4](docs/03-blueprint/model-data-sheet.md)
12+
(interim, ADR-0001). `src/config/dimensions.ts` reproduces those exact vectors.
13+
- **Cost & operational-complexity indicators** (`src/config/costOps.ts`) are **defensible expert
14+
defaults**, not values from the Model Data Sheet (the prototype shows none). Chosen profile per
15+
D1 option: Layered/Monolith/Modular-Monolith = ops *low* / infra *low*; Microservices = *high* /
16+
*high*; Serverless = *med* / *med* (scales to zero but variable + lock-in). Editable like any
17+
config; an independent reviewer may revise.
18+
- **Display normalization** is `round(composite / 5 × 100)` (Scoring Algorithm §7), **not** min-max
19+
— min-max would always show the worst option as 0 and exaggerate small gaps.
20+
- **`migrationPathChosen` is kept `false`** in the anti-pattern engine so the `legacy-without-plan`
21+
rule still fires; the migration card is informational guidance, not a model input.
22+
23+
## Scores & presets vs the prototype
24+
25+
- The UI matches [the prototype](docs/03-blueprint/prototype/index.html) **exactly** in look, copy,
26+
and features, with two deliberate exceptions (the prototype's are illustrative):
27+
- **Scores are computed live** from the engine, not the mockup's fixed numbers (e.g. 84%).
28+
- **All 5 presets** are shipped (the mockup chip bar showed 4; `internal-tool` was absent).
29+
30+
## UI / tech
31+
32+
- **Icons:** `@tabler/icons-react` (tree-shaken) instead of the prototype's full icon **webfont** —
33+
identical glyphs at a few KB vs a 457 KB font + 249 KB CSS, protecting the FCP budget (ADR-008).
34+
- **Charts are hand-built SVG/CSS** (radar + priority/score bars); **recharts was removed**. This
35+
matches the prototype's custom radar exactly and drops a heavy dependency.
36+
- **Dark by default** (matches the prototype); light is opt-in via the `html.light` class.
37+
- **Guided/Expert reconciliation:** the prototype has no separate analysis section, but the Build
38+
Spec mandates a risk register, fitness functions, cost/ops indicators, a C4 stub, methodology
39+
references, and a glossary. Guided mode renders **exactly** the prototype's flow; those extra
40+
panels are surfaced in an **expert-only** section so nothing mandated is lost.
41+
- **Primary factors:** the 3 shown by default (`team`, `scale`, `consistency`) mirror the
42+
prototype's three visible questions; the other 11 sit behind "Show the other N factors".
43+
- **Custom-config import/export** is implemented as **scenario** JSON (factors + selections +
44+
overrides + mode + language), the basic version per the charter; richer org-level model-config
45+
editing remains the deferred v2.x item.
46+
- **Omitted prototype theater:** the mockup's artificial skeleton-on-recompute and empty state are
47+
not reproduced — the live engine always has a result, so an empty state would mislead.
48+
49+
## Content & i18n
50+
51+
- **Authored copy:** guided factor questions, plain QA labels, the per-dimension "good / cost /
52+
know" narrative, per-option blurbs, migration steps, and short radar labels were ported from the
53+
prototype (English) and **translated to Indonesian** to match. The 3 factor questions and 4 QA
54+
labels shown in the prototype are verbatim; the rest follow the same register. Indonesian copy is
55+
**interim** — a professional translator review is welcome (charter §14.2).
56+
- **Canonical bilingual content** (factor labels/levels/help, option names, anti-pattern messages,
57+
fitness templates, risks) is reproduced verbatim from the Model Data Sheet and Option Content
58+
Sheet — see [EXTENDING.md](EXTENDING.md) for where each lives.

‎EXTENDING.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# EXTENDING
2+
3+
Every quality attribute, factor, weight, option, `qaFit` value, rule, preset, fitness template,
4+
and string lives in **`src/config/`** or **`src/i18n/`** — never hard-coded in components. The
5+
scoring math is pure and lives in `src/lib/scoring.ts`. So the model is auditable and extensible:
6+
edit data, not UI.
7+
8+
> **Canonical source.** The numeric model is frozen in
9+
> [`docs/03-blueprint/model-data-sheet.md`](docs/03-blueprint/model-data-sheet.md) and the
10+
> computation in [`scoring-algorithm.md`](docs/03-blueprint/scoring-algorithm.md). The bilingual
11+
> educational copy is in [`option-content-sheet.md`](docs/03-blueprint/option-content-sheet.md).
12+
> When you change a model value in code, change it in the Model Data Sheet too and re-run the
13+
> guards (below) so the docs and the app never drift.
14+
15+
## Where things live
16+
17+
| You want to change… | Edit | Notes |
18+
|---|---|---|
19+
| Quality attributes (the 12 QAs) | `src/config/qualityAttributes.ts` | Keep `QA_ORDER` and the `qaFit` vector order in sync |
20+
| Project factors (the 14) | `src/config/factors.ts` | `label`/`levels`/`help` are canonical; `question`/`gloss`/`primary` are guided-mode UI copy |
21+
| Factor → QA influence matrix | `src/config/factorQaMatrix.ts` | `budget` is inverted in the engine — don't add a sign here |
22+
| Dimension options + `qaFit` | `src/config/dimensions.ts` | Vectors in `QA_ORDER`; option order = tie-break order |
23+
| Default factor levels | `src/config/defaults.ts` | All 0 except `ttm:1`, `budget:2` |
24+
| Scenario presets | `src/config/presets.ts` | Full 14-level sets; must hit the SRS §5.3 targets |
25+
| Anti-pattern rules | `src/config/antiPatterns.ts` | Pure predicate over factors + selected options |
26+
| Fitness-function templates | `src/config/fitnessFunctions.ts` | One per QA |
27+
| Risk register data | `src/config/risks.ts` | Keyed `"<dim>:<optId>"`; ported from the Option Content Sheet |
28+
| Cost/ops indicators | `src/config/costOps.ts` | Per D1 option (defensible defaults — see DECISIONS.md) |
29+
| Detail narrative + option blurbs | `src/config/dimensionContent.ts` | "good / cost / know" + per-option one-liners |
30+
| Migration paths | `src/config/migrationPaths.ts` | fresh / big / mix step lists |
31+
| Glossary terms | `src/config/glossary.ts` | Method terms (QAs come from `qualityAttributes.ts`) |
32+
| Methodology references | `src/config/references.ts` | Surfaced in the "How it works" panel |
33+
| UI chrome strings | `src/i18n/dict.ts` | `{ en, id }`; add a key, use `t('key')` |
34+
35+
## Adding a translation
36+
37+
All copy is `{ en, id }`. To add a third language: widen the `Lang` type in `src/types.ts`, add the
38+
language to every `Bilingual` value (config + `dict.ts`), and add a toggle option in the header.
39+
A `t(key)` / `tr(bilingual)` helper from `useI18n()` resolves the active language.
40+
41+
## Import / export a setup
42+
43+
The toolbar (and command palette) export the current setup as JSON (`scenario` = factors +
44+
selections + overrides + mode + language) and re-import it; the full state is also encoded in the
45+
share-URL hash. See `src/lib/scenarioIO.ts` and `src/lib/urlState.ts`.
46+
47+
## Guards — run after any model change
48+
49+
```bash
50+
node scripts/verify-model.mjs # the math + fixtures + all 25 preset targets hold
51+
node scripts/cross-check-docs.mjs # the docs agree with each other and the prototype
52+
npm run test # the engine's TypeScript twin (fixtures A–C, overrides, presets)
53+
npm run lint && npm run build # types + lint + production build
54+
```
55+
56+
If a model change breaks a preset target, **adjust the preset levels — not the targets** — and
57+
re-run, per the Model Data Sheet §6.

‎README.md‎

Lines changed: 27 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
> A transparent, quality-attribute-driven decision-support tool for choosing software architecture — and always explaining *why*.
44
5-
[![Status](https://img.shields.io/badge/status-planning%20%26%20specification-blue)](docs/01-discovery-and-planning/discovery-and-planning.md)
5+
[![Status](https://img.shields.io/badge/status-v1.0%20MVP%20implemented-success)](#run-it-locally)
6+
[![CI](https://github.com/programmerShinobi/architecture-advisor/actions/workflows/ci.yml/badge.svg)](.github/workflows/ci.yml)
67
[![Docs](https://img.shields.io/badge/docs-English-success)](docs/)
78
[![License: MIT](https://img.shields.io/badge/code-MIT-green)](LICENSE)
89
[![License: CC BY 4.0](https://img.shields.io/badge/docs-CC%20BY%204.0-lightgrey)](LICENSE-docs.md)
@@ -49,13 +50,28 @@ about uncertainty: scores are *tunable heuristics, not facts*.
4950

5051
## Project status
5152

52-
> **Planning, specification & design.** This repository holds the discovery charter, the
53-
> requirements specification (SRS), the build specification, the design blueprint (with a model
54-
> data sheet of frozen model values), execution playbooks, and an interactive
55-
> [UI prototype](docs/03-blueprint/prototype/index.html).
56-
> The production application has **not** been implemented yet. See the
53+
> **v1.0 MVP implemented.** The repository holds both the full specification/design set **and** the
54+
> implemented, client-side application (Vite + React + TypeScript). It covers the four-step flow
55+
> across all five dimensions — factors → priorities → recommendation → export — with the trade-off
56+
> radar, anti-pattern detection, sensitivity & migration paths, fitness functions, guided/expert
57+
> modes, EN/ID, dark mode, and ADR / report / CSV / JSON / share exports. The scoring engine is a
58+
> TypeScript twin of the verified model ([`scripts/verify-model.mjs`](scripts/verify-model.mjs)).
59+
> See the
5760
> [evolution roadmap](docs/01-discovery-and-planning/discovery-and-planning.md#15-versioning-policy--evolution-roadmap)
58-
> for what v1.0 (MVP) covers.
61+
> for what's deferred beyond v1.0.
62+
63+
## Run it locally
64+
65+
```bash
66+
npm install
67+
npm run dev # start the dev server (fully client-side)
68+
npm run test # scoring-engine + exporter unit tests
69+
npm run lint # ESLint (strict)
70+
npm run build # production build (static; deploys to GitHub Pages)
71+
```
72+
73+
`npm install && npm run dev` is all you need. To tailor the model see **[EXTENDING.md](EXTENDING.md)**;
74+
for the build-time choices see **[DECISIONS.md](DECISIONS.md)**.
5975

6076
## Documentation
6177

@@ -68,7 +84,7 @@ traceable:
6884
| 1 | [Discovery & Planning](docs/01-discovery-and-planning/discovery-and-planning.md) | Project charter / product vision | ✅ Complete |
6985
| 2 | [Requirement Analysis](docs/02-requirement-analysis/) | [SRS](docs/02-requirement-analysis/software-requirements-specification.md) | 🔬 In progress |
7086
| 3 | [Blueprint (Design)](docs/03-blueprint/) | [Design spec](docs/03-blueprint/design-specification.md) + [Model Data Sheet](docs/03-blueprint/model-data-sheet.md) + [UI prototype](docs/03-blueprint/prototype/index.html) | 🔬 In progress |
71-
| 4 | [Development](docs/04-development/) | Source code (standards, Git, review) | 🚧 Not started |
87+
| 4 | [Development](docs/04-development/) | Source code (`src/`, scoring engine, components) | ✅ v1.0 implemented |
7288
| 5 | [Testing / QA](docs/05-testing-qa/) | Unit/integration/system/UAT + security & perf | 🚧 Not started |
7389
| 6 | [Deployment / Release](docs/06-deployment/) | CI/CD → staging → live ([guide ready](docs/06-deployment/deployment-github-pages.md)) | 🚧 Not started |
7490
| 7 | [Maintenance & Iteration](docs/07-maintenance/) | Monitoring, fixes, updates | 🚧 Ongoing |
@@ -77,10 +93,10 @@ Cross-cutting references — the [Build Spec v3](docs/specs/build-spec-v3.md) an
7793
[execution playbooks](docs/guides/) — support multiple phases. The full map, with an SDLC flow
7894
diagram, is in **[docs/README.md](docs/README.md)**.
7995

80-
## Planned tech stack
96+
## Tech stack
8197

82-
- **Vite + React + TypeScript** (strict), Tailwind CSS with dark mode
83-
- **recharts** (radar + bar charts), **mermaid** (C4-style diagram stub)
98+
- **Vite + React + TypeScript** (strict), Tailwind CSS — **dark by default**, Inter + JetBrains Mono, Tabler icons
99+
- **Hand-built SVG/CSS charts** (trade-off radar + score bars); **mermaid** (C4-style diagram stub, lazy-loaded)
84100
- React hooks only; state persisted to `localStorage` and encoded in the URL hash (shareable links)
85101
- Lightweight i18n (ID/EN), Vitest + Testing Library, ESLint + Prettier
86102
- **Pure client-side** — no backend, database, accounts, or AI calls

‎docs/04-development/README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
# Phase 4 — Development
22

3-
> 🚧 **Not started.** Phase 4 of 7. Begins once the [Blueprint](../03-blueprint/) is stable.
3+
> ✅ **v1.0 implemented.** The client-side app lives in [`src/`](../../src/); run it with
4+
> `npm install && npm run dev`. How to run, tailor the model, and the build-time choices are in the
5+
> root [README](../../README.md#run-it-locally), [EXTENDING.md](../../EXTENDING.md), and
6+
> [DECISIONS.md](../../DECISIONS.md). The scoring engine is a TypeScript twin of the verified model
7+
> ([`scripts/verify-model.mjs`](../../scripts/verify-model.mjs)); CI runs lint + tests + build.
48
59
Writing the code on the [planned tech stack](../specs/build-spec-v3.md#2-tech-stack-use-exactly-this)
610
with consistent standards and conventions, under version control (Git), with code review to keep

0 commit comments

Comments
 (0)