Skip to content

Architecture

Nguyen Le edited this page Nov 15, 2026 · 8 revisions

Architecture

A thin gateway in front of five Amazon Bedrock AgentCore agents, with every calculation in a deterministic AWS Lambda over versioned S3 data.

System layers

flowchart TB
  subgraph Client["Client"]
    UI["Next.js dashboard<br/>Holdings pop-up · chat · trace"]
    CL["Your AI agent<br/>Claude · Muse · Dots"]
  end

  subgraph Gateway["Gateway"]
    API["FastAPI<br/>validates · signs · forwards"]
    MCP["MCP server<br/>submit_persona · get_persona"]
  end

  subgraph Agents["AgentCore runtimes · Strands Agents SDK"]
    O["Orchestrator"]
    IN["Intake"]
    MK["Market"]
    CF["Classifier"]
    XP["Explainer"]
  end

  subgraph Compute["Deterministic compute"]
    LA["AWS Lambda<br/>financial-tools · Python 3.12"]
  end

  subgraph Data["Data"]
    S3D[("S3 · market data<br/>versioned · checksummed")]
    S3I[("S3 · investor record")]
  end

  BR["Amazon Bedrock<br/>Nova Lite"]

  UI --> API
  CL -->|MCP| MCP --> API
  API -->|"every call"| O
  O --> IN & MK & CF & XP
  IN <--> S3I
  MK --> LA
  CF --> LA
  LA --> S3D
  XP --> BR
  O --> BR
Loading

Request path: a Buy or Sell click

sequenceDiagram
  actor You
  participant UI as Dashboard
  participant API as FastAPI
  participant O as Orchestrator
  participant IN as Intake
  participant MK as Market
  participant CF as Classifier
  participant XP as Explainer

  You->>UI: Sell NVDA
  UI->>API: GET /api/trade-check/NVDA
  API->>O: trade_check (signed, AgentCore)
  par independent steps
    O->>IN: who is asking?
    IN-->>O: persona + risk band
  and
    O->>MK: what changed?
    MK-->>O: market change + evidence IDs
  end
  O->>CF: classify (band, growth style)
  CF-->>O: verdict, scores, evidence
  O->>XP: explain
  XP-->>O: pop-up title + chat detail
  O-->>API: verdict + trace (with runtime names)
  API-->>UI: render pop-up
Loading

Market and Classifier also preload on Refresh market, so on a click both steps are usually cache hits.

Design principles

Principle Mechanism
Models never calculate Verdicts and every figure come from Lambda; agents return their tool's output, not the model's text
One entry point The gateway forwards every action to the Orchestrator, which routes by action to the owning agent
Validated language Generated text is rejected if it contains digits, predictions, advice or uncited evidence, and falls back to fixed wording
Reproducible data Market data is versioned in S3 and verified against a SHA-256 manifest on every load
Stateless gateway The "market refreshed" flag travels with each request; the server keeps no market state
Least privilege Separate IAM roles for the specialists and the Orchestrator, scoped to the exact S3 keys, Lambda and model they use

Deployment

Piece Detail
Region us-east-1
Agents Five AgentCore code-upload runtimes (Python 3.12, ARM64), stack portfolioguard-workshop-agentcore-agents
Calculations Lambda portfolioguard-workshop-financial-tools (Python 3.12, ARM64, 512 MB, 120 s)
Data Private, encrypted, versioned S3 bucket: market data, starter dataset, investor records, agent packages
Model Amazon Nova Lite through the Bedrock Converse API
Infrastructure as code AWS SAM / CloudFormation, deployed through reviewed change sets

Status

  • Built and deployed: gateway, five agents, Lambda, S3 data, persona-aware verdicts, preloading
  • Not enabled: the AgentCore observability dashboard (traces and token cost); the in-app execution trace works today

See Agents for the agents in detail and Trade Check for the scoring.

Clone this wiki locally