This document describes the current implementation of ArchReviewAgent from a TOGAF-style layered architecture perspective. It focuses on the four primary TOGAF architecture domains:

• Business Architecture
• Application Architecture
• Data Architecture
• Technology Architecture

It also includes cross-cutting security controls, runtime flow diagrams, and a pragmatic gap assessment for the next architecture increment.

For the future-state design for configurable guardrails beyond the current two-rule implementation, see docs/extensible-guardrail-architecture.md.

ArchReviewAgent is a procurement-oriented vendor assessment application. A user enters a company or product name, and the system performs a security-analyst-style review focused on two enterprise guardrails:

• EU data residency
• Enterprise deployment

Alongside the guardrail verdict, the system also produces a short factual product-context summary that explains what the vendor or product actually does.

The solution is implemented as a single web application with:

• a React single-page frontend
• a Node.js + Express backend
• a staged OpenAI Agents SDK workflow for intake, retrieval, decisioning, and presentation
• a Postgres-backed server-side cache for vendor resolutions, accepted report snapshots, and evidence metadata
• a stale-while-revalidate refresh pattern for cache hits
• browser-local conversation history persisted in localStorage

The current production shape is a single deployable web service that can serve both:

• the API
• the built frontend assets

The key architectural choice is separation of concerns in the backend pipeline:

1. Vendor intake and normalization
2. Vendor context and evidence retrieval
3. Structured decisioning
4. Final report presentation

This is materially better than a single free-form agent because it improves:

• consistency
• testability
• guardrail enforcement
• diagnosability

flowchart TB
  subgraph B["Business Architecture"]
    B1["Capability: Third-party security review"]
    B2["Outcome: Product context plus enterprise readiness recommendation"]
    B3["Actor: Analyst / procurement user"]
    B4["Policy focus: EU residency and deployment guardrails"]
  end

  subgraph A["Application Architecture"]
    A1["React research workspace"]
    A2["Express API facade"]
    A3["Research orchestrator"]
    A4["Vendor intake"]
    A5["Vendor context and evidence retrieval"]
    A6["Structured decisioning"]
    A7["Report presentation"]
    A8["Test mode report generator"]
    A9["Cache repository and promotion policy"]
  end

  subgraph D["Data Architecture"]
    D1["ResearchRequest"]
    D2["VendorResolution"]
    D3["Research memo with product context"]
    D4["ResearchDecision"]
    D5["EnterpriseReadinessReport"]
    D6["ConversationState"]
    D7["Structured research logs"]
    D8["Subject resolution cache"]
    D9["Evidence bundles and evidence items"]
    D10["Decision snapshots"]
  end

  subgraph T["Technology Architecture"]
    T1["Browser + localStorage"]
    T2["Node.js + Express"]
    T3["OpenAI Agents SDK"]
    T4["Hosted web search"]
    T5["Vendor-controlled public web"]
    T6["Vite / TypeScript toolchain"]
    T7["Postgres"]
  end

  B3 --> B1 --> B2
  B4 --> B1

  A1 --> A2 --> A3
  A3 --> A4 --> A5 --> A6 --> A7
  A2 --> A8
  A3 --> A9

  A2 -. receives .-> D1
  A4 -. produces .-> D2
  A5 -. produces .-> D3
  A6 -. produces .-> D4
  A7 -. produces .-> D5
  A1 -. persists .-> D6
  A3 -. emits .-> D7
  A9 -. persists .-> D8
  A9 -. persists .-> D9
  A9 -. persists .-> D10

  T1 --> A1
  T2 --> A2
  T2 --> A3
  T2 --> A9
  T3 --> A4
  T3 --> A5
  T3 --> A6
  T4 --> A5
  T5 --> T4
  T6 --> A1
  T6 --> A2
  T7 --> A9

The business goal is to reduce procurement risk when evaluating third-party software products. The application supports a lightweight but structured security review before enterprise adoption.

flowchart LR
  U["Analyst"] --> P1["Submit vendor name"]
  P1 --> P2["Resolve vendor identity"]
  P2 --> P3["Establish what the product does"]
  P3 --> P4["Search official vendor evidence"]
  P4 --> P5["Evaluate EU residency and deployment"]
  P5 --> P6["Produce product context, recommendation, and confidence"]
  P6 --> P7["Persist conversation in browser history"]

• Only two business guardrails are currently in scope.
• unknown should only be used when the evidence is genuinely too thin.
• Vendor evidence should come from official vendor-controlled domains.
• EU transfer-law language is not equivalent to EU residency support.
• Product context should be factual and grounded in vendor-controlled descriptions, not marketing paraphrase.
• The system should expose evidence and unanswered questions, not only a color verdict.

