# ecarlsson-r/quoteplot-agent architecture

> Architecture diagram of the GitHub repository ecarlsson-r/quoteplot-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ecarlsson-r/quoteplot-agent
- Repository: https://github.com/ecarlsson-r/quoteplot-agent

## Overview

QuotePlot Agent combines Lucy’s evidence-gathering crypto investigations with a separate browser wallet workspace for testnet token management. The principal flow is a natural-language question through the Angular Lucy panel and FastAPI agent router, which gathers market, machine-learning, web, and on-chain evidence before returning a narrated or deterministic result. A separate scheduled backend maintains market and alternative-data inputs. The wallet workspace reads factory inventory and events and supports token actions through a connected wallet. Some backend internals and unsampled UI modules are represented only at the directory level; documented relationships are cited to the README.

Main entry points: [`backend/routers/agent.py`](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/routers/agent.py) (Evidence Gathering), [`frontend/src/app/app.ts`](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/app.ts) (Angular App), [`frontend/src/app/services/seed-token-factory.service.ts`](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/services/seed-token-factory.service.ts) (Factory Service), [`frontend/src/app/components/token-list/token-list.component.ts`](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/components/token-list/token-list.component.ts) (Token Inventory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Angular Client"]
  node_app["Angular App<br/>[app.ts]"]
  node_lucy_panel["Lucy Panel"]
  node_market_panel["Market Panel"]
  node_lucy_service["Lucy Service<br/>[lucy.service.ts]"]
  node_market_service["Market Service<br/>[market.service.ts]"]
  node_backend_url["Backend URL<br/>[backend-url.ts]"]
end

subgraph group_agent["Lucy Investigation"]
  node_agent_router["Agent API<br/>[agent.py]"]
  node_investigation["Evidence Gathering<br/>[agent.py]"]
  node_gemini["Gemini Narration<br/>[agent.py]"]
  node_market_router["Market API<br/>[market.py]"]
  node_web_research["Bright Data"]
  node_chain_evidence["Chain Evidence"]
  node_ethereum_reader["Ethereum Reader<br/>[ethereum.py]"]
end

subgraph group_data["Data and Analysis"]
  node_scheduler["Background Jobs<br/>[tasks.py]"]
  node_brain["Market Analysis<br/>[brain.py]"]
  node_market_store[("Market Database<br/>[database.py]")]
  node_data_models["Data Models<br/>[models.py]"]
  node_ml_methods["ML Methods"]
end

subgraph group_wallet["Token Workspace"]
  node_token_list["Token Inventory"]
  node_factory_service["Factory Service"]
  node_provider_service["Wallet Provider"]
  node_new_token["Token Creation"]
  node_event_list["Factory Events"]
end

subgraph group_contracts["EVM Contracts"]
  node_factory_abi["Factory ABI"]
  node_token_abi["Token ABI<br/>[seed-token.abi.ts]"]
  node_testnet{{"Testnet Contracts"}}
end

node_researcher(("Researcher"))
node_user_wallet(("Connected Wallet"))
node_database[("Configured Database")]
node_brightdata_service["Bright Data Services"]
node_gemini_service["Gemini"]
node_ethereum_rpc["Ethereum JSON-RPC"]
node_testnet_rpc["Testnet RPC"]

node_researcher -->|"uses"| node_app
node_app -->|"displays"| node_lucy_panel
node_app -->|"displays"| node_market_panel
node_lucy_panel -->|"requests"| node_lucy_service
node_market_panel -->|"requests"| node_market_service
node_lucy_service -->|"resolves endpoint"| node_backend_url
node_market_service -->|"resolves endpoint"| node_backend_url
node_lucy_service -->|"sends requests"| node_agent_router
node_market_service -->|"sends requests"| node_market_router
node_agent_router -->|"orchestrates"| node_investigation
node_investigation -->|"analyzes market"| node_brain
node_investigation -->|"collects context"| node_web_research
node_investigation -->|"resolves token"| node_chain_evidence
node_chain_evidence -->|"reads chain data"| node_ethereum_reader
node_investigation -->|"narrates evidence"| node_gemini
node_investigation -->|"reads market data"| node_database
node_investigation -.->|"requests web context"| node_brightdata_service
node_gemini -->|"uses"| node_gemini_service
node_ethereum_reader -->|"reads"| node_ethereum_rpc
node_market_router -->|"queries"| node_market_store
node_market_store -->|"persists"| node_data_models
node_scheduler -->|"updates"| node_market_store
node_scheduler -.->|"evaluates predictions"| node_brain
node_brain -.->|"uses analysis methods"| node_ml_methods
node_app -->|"displays"| node_token_list
node_app -->|"displays"| node_event_list
node_app -->|"displays"| node_new_token
node_token_list -->|"loads inventory"| node_factory_service
node_event_list -->|"loads events"| node_factory_service
node_new_token -->|"creates token"| node_factory_service
node_provider_service -->|"configures provider"| node_factory_service
node_factory_service -->|"encodes calls"| node_factory_abi
node_token_list -->|"uses token interface"| node_token_abi
node_factory_service -->|"connects factory"| node_testnet
node_user_wallet -->|"connects"| node_provider_service
node_provider_service -->|"reads network"| node_testnet_rpc
node_new_token -->|"submits transaction"| node_testnet
node_token_list -->|"manages tokens"| node_testnet

click node_app "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/app.ts"
click node_lucy_panel "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/components/lucy-panel/lucy-panel.component.ts"
click node_market_panel "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/components/market-panel/market-panel.component.ts"
click node_lucy_service "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/services/lucy.service.ts"
click node_market_service "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/services/market.service.ts"
click node_backend_url "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/services/backend-url.ts"
click node_agent_router "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/routers/agent.py"
click node_investigation "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/routers/agent.py"
click node_gemini "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/routers/agent.py"
click node_market_router "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/routers/market.py"
click node_scheduler "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/tasks.py"
click node_brain "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/brain.py"
click node_market_store "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/database.py"
click node_data_models "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/models.py"
click node_ml_methods "https://github.com/ecarlsson-r/quoteplot-agent/tree/main/dm"
click node_web_research "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/brightdata_utils.py"
click node_chain_evidence "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/blockchain/token_intelligence.py"
click node_ethereum_reader "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/blockchain/ethereum.py"
click node_token_list "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/components/token-list/token-list.component.ts"
click node_factory_service "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/services/seed-token-factory.service.ts"
click node_provider_service "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/services/provider.service.ts"
click node_new_token "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/components/new-token/new-token.component.ts"
click node_event_list "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/components/event-list/event-list.component.ts"
click node_factory_abi "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/contracts/seed-token-factory.abi.ts"
click node_token_abi "https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/contracts/seed-token.abi.ts"
click node_testnet "https://github.com/ecarlsson-r/quoteplot-agent/tree/main/contracts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_lucy_panel,node_market_panel,node_lucy_service,node_market_service,node_backend_url toneBlue
class node_agent_router,node_investigation,node_gemini,node_market_router,node_web_research,node_chain_evidence,node_ethereum_reader,node_database toneAmber
class node_scheduler,node_brain,node_market_store,node_data_models,node_ml_methods toneMint
class node_token_list,node_factory_service,node_provider_service,node_new_token,node_event_list toneRose
class node_factory_abi,node_token_abi,node_testnet,node_researcher,node_user_wallet,node_brightdata_service,node_gemini_service,node_ethereum_rpc,node_testnet_rpc toneIndigo
```

## Components

### Angular Client

- [Angular App](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/app.ts): `frontend/src/app/app.ts`
- [Lucy Panel](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/components/lucy-panel/lucy-panel.component.ts): `frontend/src/app/components/lucy-panel/lucy-panel.component.ts`
- [Market Panel](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/components/market-panel/market-panel.component.ts): `frontend/src/app/components/market-panel/market-panel.component.ts`
- [Lucy Service](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/services/lucy.service.ts): `frontend/src/app/services/lucy.service.ts`
- [Market Service](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/services/market.service.ts): `frontend/src/app/services/market.service.ts`
- [Backend URL](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/services/backend-url.ts): `frontend/src/app/services/backend-url.ts`

### Lucy Investigation

- [Agent API](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/routers/agent.py): `backend/routers/agent.py`
- [Evidence Gathering](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/routers/agent.py): `backend/routers/agent.py`
- [Gemini Narration](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/routers/agent.py): `backend/routers/agent.py`
- [Market API](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/routers/market.py): `backend/routers/market.py`
- [Bright Data](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/brightdata_utils.py): `backend/brightdata_utils.py`
- [Chain Evidence](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/blockchain/token_intelligence.py): `backend/blockchain/token_intelligence.py`
- [Ethereum Reader](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/blockchain/ethereum.py): `backend/blockchain/ethereum.py`

### Data and Analysis

- [Background Jobs](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/tasks.py): `backend/tasks.py`
- [Market Analysis](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/brain.py): `backend/brain.py`
- [Market Database](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/database.py): `backend/database.py`
- [Data Models](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/backend/models.py): `backend/models.py`
- [ML Methods](https://github.com/ecarlsson-r/quoteplot-agent/tree/main/dm): `dm`

### Token Workspace

- [Token Inventory](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/components/token-list/token-list.component.ts): `frontend/src/app/components/token-list/token-list.component.ts`
- [Factory Service](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/services/seed-token-factory.service.ts): `frontend/src/app/services/seed-token-factory.service.ts`
- [Wallet Provider](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/services/provider.service.ts): `frontend/src/app/services/provider.service.ts`
- [Token Creation](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/components/new-token/new-token.component.ts): `frontend/src/app/components/new-token/new-token.component.ts`
- [Factory Events](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/components/event-list/event-list.component.ts): `frontend/src/app/components/event-list/event-list.component.ts`

### EVM Contracts

- [Factory ABI](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/contracts/seed-token-factory.abi.ts): `frontend/src/app/contracts/seed-token-factory.abi.ts`
- [Token ABI](https://github.com/ecarlsson-r/quoteplot-agent/blob/main/frontend/src/app/contracts/seed-token.abi.ts): `frontend/src/app/contracts/seed-token.abi.ts`
- [Testnet Contracts](https://github.com/ecarlsson-r/quoteplot-agent/tree/main/contracts): `contracts`

### Other components

- **Researcher**
- **Connected Wallet**
- **Configured Database**
- **Bright Data Services**
- **Gemini**
- **Ethereum JSON-RPC**
- **Testnet RPC**

## Connections

- Researcher → Angular App: uses (evidence: `README.md`)
- Angular App → Lucy Panel: displays (evidence: `frontend/src/app/app.ts`)
- Angular App → Market Panel: displays (evidence: `frontend/src/app/app.ts`)
- Lucy Panel → Lucy Service: requests (evidence: `frontend/src/app/components/lucy-panel/lucy-panel.component.ts`)
- Market Panel → Market Service: requests (evidence: `frontend/src/app/components/market-panel/market-panel.component.ts`)
- Lucy Service → Backend URL: resolves endpoint (evidence: `frontend/src/app/services/lucy.service.ts`)
- Market Service → Backend URL: resolves endpoint (evidence: `frontend/src/app/services/market.service.ts`)
- Lucy Service → Agent API: sends requests (evidence: `README.md`)
- Market Service → Market API: sends requests (evidence: `README.md`)
- Agent API → Evidence Gathering: orchestrates (evidence: `README.md`)
- Evidence Gathering → Market Analysis: analyzes market (evidence: `README.md`)
- Evidence Gathering → Bright Data: collects context (evidence: `backend/routers/agent.py`)
- Evidence Gathering → Chain Evidence: resolves token (evidence: `backend/routers/agent.py`)
- Chain Evidence → Ethereum Reader: reads chain data (evidence: `backend/blockchain/token_intelligence.py`)
- Evidence Gathering → Gemini Narration: narrates evidence (evidence: `README.md`)
- Evidence Gathering → Configured Database: reads market data (evidence: `README.md`)
- Evidence Gathering → Bright Data Services: requests web context (evidence: `README.md`)
- Gemini Narration → Gemini: uses (evidence: `README.md`)
- Ethereum Reader → Ethereum JSON-RPC: reads (evidence: `README.md`)
- Market API → Market Database: queries (evidence: `backend/routers/market.py`)
- Market Database → Data Models: persists (evidence: `backend/database.py`)
- Background Jobs → Market Database: updates (evidence: `backend/tasks.py`)
- Background Jobs → Market Analysis: evaluates predictions (evidence: `backend/tasks.py`)
- Market Analysis → ML Methods: uses analysis methods
- Angular App → Token Inventory: displays (evidence: `frontend/src/app/app.ts`)
- Angular App → Factory Events: displays (evidence: `frontend/src/app/app.ts`)
- Angular App → Token Creation: displays (evidence: `frontend/src/app/app.ts`)
- Token Inventory → Factory Service: loads inventory (evidence: `frontend/src/app/components/token-list/token-list.component.ts`)
- Factory Events → Factory Service: loads events (evidence: `frontend/src/app/components/event-list/event-list.component.ts`)
- Token Creation → Factory Service: creates token (evidence: `frontend/src/app/components/new-token/new-token.component.ts`)
- Wallet Provider → Factory Service: configures provider (evidence: `frontend/src/app/services/provider.service.ts`)
- Factory Service → Factory ABI: encodes calls (evidence: `frontend/src/app/services/seed-token-factory.service.ts`)
- Token Inventory → Token ABI: uses token interface (evidence: `frontend/src/app/components/token-list/token-list.component.ts`)
- Factory Service → Testnet Contracts: connects factory (evidence: `README.md`)
- Connected Wallet → Wallet Provider: connects (evidence: `README.md`)
- Wallet Provider → Testnet RPC: reads network (evidence: `README.md`)
- Token Creation → Testnet Contracts: submits transaction (evidence: `README.md`)
- Token Inventory → Testnet Contracts: manages tokens (evidence: `README.md`)
