source: .forge/design/architecture-decisions-why.md · generated — edit the markdown, not this file

Architecture Decisions — why each was made

The Why column of .claude/CLAUDE.md § Architecture Decisions (DO NOT REVERSE), which keeps each decision’s rule and date. It moved here so that it is not loaded into every request; the rule in CLAUDE.md is what binds. Read the row here for the reason behind a decision and its lead sign-off. The full text of every row as it stood on 2026-09-23 and on 2026-10-02, and the original sign-off wording and trade-offs of AD #29 onwards, are in .forge/engagement-log.md § Architecture Decisions — full rationale archive. A new or refining decision adds its Why row here in the same PR that adds its row to CLAUDE.md.

# Why Date
1 Team’s existing enterprise-backend stack 2026-07-13
2 Client prototype’s own runtime is React-based; strongest ecosystem for Kanban/calendar widgets 2026-07-13
3 PRD-preferred; structured domain model; mature Flyway/JPA tooling 2026-07-13
4 Broadest managed-service catalog; team’s enterprise-stack familiarity; UAT holds test data only, so it stays out of the production account and copies nothing per round 2026-07-13 (uat clause 2026-10-23)
5 The session model stands; the original dual-login rationale was superseded by AD #28 2026-07-13
6 Isolates the OQ-15/R-PRD-002 self-hosted-model fork so a “no” swaps an implementation, not a rewrite 2026-07-13
7 Team scale (10–20 users) doesn’t justify microservice/K8s complexity; in-house-first 2026-07-13
8 Keeps core schema stable and query-performant while allowing schema-less extension 2026-07-13
9 One uniform gate for both ecosystems 2026-07-13
10 R-PRD-001 accepted risk; keeps the seam ready without blocking on an unconfirmed ERP API 2026-07-13
11 Prevents admin pipeline edits (F24) from silently breaking AI/automation logic keyed on stage semantics (R-14) 2026-07-13
12 With more than one ECS task, @Scheduled fires on every task — duplicate alerts and duplicate buyer-facing email 2026-08-06
13 SQS standard queues deliver at-least-once; an outreach step sent to a buyer twice is unacceptable 2026-08-06
14 Price history + as-of quoting are PRD requirements (OQ-33/38/42); temporality cannot be retrofitted without rewriting every read path. Neither exception changes an as-of read for a day before today. Cost exception: lead sign-off, Tharinda, 2026-10-05. Price-withdrawal exception: lead sign-off, Tharinda, 2026-10-11 2026-08-06 (exceptions 2026-10-05, 2026-10-11)
15 OQ-47 requires layered access across roles, which a flat authority check cannot express 2026-08-06
16 The issued proposal quoted Microsoft 365 via Graph only, and OQ-24 confirmed it is all Empire uses; the seam keeps a later provider cheap 2026-08-06
17 Its return rested on OQ-50’s assumed reuse of the generic layer, which is no longer expected (AD #29) 2026-08-06
18 Team decision; matches every existing Altrium backend’s convention 2026-08-18
19 One vendor and one bill, with in-account processing as the strongest data-governance answer; Bedrock’s new-model lag is acceptable because models are pinned 2026-08-18 (models revised 2026-09-30)
20 It matches proposal §4 and a working prototype exists; the descope lever back to capture-and-feed is decided at the capture-app checkpoint, which the Statement of Work of 2026-09-29 holds during Phase 2, date to be set (project-timeline.md §2) 2026-08-18
21 Internal, authenticated apps with no SEO need; an SPA is simpler to build, test and host, and matches the team’s frontend convention 2026-08-18
22 An SPA needs no server and S3 + CloudFront costs less than a Fargate frontend, and secrets never sit in git, images, task definitions or the bundle 2026-08-18
23 The temporary UAT environment is only cheap if it is one terraform apply away, and IaC keeps dev and prod the same shape; DevOps (Shyamin Ayesh) works in the separate repository, which the lead confirmed on 2026-09-29; S3’s lock file is what forge-et-iaac uses and needs no extra table; one uat instance kept from Phase 1’s round to the end of Phase 2’s keeps the hand-entered UAT data and the testers’ records across Phase 1’s two releases and into Phase 2, for about $100–155 in all if it runs throughout, on dev’s measured cost, less if paused between the rounds; a person does every pause and destroy so that a round running late is never cut off (the lead, 2026-11-18) 2026-08-19 (location revised 2026-09-29; locking revised 2026-10-02; UAT lifetime revised 2026-11-18)
24 A phase can reach production before V1 signs off, so a hotfix path free of next-phase work is needed as soon as something is live, and tags give immutable handover artifacts while main stays the single integration point 2026-08-19 (manual dev deploy of a branch 2026-10-18)
25 Boot 3.5’s free support ended 30 Jun 2026 and 4.0’s ends 31 Dec 2026, before V1 sign-off. The line moved from 4.1 (support to 31 Jul 2027) to 4.2 (support to 31 Dec 2027) for its longer open-source support, when 4.2.0 was released. Lead sign-off: Tharinda, 2026-11-20 (the 4.2 line) 2026-08-21 (4.2 line 2026-11-20)
26 role == ADMIN would silently make every future Administrator a below-floor-pricing approver, and no audit log would catch it 2026-08-21
27 OWASP Dependency-Check cannot scan pnpm and Trivy was the only free tool meeting every AD #9 property on both ecosystems; accepted: GHSA advisories can lag NVD by days to weeks, to revisit when the release check is built (AD #38). Revisited once the release check was built: the lag stays accepted, because every app repo is scanned every night and a UAT or production release stops on any open HIGH/CRITICAL finding, so a late advisory is caught on the first night after it reaches Trivy; Dependabot reads the same reviewed advisories, so it does not shorten the lag. Lead sign-off: Tharinda, 2026-11-03 2026-08-31 (revisited 2026-11-03)
28 Empire is all Microsoft 365 (OQ-24), so a local fallback protected nobody and dropping it removes password storage and reset/lockout surface; accepted: an Entra outage blocks all login, and every user needs an Empire M365 account 2026-09-04
29 The split’s only return was OQ-50’s assumed reuse of the generic layer, which is no longer expected. Lead sign-off: Tharinda, 2026-09-07 (history: architecture.md § Core / Domain Separation) 2026-09-07
30 Empire asked for fully configurable roles (2026-09-07), which a fixed per-role matrix cannot express; treated as a V1 requirement with no change request (proposal §3.2 post-issue note). Lead sign-off: Tharinda, 2026-09-07 2026-09-07
31 The scaffolding AD #29 had kept taxed every feature for a payoff already gone, and removal cost was at its lowest. Lead sign-off: Tharinda, 2026-09-09 2026-09-09
32 Each removed mechanism was one nobody asked for and an Administrator would have to learn; a team decision, confirmed by Dinil. Lead sign-off: Tharinda, 2026-09-11 (the account briefing moved to the user-invoked examples, F13: Tharinda, 2026-10-21) 2026-09-11 (account briefing moved 2026-10-21)
33 Less AWS configuration than routing the backend through each app’s CloudFront, and the reply URLs on api.* keep working (three new mailbox URLs instead of nine); accepted: a small cookie change in the backend and both frontends, per-environment settings that must match, and a CORS preflight on writes. Lead sign-off: Tharinda, 2026-09-24 2026-09-24
34 The lead’s design (2026-09-22/24) uses the fewest keys that describe the business and a seeded admin so the first person can get in; the superadmin, the nine admin keys and the category axis were mechanisms nobody needed. Administration was folded into settings.manage because Users and Roles became pages of Settings (design-system Rev 70), and one permission per Settings page was more than Empire has asked for (.forge/owed.md; superseded by AD #41). Lead sign-off: Tharinda, 2026-09-24 (the fold into settings.manage, decided by Nanndish on 2026-10-26: Tharinda, 2026-10-27) 2026-09-24 (refined 2026-10-26, 2026-10-28)
35 The lead’s design (2026-09-23): the reporting tree for managers and explicit shares for everyone else, with one rule for lists and records, which removes the list-versus-record mismatch F1-a ships as an interim (its FR-O3, Q-11). Lead sign-off: Tharinda, 2026-09-24 2026-09-24
36 Unlimited self-escalation (AD #34) and transitive sharing (AD #35) are acceptable only because every change can be attributed afterwards; an audit row for every message opened in the inbox would bury that trail. Lead sign-off: Tharinda, 2026-09-24 (the Outlook-state clause: Tharinda, 2026-10-28) 2026-09-24 (Outlook-state clause 2026-10-28)
37 The scope choice only mattered for managers, whom the reporting line already records, so only “every record” needs a setting, and every recommended role holds one reach per entity for view and manage alike, so none is lost. Lead sign-off: Tharinda, 2026-09-27 2026-09-27
38 An enforcing PR gate stops every merge, and so every dev deploy, the day an advisory is published against a dependency the PR never touched; dev has to deploy as soon as the AWS work allows. What Empire receives still meets the proposal’s control. Lead sign-off: Tharinda, 2026-10-02 (where Trivy runs restated for all three app repos’ nightly runs: Tharinda, 2026-10-12; no image scan in the dev deploy: Tharinda, 2026-10-20; the nightly scan named as the Mac’s nightly full run, CI’s scheduled run now weekly: Tharinda, 2026-11-03) 2026-10-02 (restated 2026-10-12, 2026-10-20, 2026-11-03)
39 Building every primitive in-house left screens with inconsistent spacing, alignment, sizes and states, each fixed one screen at a time; rebuilding the Users screen on shadcn’s components removed that kind of problem, so the whole frontend composes from one library. Lead sign-off: Tharinda (approval reported by Nanndish, 2026-10-09; the enforcing test reported approved by Nanndish, 2026-10-12) 2026-10-09 (test 2026-10-12)
40 One way in every environment, and no USD 0.40-a-month secret for a value that is not sensitive; a plain value can be read in the task definition. Lead sign-off: Tharinda, 2026-10-28 (F38-i spec Rev 1, decisions 23–24) 2026-10-28
41 A role can be given some Settings pages and not others — the tags or the email templates without users and roles — which one key could not express (the owed item it closed is quoted in .forge/engagement-log.md § AD #41); accepted: a Users or Roles holder can still give themselves every page. Lead sign-off: Tharinda (agreement reported by Nanndish, 2026-10-30) 2026-10-30
42 Reps work the show from the app, where the notifications bell and the on-screen notice already tell them when a lead is ready and what teammates decided, so an email repeats it; dropping it removes F36-c’s sender, recipients and template (proposed by Nanndish with the capture-app redesign, .forge/engagement-log.md § AD #42); accepted: a rep with the app closed learns nothing until they open it. Lead sign-off: Tharinda (confirmation reported by Nanndish, 2026-11-12) 2026-11-12
43 The CRM and the capture app are one product to Empire’s staff, and AD #39’s reason holds here too: the capture app’s own components draw spacing, sizes and states each screen differently, while one library keeps both apps consistent and lets a fix in one be copied to the other. Accepted: four more runtime packages on the phone (about 33 kB more in the entry chunk, mostly tailwind-merge) and a period with two component sets in the capture app while the screens move (.forge/design/ui/pwa-shadcn.md). Lead sign-off: Tharinda (agreement reported by Nanndish, 2026-11-20) 2026-11-20

Generated from .forge/design/architecture-decisions-why.md by .claude/lib/render-docs-html.js. Markdown is canonical.