flowchart LR
  UI["React UI"] -->|"POST /api/chat"| API["Express API"]
  UI -->|"POST /api/chat/stream"| API
  UI -->|"POST /api/chat/test"| API

  API --> ORCH["Research Orchestrator"]
  API --> MOCK["Mock Report Generator"]

  ORCH --> INTAKE["Vendor Intake"]
  ORCH --> CACHE["Research Cache Repository"]
  ORCH --> RETRIEVE["Evidence Retrieval"]
  ORCH --> DECIDE["Structured Decisioning"]
  ORCH --> PRESENT["Report Presentation"]
  ORCH --> POLICY["Cache Promotion Policy"]
  ORCH --> LOG["Structured Logging"]

  INTAKE --> OPENAI["OpenAI Agents SDK"]
  RETRIEVE --> OPENAI
  DECIDE --> OPENAI
  CACHE --> DB["Postgres"]

sequenceDiagram
  actor User
  participant UI as React UI
  participant API as Express API
  participant Orch as Research Orchestrator
  participant Intake as Vendor Intake
  participant Cache as Research Cache Repository
  participant Retrieve as Retrieval
  participant OpenAI as OpenAI Platform
  participant Decide as Decisioning
  participant Present as Presentation
  participant DB as Postgres
  participant Store as Browser localStorage

  User->>UI: Enter vendor or click starter option
  UI->>API: POST /api/chat/stream
  API->>Orch: researchCompany(companyName, onProgress)
  Orch->>Intake: validateVendorInput()
  Intake->>OpenAI: Resolve canonical vendor identity
  OpenAI-->>Intake: canonicalName + officialDomains
  Orch->>Cache: loadAcceptedReportSnapshot(canonicalSubjectKey)
  Cache->>DB: read accepted bundle + decision snapshot
  alt accepted cache hit
    DB-->>Cache: accepted report snapshot
    Cache-->>Orch: cached report
    Orch-->>API: cached report
    API-->>UI: SSE result event
    UI->>Store: Persist conversation state
    Orch->>Retrieve: background refresh (stale-while-revalidate)
    Retrieve->>OpenAI: Agent run with webSearchTool
    OpenAI-->>Retrieve: Refreshed memo
    Orch->>Decide: buildDecisionFromMemo()
    Decide->>OpenAI: Structured decision request
    OpenAI-->>Decide: Structured ResearchDecision
    Orch->>Present: presentDecision()
    Orch->>Cache: compare candidate vs accepted baseline
    Cache->>DB: persist weak/accepted candidate and renew or replace baseline
  else cache miss
    Orch->>Retrieve: generateResearchMemo()
    Retrieve->>OpenAI: Agent run with webSearchTool
    OpenAI-->>Retrieve: Streamed tool and text events
    Retrieve-->>API: Progress stages
    OpenAI-->>Retrieve: Product context + evidence memo
    Orch->>Decide: buildDecisionFromMemo()
    Decide->>OpenAI: Structured decision request
    OpenAI-->>Decide: Structured ResearchDecision with product context
    Orch->>Present: presentDecision()
    Orch->>Cache: evaluate candidate and persist artifacts
    Cache->>DB: write resolution, evidence bundle, evidence items, decision snapshot
    Present-->>API: EnterpriseReadinessReport
    API-->>UI: SSE result event
    UI->>Store: Persist conversation state
  end

The frontend is a single React screen with four primary responsibilities:

• collect the target vendor name
• display what the product does before the security verdict
• display live research progress
• render the final structured report
• persist and restore conversation history in the current browser

Notable frontend behaviors:

• history is local to the browser, not server-backed
• the live path uses SSE and stages the visible progress to avoid abrupt jumps
• test mode bypasses live research and returns a static mock report
• starter vendor buttons accelerate common demo paths

The backend follows an orchestrated staged pattern instead of a monolithic agent.

This separation is important because it:

• isolates guardrails
• improves test coverage
• reduces dependence on free-form parsing
• makes failures diagnosable by stage

This staged flow is now wrapped by a server-side caching shell:

1. resolve canonical subject
2. check for a fresh accepted report snapshot by canonical subject key
3. return cached immediately when present
4. start a background refresh on cache hits
5. compare the refreshed candidate to the accepted baseline before promotion

flowchart LR
  RQ["ResearchRequest"] --> VR["VendorResolution"]
  VR --> SRC["Subject resolution cache"]
  VR --> RM["Research memo"]
  RM --> RD["ResearchDecision"]
  RD --> RP["EnterpriseReadinessReport"]
  RM --> EB["Evidence bundle"]
  RP --> DS["Decision snapshot"]
  EB --> DS
  RP --> CS["ConversationState in localStorage"]
  VR --> LG["Structured log events"]
  RM --> LG
  RD --> LG
  EB --> LG
  DS --> LG

