Tech stack & architecture reference
A plain-terms map of the Empire Teas CRM stack: frontend, backend, how they talk, hosting, and the AI layer. For orienting new joiners and anyone who needs the shape of the whole thing in one place.
Reference snapshot compiled 2026-09-18 from the live repos (
forge-et-be,forge-et-fe,forge-et-pwa). Where a fact could age (versions, a running environment), treat it as “true when written” and re-check against the code — the repos and each repo’sCLAUDE.mdare the source of truth.Updated 2026-09-24 for the access-model decisions (AD #34, AD #35, AD #36): the auth table and the locked-decisions list describe what was decided. Rows marked decided … built by describe work not yet on
main.
At a glance: Java 21 · Spring Boot 4.2 · React 19 · Vite · PostgreSQL · AWS (Fargate · S3 · CloudFront) · Claude via Bedrock.
The big picture
Three deployable apps, one shared design language, one backend:
flowchart TD FE["CRM web app — forge-et-fe<br/>React SPA · main product screens"] -->|HTTP JSON /api/v1| BE["Backend API — forge-et-be<br/>Spring Boot · rules, data, AI"] PWA["Capture app — forge-et-pwa<br/>React PWA · trade-show capture (Phase 1)"] -->|HTTP JSON /api/v1| BE BE --> DB[(PostgreSQL)] BE --> Bedrock["Claude via Amazon Bedrock"]
The two frontends are static bundles (just HTML/JS/CSS files) served from S3 + CloudFront. The backend is the only running server. Everything a frontend does that isn’t drawing pixels goes through the backend’s REST API. The capture app mirrors the CRM app’s layout and even keeps byte-identical copies of the shared design-token files (a drift check enforces they stay in sync).
One-line mental model: the frontends are “dumb” render layers that hold no secrets and enforce nothing security-critical; the backend owns the truth, the rules, the data and the AI. The browser is never trusted.
Frontend stack
TypeScript + React 19, built and bundled by Vite, package-managed by pnpm. No server-side rendering — it’s a pure single-page app, because it’s an internal authenticated tool with zero SEO need.
| Concern | Library | What it does / why |
|---|---|---|
| UI framework | react 19 + react-dom |
The component runtime. The client’s prototype was already React, so nothing was lost in translation. |
| Build / dev server | vite |
Fast dev server (hot reload) and the production bundler. pnpm dev serves on :5173; pnpm build emits static files to dist/. |
| Language | TypeScript | Types everywhere. pnpm typecheck = tsc --noEmit. Strict; no unchecked as casts at the API boundary. |
| Routing | react-router-dom 7 |
Client-side routing. Routes are lazy-loaded per feature (code-splitting), assembled in src/app/router.tsx with createBrowserRouter + <RouterProvider>. |
| UI components (CRM) | shadcn/ui on radix-ui |
Since 2026-10-09 (AD #39) the CRM’s components: shadcn’s source copied into src/ui/shadcn and adapted, with Radix UI supplying the behaviour (focus management, ARIA, keyboard). Added with the shadcn CLI. |
| Styling (CRM) | tailwindcss v4 (+ @tailwindcss/vite, tw-animate-css), class-variance-authority, clsx + tailwind-merge |
Utility classes for the shadcn components, mapped onto the --et-* tokens; cva defines component variants; cn() merges class lists. |
| Accessible components (older screens) | react-aria-components |
Behaviour behind the in-house Combobox and Tooltip on screens not yet moved to shadcn; no new use. |
| Toasts, command menus | sonner; cmdk not yet |
Sonner is installed with shadcn’s sonner component. cmdk comes with shadcn’s Command component, added by the first screen that uses one (a new dependency, so ask first). |
| Icons | lucide-react |
The icon set — imported in exactly one file (a concept registry). See “Styling & icons”. |
| Fonts | @fontsource-variable/inter |
Self-hosted variable font (no Google Fonts network dependency). Inter is the one typeface, for headings and body alike (Fraunces was dropped, design-system Rev 18). |
| Unit/component tests | vitest + React Testing Library + jsdom |
pnpm test. Renders components in a fake DOM; asserts behaviour by role/label, not implementation. |
| Browser E2E | @playwright/test + @axe-core/playwright |
Real-browser end-to-end tests + automated accessibility scans. pnpm e2e. Not run in the PR lanes — run by the delivery orchestrator before a wave ships. |
| Lint / format | biome |
One tool for both. pnpm check. Accessibility lint rules are errors, not warnings. |
| Folder boundaries | dependency-cruiser |
pnpm check:boundaries — enforces the src/{app,features,ui,lib} import rules, no cycles, no orphans. |
| Extra guards | knip, custom node scripts |
Dead-code report (advisory), bundle-size budget per route chunk, and a check that every interactive element is addressable by role/label/data-testid. |
| Git hooks | husky + lint-staged + commitlint |
Pre-commit formatting and commit-message convention enforcement. |
The forge-et-pwa capture app uses the same stack, shadcn/ui and Tailwind included (AD #43; its older screens were moved over one at a time, .forge/design/ui/pwa-shadcn.md), and adds PWA service-worker validation on build.
Styling & icons
Styling: shadcn/ui on Tailwind, on the design tokens (AD #39)
There is no CSS-in-JS library (no styled-components, no Emotion). Since 2026-10-09 the CRM styles in three layers:
- Design tokens — CSS custom properties named
--et-*(colours, spacing, radius, typography): names and fallbacks insrc/ui/styles/tokens.css, Empire’s values intheme-empire.css, and the revamped colour layer intheme-revamp.css, which a route opts into (handle.theme: 'revamp') as its screens move to shadcn. Raw hex is only allowed in the token and theme files. - Tailwind v4 utility classes for the shadcn components.
src/ui/styles/shadcn.cssmaps every colour, radius, face and text size Tailwind names onto the tokens (@theme inline), sobg-primaryorrounded-mddraws the design system’s value. Tailwind’s global reset (preflight) is left out, so pages not yet moved over are unchanged, and it scans onlysrc/ui/shadcnand the features listed in its@sourcelines. - CSS Modules — a
.module.cssper component or feature for layout that is easier in CSS, and the only styling on screens not yet moved over. Unlayered module rules win over Tailwind’s layered utilities when both style one element.
Light/dark and the fixed brand surfaces are all expressed as tokens, so a theme is a token swap, not a component change (e.g. the login screen’s deep-green brand panel and gold button are pure tokens).
Components: shadcn/ui first, the in-house set on older screens
New and changed UI uses the shadcn components in src/ui/shadcn (the current list is the files in forge-et-fe src/ui/shadcn/; more are added with the shadcn CLI as screens need them). Each is adapted to the CRM’s rules: disabled renders as aria-disabled, base.css’s global focus ring is the focus indicator, icons come from the registry, and inside a Field a control takes the field’s id and aria-* wiring. The rules are in forge-et-fe/CLAUDE.md § Conventions.
The older in-house set in src/ui/components/ stays on the screens not yet moved over. It is built on native elements, with react-aria-components for Combobox and Tooltip, and styled with CSS Modules and tokens. Its components are AiProvenance, Avatar, Badge, Button, Card, Checkbox, Combobox, DateInput, DropdownMenu, EmptyState, ErrorPanel, Field, Input, LoadingSkeleton, Modal, Radio, Select, StatusIndicator, Switch, Tabs, Toast, Tooltip. Which screens still use them is in .forge/design/ui/shadcn-backfill.md. The StatusIndicator (dot plus word for a state) has no shadcn equivalent and stays.
Plus a config-driven FieldRenderer (src/ui/fields/) that renders form fields from a registry, and a permission layer (src/ui/permissions/) that hides or disables UI based on what the user is allowed to do.
Icons: lucide-react, behind a one-file concept registry
Icons come from lucide-react, but the library is imported in exactly one place: src/ui/icons/registry.ts. That file maps a concept (“close”, “search”, “retry”, “error”…) to a glyph; an Icon.tsx component draws one by concept name.
Why: an icon is a concept, not a drawing. Naming it once means two screens can’t pick different glyphs for the same idea, the drawing changes in one place, and swapping icon libraries later is a one-file edit. A lint check greps for the lucide-react import and expects only this file to match.
Why shadcn/ui now, and why it was not chosen at first
AD #39 (2026-10-09) reversed the choice below for the CRM. Building every primitive in-house left each screen to get spacing, sizing, alignment and layering right by itself. The UI review found the same kinds of problem on screen after screen. shadcn’s components are copied into the repo rather than imported, so they can still be adapted to the CRM’s accessibility rules and tokens, and Radix UI supplies tested behaviour. Two of the original objections no longer held:
- Radix has no combobox primitive, but shadcn builds one from its Command list in a Popover.
- Tailwind’s names do map onto the
--et-*tokens, through one@theme inlineblock inshadcn.css, without renaming the tokens.
The reasoning as it stood before AD #39 follows, kept because it explains the in-house components that remain.
The stack was chosen deliberately over the common alternatives, on two axes: WCAG 2.1 AA at the lowest cost and theme reuse for the next client — not developer velocity (which is Tailwind’s / shadcn’s pitch). Documented in .forge/design/ui/design-system.md (build posture, decided 2026-08-25) and .forge/plans/foundation/003-design-primitives-plan.md (Decision Q-3):
- Native-first, over a component kit (MUI / Ant Design). Where a good native HTML element exists it is the component —
<input type="date">,<select>,<dialog>, a real<button>— because native elements arrive keyboard- and screen-reader-correct, the cheapest way to hold the AA commitment. A visual kit would also fight the client’s bespoke brand, which already existed in the approved prototype (AD #2 / #21) — there is nothing to gain from adopting someone else’s look. - A headless library only for the two gaps native can’t fill: combobox/typeahead and tooltip. The pick compared four criteria: accessibility track record, both components present, a permissive licence, and per-component tree-shaking.
- Radix: rejected, because it has no combobox primitive. This is why the in-house set isn’t shadcn’s Radix stack.
- Headless UI: rejected, because it has no tooltip.
- Base UI: runner-up; newer, with a shorter screen-reader track record.
- react-aria-components: chosen. It is Adobe’s, with the strongest accessibility and screen-reader track record available. So it is native-first with react-aria-components for combobox + tooltip — not react-aria-components everywhere.
- CSS Modules + tokens, over Tailwind. Tailwind was weighed and set aside: Tailwind v4 derives utility class names from specifically-named properties, so the
--et-*token set would not produce utilities without aliasing every token — a real cost for no gain over scoped CSS Modules. And design tokens are the reuse story: the same screen renders in Empire’s theme and a committed neutral theme by swapping one import (the “reuse proof for the next client”, FR-T5) — a third-party kit’s baked-in look fights that.
Backend stack
Java 21 on Spring Boot 4.2.x, built with Gradle (Groovy DSL). One module, feature-first packages. It is the only running service and owns all business rules, data and AI calls.
| Concern | Library | What it does / why |
|---|---|---|
| Web / REST | spring-boot-starter-webmvc |
The HTTP layer — controllers serving /api/v1/** JSON. Classic servlet MVC (not reactive). |
| Security & login | spring-boot-starter-security + -oauth2-client |
Auth, CSRF, authorization. OAuth2 client drives Microsoft (Entra) login. |
| Sessions | spring-session-jdbc |
Server-side sessions stored in Postgres (not JWT). The browser holds only an opaque SESSION cookie. |
| Data access | spring-boot-starter-data-jpa |
ORM over PostgreSQL (Hibernate). Repositories per feature. |
| Migrations | flyway-core + flyway-database-postgresql |
Versioned SQL migrations (V1…) run on startup. All schema changes are migrations — never hand-applied. |
| Database driver | postgresql |
PostgreSQL (AWS RDS in cloud; a local Docker Postgres in dev). |
| Validation | spring-boot-starter-validation |
Bean Validation (@NotBlank etc.) on request bodies and config. |
| API docs | springdoc-openapi |
Generates the OpenAPI/Swagger spec from the controllers. |
| Background jobs | spring-cloud-aws-starter-sqs |
Async workers consume AWS SQS queues (in-account; LocalStack in dev). Every job carries an idempotency key (at-least-once delivery). |
| File storage | software.amazon.awssdk:s3 |
Attachments in S3 (LocalStack in dev). Presigned URLs; a virus-scan gate on upload. |
| Health / metrics | spring-boot-starter-actuator + micrometer-tracing (Brave) |
/actuator/health (liveness/readiness) + distributed tracing. |
| Nullability & boilerplate | jspecify (@NullMarked) + lombok |
Null-safety annotations enforced by NullAway/Error Prone; Lombok cuts constructor/getter boilerplate. |
| Logging bridge | jcl-over-slf4j |
Required because Spring Framework 7 removed spring-jcl (a Boot 4 detail). |
| Tests | spock (Groovy) + spring-test |
Spock is the test framework (Groovy). ./gradlew check runs everything. |
| Architecture tests | archunit |
Enforces layering/boundary rules in code (e.g. web → service → repository) as failing tests. |
| Integration DBs | testcontainers (postgres + localstack) |
Spins real Postgres/LocalStack in Docker for integration tests — no mocks for the DB. |
| Quality gates | Error Prone + NullAway, -Werror, doclint, Spotless |
Compile fails on warnings, nullness violations, format drift. Mandatory Javadoc “spec blocks” on beans. |
Build note: Boot is pinned to the 4.2 line deliberately (AD #25). The pin moves about once a year, to the Boot line with the longest free support: 3.5 lost it in mid-2026, and 4.2’s runs to the end of 2027. The Boot 4 line brings Spock 2.5-groovy-5.0 and the jcl-over-slf4j bridge. The move from 3.5 was taken while the backend was still a shell, so it cost little.
How the front and back talk
Everything crosses one seam: a JSON REST API under /api/v1/**. There is no GraphQL, no WebSocket for the core app.
flowchart LR B["Browser (SPA)<br/>apiClient — a fetch wrapper in src/lib/api"] -->|"HTTP JSON · credentials:'include' · CSRF header · RFC 9457 errors"| C["Spring controllers<br/>@RestController → service → repository → Postgres"]
The frontend HTTP client:
- One thin
fetchwrapper (apiClient.get/post) under TanStack Query, which every server read and write goes through (oneQueryClientProviderat the app root;.claude/CLAUDE.md § Stack). - Always sends the session cookie (
credentials:'include'). - Reads the
XSRF-TOKENcookie and echoes it as theX-XSRF-TOKENheader on writes. - A
401from any call clears the session and redirects to/login, preserving the attempted route. - Parses errors from the standard RFC 9457 “problem+json” envelope into a typed error.
Dev vs production wiring:
- Dev: the Vite dev server (:5173) proxies
/api→ backend (:8080), so the SPA and API look same-origin to the browser. (A subtlety: the proxy must strip the browserOriginheader, or the backend’s empty local CORS list rejects writes — a real bug caught by F5-a’s browser tests.) - Production: SPA on CloudFront, API behind an ALB — genuinely cross-origin, so real per-environment CORS is configured. Cookies use
Secure; a cookie-domain setup ties them together.
External integrations are hidden behind seam interfaces so a provider can be swapped without a rewrite: AIProvider (Claude via Bedrock), MailboxProvider (Microsoft Graph), ErpHandoffService (manual doc in V1), and a lead-research SearchProvider. Each is built by the first feature that needs it.
Auth, session & permissions
| Aspect | How it works |
|---|---|
| Login | Microsoft (Entra ID) OAuth2 only. No Google, no local passwords — Empire is an all-Microsoft-365 shop, so every user already has an M365 account. “Sign in with Microsoft” is a full-page redirect to /oauth2/authorization/microsoft. The verified email must match exactly one active user that an administrator created beforehand — nobody is auto-provisioned, and there is no invitation email (AD #34). |
| Users | Deactivated and reactivated, never deleted. Deactivating a user ends their sessions at once (their next request gets a 401). Nobody can deactivate themselves (AD #34). Decided 2026-09-24; the session end is built by F5-c (done). |
| Local/CI | A profile-scoped stub login (POST /api/v1/auth/stub-login, local/test only) so laptops and CI need no Entra registration. Structurally absent from cloud builds. |
| Session | Server-side, stored in Postgres via Spring Session JDBC. Browser holds an opaque SESSION cookie (HttpOnly). Not JWT. |
| CSRF | A JS-readable XSRF-TOKEN cookie; the SPA echoes it in the X-XSRF-TOKEN header on state-changing requests. The token rotates on login. |
| Session bootstrap | On load, the SPA calls GET /api/v1/me. A 200 renders the app (gating every route with no flash of authenticated UI); a 401 sends the user to /login. The SPA calls it again after any 403 and when the window regains focus, so a permission change shows up without a reload (AD #34 — the backend re-reads grants on every request). The re-read is decided 2026-09-24 and built by F5-k. |
| Permissions | A code-declared permission catalog, kept minimal (AD #34). Each entity has <entity>.view and <entity>.manage (manage implies view). The special keys are: one key per Settings page (AD #41, since 2026-10-30: settings.users.manage, settings.roles.manage, and one each for account tags, contact tags, lead tags and email templates); capture.use (the capture app); email.manage (your own mailbox only); price.publish; quote.approve_sub_floor. The database stores only which role holds which key, with no scope (AD #37). A key reaches the records of the holder and of everyone below them in the reporting line. An entity’s <entity>.all key (lead.all, account.all, …) reaches every record. F5-l dropped the scope column FS-6 had shipped. /me returns the user’s effective keys, and the frontend’s PermissionResolver hides or disables UI to match. The minimal catalog was decided 2026-09-24 and built by F5-k (done). |
| Ownership & sharing | Each lead, account, deal and quote has one owner and can be shared with colleagues; a share widens who can see a record, never what they may do with it. One visibility rule serves both lists and single records (AD #35). Decided 2026-09-24; built by F5-f (done 2026-10-04). |
| Audit | Every write and every security event (sign-in, sign-out, deactivation, role changes, sharing, exports) is recorded in one audit_event table, in the same transaction as the change (AD #36). Decided 2026-09-24; built by F39 (done). |
| Golden rule | Code asks “can the user do X?” by permission name, never “is the user an admin?”. Who holds a permission is configuration, not code (AD #26). |
Folder structure
Frontend (forge-et-fe & forge-et-pwa) — one package (no workspace), laid out src/{app, features, ui, lib}:
src/
app/ composition root: router, app layout, auth gate, providers, main.tsx
features/ one folder per capability (accounts/ auth/ dashboard/ ...)
ui/ the design system
components/ (Button, Modal, Tabs, ...)
fields/ (config-driven form fields)
icons/ (lucide registry + Icon)
overlays/ permissions/ styles/ (tokens)
lib/ cross-cutting, framework-agnostic
api/ (the HTTP client)
session/ (session store + useSession)
test/ shared test setup
e2e/ Playwright: seam/ browser/ fixtures/
Import rule: a feature may use ui and lib but not another feature or app; lib is a leaf (depends on nothing above it). Enforced by dependency-cruiser.
Backend (forge-et-be) — one Gradle module, feature-first packages under com.empireteas.<capability>, layered inside each:
com.empireteas/
platform/ the shared substrate: config, web, error, persistence,
query, time (as-of clock), async, messaging, idempotency,
scheduling, storage, scan, observability, access
auth/ identity, role, access, config, web, service, stub, catalog
pricing/ (weekly price build-ups)
quote/ attachment/ ... (grows per feature)
each capability: web / service / repository layers (enforced by ArchUnit)
One Postgres schema (public), one Flyway location. No core/tea module split (that was collapsed in AD #31 — see decisions).
Hosting & infrastructure
| Layer | How it’s hosted |
|---|---|
| Both frontends | Static bundles on S3 + CloudFront (each at its own URL, TLS via ACM). No server. CI = build → S3 sync → CloudFront invalidation. Build-time config via GitHub Actions variables (non-secret only — the bundle is public). |
| Backend | The only container service: ECS Fargate behind an ALB. Secrets via task-definition references → AWS Secrets Manager; AWS access via the task IAM role (no static keys). |
| Data & jobs | RDS PostgreSQL · SQS (background jobs) · S3 (attachments) · SES (system mail; the capture app sends none — AD #42) · EventBridge Scheduler (all timed work — never in-process @Scheduled, so multi-task deploys don’t double-fire). |
| AI | Amazon Bedrock, called from the account in us-east-1, through each model’s inference profile (ai-provider-strategy.md §4b). |
| Everything | All infrastructure is Terraform-managed. A temporary UAT environment is a terraform apply/destroy, one instance kept from Phase 1’s acceptance round to the end of Phase 2’s. |
Local dev needs none of AWS: docker compose up -d gives Postgres + LocalStack (fake AWS), and ./gradlew bootRun runs the backend on the local profile.
The AI layer
Claude is called from the backend (never the browser) behind an AIProvider interface, served via Amazon Bedrock in the project’s own AWS account (one vendor, one bill, in-account data governance).
- Models: Claude Haiku 4.5 for high-volume/simple work (card reading, extraction, triage); Claude Sonnet 5.5 for complex synthesis (briefings, drafting). Haiku 5.5 replaces Haiku 4.5 once it reaches Bedrock. That is the design; until AWS lifts the new-account limits on Empire Teas’ account, Haiku 4.5 runs every AI feature in every environment, set per feature in configuration (
ai-provider-strategy.md§5 row 10). - Human-in-the-loop is structural: the AI layer holds no permission. AI runs on its own for read-only signals (lead scoring, inquiry extraction, briefings). Anything outward-facing (sending an email, committing a draft) is an action a person performs — the AI only assists.
- Per-feature switch: each AI feature has a
{model, enabled}runtime config. An outage degrades to the manual path.
Locked decisions worth knowing
These are settled (“do not reverse”) and shape how you build. The full list is in the project CLAUDE.md Architecture Decisions table.
-
Single backend module, feature-first packages (AD #31) — the earlier core/tea split was collapsed; new code goes in
com.empireteas.<capability>with web/service/repository layers. -
Microsoft-only login (AD #28) — no Google, no local passwords; a stub for local/CI.
-
Configurable roles on a minimal code catalog (AD #30/#32, refined by AD #34 and AD #41). There are no predefined roles and no superadmin. One Flyway migration seeds an editable IT Admin role and one user in every environment, and Empire’s administrator builds every other role. Each user has one role. Each entity has view and manage keys, plus a few special keys and one key per Settings page. Permission keys are code; grants are data. AI is not a grantable level. (The seeded IT Admin and the minimal catalog are built by F5-k.)
-
One owner per record, plus shares (AD #35) — one visibility rule for lists and single records; a share widens reach, never authority. (Built by F5-f.)
-
One audit trail (AD #36) — every write and security event, in the same transaction as the change. (Built by F39.)
-
Effective-dated prices & costs (AD #14): a row is never updated in place. There are two exceptions:
- a cost row starting today or later is deleted when a new cost from that date replaces it (F26-b FR-W4);
- a published price starting today or later can be withdrawn: its status becomes
withdrawn, and its figures and validity stay unchanged (F26-f FR-10).
Price history and as-of quoting are built in. One price per Buying Standard per week; the price is a four-figure build-up (LKR → +overhead → USD → +margin → final USD).
-
No products catalog — the Buying Standard is the sellable record for both bulk and private-label.
-
Provider seams —
AIProvider,MailboxProvider(Microsoft Graph),ErpHandoffService(manual in V1),SearchProvider(lead research) — swap an implementation, not a rewrite. -
All timed work via EventBridge → SQS → worker (AD #12) — never in-process schedulers, so scaling doesn’t double-fire buyer emails.
-
Dependency-vuln gate: Trivy (AD #27) in all three app repos, for HIGH and CRITICAL findings. It reports, without failing, on every ready PR,
release/*push, manual run and nightly run. The dev deploy runs no scan; ECR scans each dev image on push. A UAT or production release stops on an open finding that has no exception (AD #38).
Forge delivery & review model
Features run through a fixed pipeline. Review effort is deliberately front-loaded into spec and plan, because a wrong plan produces wrong code no amount of code review can efficiently fix. (The full explainer is forge-deliver-explained.md.)
The pipeline: Spec → Plan → Implement → Check → Review → Ship → Reflect. Bigger features are broken into work items shipped in waves (one PR per wave per repo, straight to main). Each wave is a vertical slice you can verify end-to-end.
Who reviews what:
| Artifact | Reviewer |
|---|---|
| Specs and plans | /forge-spec-review or /forge-plan-review; the developer who runs it approves, the author included (no teammate’s approval needed) |
| Code diff | Verified against spec + plan (lighter — upstream gates did the hard work) |
The gates:
- Mandatory: spec reviewed & approved before planning; plan reviewed & approved before coding; lint + tests + build pass; diff reviewed against spec + plan.
- Enforced at merge: branch protection on
mainrequires a pull request and green required checks (Fast lane,Slow lane,Test record,Forge reviewin each app repo). It blocks force-push and deletion. No approval is required for now;release/*still requires one Code Owner approval. - Automated helpers:
/forge-pre-pr-reviewreviews the diff adversarially./forge-review-pr <repo>#<N>reviews an open PR against the framework, and/forge-deliverruns it on every app-repo PR. Both are tools that inform the human review./forge-review-pralso writes the PR’s review record: aForge reviewstatus on the head. That status is a required check in all three app repos, so a PR with no record cannot be merged (.claude/rules/review-record.md). - Recommended: security scan for auth/data endpoints. (Browser QA,
pnpm e2e:gate, runs every night onmainin both frontends, and on a PR intorelease/*; a PR intomainruns none.)
Key point on merging: /forge-review-pr is mandatory on every app-repo PR into main or release/*, and it writes the review record that PR needs. Human review effort goes where it matters most, into the specs and plans (the table above). No approval is currently required to merge into main, so the author may merge their own PR once the required checks pass (see Enforced at merge above).
Sources. Compiled from the live forge-et-be, forge-et-fe and forge-et-pwa repositories on 2026-09-18. Anything version- or environment-specific was true at that time; the code is the source of truth — re-check there if something looks off. Full detail lives in each repo’s CLAUDE.md and the project .forge/ docs.