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 |