• The server now uses Postgres for durable caching of subject resolutions, accepted report snapshots, and evidence metadata.
• The backend still keeps stage-local working data in memory for the lifetime of a request.
• The browser stores conversation history per mode in localStorage.
• The public report contract is stable and typed in shared/contracts.ts.
• Internal stage objects are stricter than the UI contract and use Zod for normalization.
• Accepted report caching is keyed by canonical subject, not the raw typed string.
• Background refresh uses a stale-while-revalidate pattern and only promotes candidates that meet minimum coverage and anti-regression rules.

• Official domains are normalized and deduplicated before retrieval.
• Retrieval is constrained to vendor-controlled domains.
• Decision evidence is normalized before being surfaced to the UI.
• The UI never receives the raw memo; it receives only the presented report.
• Invalid or prompt-like raw input is rejected before any live research.

flowchart LR
  subgraph C["Client Boundary"]
    USER["End user browser"]
    SPA["React SPA"]
    LS["Browser localStorage"]
    USER --> SPA
    SPA <--> LS
  end

  subgraph S["Application Boundary"]
    API["Express server"]
    ORCH["Research orchestrator"]
    CACHE["Cache repository + promotion policy"]
    LOG["Structured logs"]
    SPA <-->|HTTPS / SSE| API
    API --> ORCH
    ORCH --> CACHE
    ORCH --> LOG
  end

  subgraph P["Persistence Boundary"]
    DB["Postgres"]
  end

  subgraph A["External AI Boundary"]
    OAI["OpenAI model runtime"]
    WS["Hosted web search"]
  end

  subgraph V["External Evidence Boundary"]
    WEB["Vendor-controlled public websites"]
  end

  ORCH --> OAI
  ORCH --> DB
  OAI --> WS
  WS --> WEB
  CACHE --> DB

The architecture has four meaningful trust zones:

1. Browser input zone
2. Backend application zone
3. OpenAI platform zone
4. Public vendor evidence zone

The system explicitly treats the following as untrusted:

• user-supplied vendor names
• text embedded in retrieved vendor web pages
• malformed or partial model outputs

• No authentication or authorization layer
• No tenant isolation because there is no server-side user model
• No explicit encryption-at-rest policy described at the application level; relies on managed Postgres/runtime controls
• Browser localStorage history is device-local and not centrally governed
• Background refresh is in-process, not queue-backed, so it is still tied to a single app instance
• No external policy engine for enterprise control rules

• The dominant latency is external model and search work, not local compute.
• The UI mitigates latency with streamed progress stages.
• Test mode provides a near-instant UX fallback for demo and validation scenarios.
• Accepted cache hits are now near-instant compared with live research.
• Background refresh shifts freshness work off the critical request path.

• The system uses stage-level time budgeting.
• Retrieval can retry once on retryable model failures.
• Decision output is normalized and repaired when the model returns malformed JSON.
• The system returns specific user-facing error classes for common failure modes.
• Accepted baselines are retained when a refreshed candidate is weaker or thinner.

• The backend has stage-level tests for intake, retrieval, decisioning, presentation, and logging.
• The backend now also has explicit cache-promotion policy tests.
• Shared report structures reduce drift between stages.
• The application contract is centralized in shared/contracts.ts.

• The staged architecture is easier to reason about than a single large agent.
• The current codebase has a clear module boundary for each backend concern.
• The current maintenance hotspot is now around distributed background refresh and eventual worker separation, not cache correctness.

From a TOGAF perspective, the current solution is a strong MVP architecture but not yet a full enterprise platform.

• Clear separation of business workflow and application services
• Typed contracts between frontend and backend
• Stronger-than-average trust handling for user input and public evidence
• Good developer observability for a single-service app

The most natural next-state architecture would add:

• authenticated users
• server-side persistent conversation and evidence storage
• queue-backed background research jobs with polling or event updates
• richer evidence-bundle comparison and audit views
• administrative policy configuration for additional guardrails
• centralized monitoring and log aggregation

From a TOGAF viewpoint, ArchReviewAgent is currently a layered digital solution with:

• a clear business capability for third-party security review
• a modular application architecture centered on a four-stage research pipeline wrapped by a cache-and-refresh shell
• a data architecture with typed artifacts, browser-local history, and Postgres-backed accepted evidence/report caching
• a lightweight technology architecture optimized for a single deployable web service plus managed Postgres

Its strongest architectural qualities are:

• staged decomposition
• evidence-focused decisioning
• canonical-subject caching with anti-regression promotion rules
• explicit trust-boundary controls
• strong contract discipline between layers

Its main limitations are architectural scale concerns rather than code organization concerns:

• no shared persistence
• no asynchronous job backbone
• no enterprise identity or governance layer

As an MVP, the architecture is coherent and well-shaped. As an enterprise service, the next major evolution should be in persistence, identity, and asynchronous workload handling rather than another rewrite of the current layered core.