# jay-withers/market-agent architecture

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

- Interactive diagram: https://gitdiagram.com/jay-withers/market-agent
- Repository: https://github.com/jay-withers/market-agent

## Overview

MarketAgent is a paper-trading and investment-research platform: scheduled jobs gather news and market data, an LLM recommends actions, deterministic risk checks constrain them, and approved orders go to Alpaca’s paper account. Separate jobs synchronize broker state, report performance against benchmarks, and produce weekly reviews. The read-only API serves the dashboard’s portfolio, history, decisions, and activity views. The README documents these major workflows; sampled source confirms API/query boundaries and selected storage, broker, and review behavior, but does not expose every job’s call wiring.

Main entry points: [`apps/marketagent/src/marketagent/jobs/agent.py`](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/jobs/agent.py) (Agent workflow), [`apps/dashboard/src/App.tsx`](https://github.com/jay-withers/market-agent/blob/main/apps/dashboard/src/App.tsx) (Dashboard app), [`apps/marketagent/src/marketagent/jobs/summary.py`](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/jobs/summary.py) (Daily summary), [`apps/marketagent/src/marketagent/jobs/weekly.py`](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/jobs/weekly.py) (Weekly review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_trading["Research and trading"]
  node_agent_job["Agent workflow<br/>[agent.py]"]
  node_news["News research<br/>[news.py]"]
  node_market_data["Market data<br/>[marketdata.py]"]
  node_llm["LLM analysis"]
  node_risk["Risk engine<br/>[risk.py]"]
  node_broker_client["Broker adapter<br/>[alpaca.py]"]
  node_sync_job["Account sync<br/>[sync.py]"]
end

subgraph group_reporting["Reporting and review"]
  node_summary_job["Daily summary<br/>[summary.py]"]
  node_benchmarks["Benchmarks<br/>[benchmarks.py]"]
  node_weekly_job["Weekly review<br/>[weekly.py]"]
  node_mailer["Email delivery<br/>[mailer.py]"]
end

subgraph group_read_api["Read API"]
  node_api_app["Read-only API<br/>[main.py]"]
  node_portfolio_routes["Portfolio routes<br/>[portfolio.py]"]
  node_decision_routes["Decision routes<br/>[decisions.py]"]
  node_activity_routes["Activity routes<br/>[activity.py]"]
  node_queries["Read queries<br/>[queries.py]"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_app["Dashboard app<br/>[App.tsx]"]
  node_dashboard_api["Dashboard API client<br/>[api.ts]"]
  node_tables["Portfolio tables<br/>[Tables.tsx]"]
  node_performance_chart["Performance chart"]
  node_price_trends["Price trends<br/>[PriceTrends.tsx]"]
  node_compare["Account comparison<br/>[Compare.tsx]"]
  node_review_view["Weekly review view<br/>[Review.tsx]"]
end

node_scheduler(("Job scheduler"))
node_alpaca["Alpaca paper account"]
node_database[("Application database")]
node_news_service["Financial news sources"]
node_market_service["Market data sources"]
node_llm_service["DeepSeek service"]
node_email_service["Email provider"]
node_user(("Dashboard user"))

node_scheduler -->|"schedules"| node_agent_job
node_scheduler -->|"schedules"| node_sync_job
node_scheduler -->|"schedules"| node_summary_job
node_scheduler -->|"schedules"| node_weekly_job
node_agent_job -->|"fetches research"| node_news
node_agent_job -->|"fetches prices"| node_market_data
node_agent_job -->|"requests analysis"| node_llm
node_agent_job -->|"checks recommendations"| node_risk
node_agent_job -->|"submits approved orders"| node_broker_client
node_agent_job -->|"records run and decisions"| node_database
node_news -->|"retrieves articles"| node_news_service
node_market_data -->|"retrieves prices"| node_market_service
node_llm -->|"requests completion"| node_llm_service
node_broker_client -->|"places and reads orders"| node_alpaca
node_sync_job -->|"reads account snapshot"| node_broker_client
node_sync_job -->|"stores account state"| node_database
node_summary_job -->|"reconciles fills"| node_broker_client
node_summary_job -->|"compares performance"| node_benchmarks
node_summary_job -->|"reads and records summary"| node_database
node_summary_job -->|"sends summary"| node_mailer
node_benchmarks -.->|"uses price history"| node_market_data
node_weekly_job -->|"reads metrics and stores review"| node_database
node_weekly_job -->|"requests review"| node_llm
node_weekly_job -->|"sends review"| node_mailer
node_mailer -->|"delivers email"| node_email_service
node_api_app -->|"mounts routes"| node_portfolio_routes
node_api_app -->|"mounts routes"| node_decision_routes
node_api_app -->|"mounts routes"| node_activity_routes
node_portfolio_routes -->|"requests portfolio data"| node_queries
node_decision_routes -->|"requests decision data"| node_queries
node_activity_routes -->|"requests activity data"| node_queries
node_queries -->|"reads"| node_database
node_user -->|"views"| node_dashboard_app
node_dashboard_app -->|"requests dashboard data"| node_dashboard_api
node_dashboard_api -->|"calls GET endpoints"| node_api_app
node_dashboard_app -->|"renders tables"| node_tables
node_dashboard_app -->|"renders performance"| node_performance_chart
node_dashboard_app -->|"renders price history"| node_price_trends
node_dashboard_app -->|"renders comparisons"| node_compare
node_dashboard_app -->|"renders weekly review"| node_review_view

click node_agent_job "https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/jobs/agent.py"
click node_news "https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/news.py"
click node_market_data "https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/marketdata.py"
click node_llm "https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/llm/deepseek_provider.py"
click node_risk "https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/risk.py"
click node_broker_client "https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/broker/alpaca.py"
click node_sync_job "https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/sync.py"
click node_summary_job "https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/jobs/summary.py"
click node_benchmarks "https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/benchmarks.py"
click node_weekly_job "https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/jobs/weekly.py"
click node_mailer "https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/mailer.py"
click node_api_app "https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/api/main.py"
click node_portfolio_routes "https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/api/routers/portfolio.py"
click node_decision_routes "https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/api/routers/decisions.py"
click node_activity_routes "https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/api/routers/activity.py"
click node_queries "https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/queries.py"
click node_dashboard_app "https://github.com/jay-withers/market-agent/blob/main/apps/dashboard/src/App.tsx"
click node_dashboard_api "https://github.com/jay-withers/market-agent/blob/main/apps/dashboard/src/api.ts"
click node_tables "https://github.com/jay-withers/market-agent/blob/main/apps/dashboard/src/components/Tables.tsx"
click node_performance_chart "https://github.com/jay-withers/market-agent/blob/main/apps/dashboard/src/components/PerformanceChart.tsx"
click node_price_trends "https://github.com/jay-withers/market-agent/blob/main/apps/dashboard/src/components/PriceTrends.tsx"
click node_compare "https://github.com/jay-withers/market-agent/blob/main/apps/dashboard/src/components/Compare.tsx"
click node_review_view "https://github.com/jay-withers/market-agent/blob/main/apps/dashboard/src/components/Review.tsx"

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_agent_job,node_news,node_market_data,node_llm,node_risk,node_broker_client,node_sync_job,node_user toneBlue
class node_summary_job,node_benchmarks,node_weekly_job,node_mailer,node_database toneAmber
class node_api_app,node_portfolio_routes,node_decision_routes,node_activity_routes,node_queries toneMint
class node_dashboard_app,node_dashboard_api,node_tables,node_performance_chart,node_price_trends,node_compare,node_review_view,node_scheduler toneRose
class node_alpaca,node_news_service,node_market_service,node_llm_service,node_email_service toneIndigo
```

## Components

### Research and trading

- [Agent workflow](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/jobs/agent.py): `apps/marketagent/src/marketagent/jobs/agent.py`
- [News research](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/news.py): `apps/marketagent/src/marketagent/news.py`
- [Market data](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/marketdata.py): `apps/marketagent/src/marketagent/marketdata.py`
- [LLM analysis](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/llm/deepseek_provider.py): `apps/marketagent/src/marketagent/llm/deepseek_provider.py`
- [Risk engine](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/risk.py): `apps/marketagent/src/marketagent/risk.py`
- [Broker adapter](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/broker/alpaca.py): `apps/marketagent/src/marketagent/broker/alpaca.py`
- [Account sync](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/sync.py): `apps/marketagent/src/marketagent/sync.py`

### Reporting and review

- [Daily summary](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/jobs/summary.py): `apps/marketagent/src/marketagent/jobs/summary.py`
- [Benchmarks](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/benchmarks.py): `apps/marketagent/src/marketagent/benchmarks.py`
- [Weekly review](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/jobs/weekly.py): `apps/marketagent/src/marketagent/jobs/weekly.py`
- [Email delivery](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/mailer.py): `apps/marketagent/src/marketagent/mailer.py`

### Read API

- [Read-only API](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/api/main.py): `apps/marketagent/src/marketagent/api/main.py`
- [Portfolio routes](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/api/routers/portfolio.py): `apps/marketagent/src/marketagent/api/routers/portfolio.py`
- [Decision routes](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/api/routers/decisions.py): `apps/marketagent/src/marketagent/api/routers/decisions.py`
- [Activity routes](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/api/routers/activity.py): `apps/marketagent/src/marketagent/api/routers/activity.py`
- [Read queries](https://github.com/jay-withers/market-agent/blob/main/apps/marketagent/src/marketagent/queries.py): `apps/marketagent/src/marketagent/queries.py`

### Dashboard

- [Dashboard app](https://github.com/jay-withers/market-agent/blob/main/apps/dashboard/src/App.tsx): `apps/dashboard/src/App.tsx`
- [Dashboard API client](https://github.com/jay-withers/market-agent/blob/main/apps/dashboard/src/api.ts): `apps/dashboard/src/api.ts`
- [Portfolio tables](https://github.com/jay-withers/market-agent/blob/main/apps/dashboard/src/components/Tables.tsx): `apps/dashboard/src/components/Tables.tsx`
- [Performance chart](https://github.com/jay-withers/market-agent/blob/main/apps/dashboard/src/components/PerformanceChart.tsx): `apps/dashboard/src/components/PerformanceChart.tsx`
- [Price trends](https://github.com/jay-withers/market-agent/blob/main/apps/dashboard/src/components/PriceTrends.tsx): `apps/dashboard/src/components/PriceTrends.tsx`
- [Account comparison](https://github.com/jay-withers/market-agent/blob/main/apps/dashboard/src/components/Compare.tsx): `apps/dashboard/src/components/Compare.tsx`
- [Weekly review view](https://github.com/jay-withers/market-agent/blob/main/apps/dashboard/src/components/Review.tsx): `apps/dashboard/src/components/Review.tsx`

### Other components

- **Job scheduler**
- **Alpaca paper account**
- **Application database**
- **Financial news sources**
- **Market data sources**
- **DeepSeek service**
- **Email provider**
- **Dashboard user**

## Connections

- Job scheduler → Agent workflow: schedules
- Job scheduler → Account sync: schedules
- Job scheduler → Daily summary: schedules
- Job scheduler → Weekly review: schedules
- Agent workflow → News research: fetches research
- Agent workflow → Market data: fetches prices
- Agent workflow → LLM analysis: requests analysis
- Agent workflow → Risk engine: checks recommendations
- Agent workflow → Broker adapter: submits approved orders
- Agent workflow → Application database: records run and decisions
- News research → Financial news sources: retrieves articles
- Market data → Market data sources: retrieves prices
- LLM analysis → DeepSeek service: requests completion
- Broker adapter → Alpaca paper account: places and reads orders
- Account sync → Broker adapter: reads account snapshot
- Account sync → Application database: stores account state
- Daily summary → Broker adapter: reconciles fills
- Daily summary → Benchmarks: compares performance
- Daily summary → Application database: reads and records summary
- Daily summary → Email delivery: sends summary
- Benchmarks → Market data: uses price history
- Weekly review → Application database: reads metrics and stores review
- Weekly review → LLM analysis: requests review
- Weekly review → Email delivery: sends review
- Email delivery → Email provider: delivers email
- Read-only API → Portfolio routes: mounts routes
- Read-only API → Decision routes: mounts routes
- Read-only API → Activity routes: mounts routes
- Portfolio routes → Read queries: requests portfolio data
- Decision routes → Read queries: requests decision data
- Activity routes → Read queries: requests activity data
- Read queries → Application database: reads
- Dashboard user → Dashboard app: views
- Dashboard app → Dashboard API client: requests dashboard data
- Dashboard API client → Read-only API: calls GET endpoints
- Dashboard app → Portfolio tables: renders tables
- Dashboard app → Performance chart: renders performance
- Dashboard app → Price trends: renders price history
- Dashboard app → Account comparison: renders comparisons
- Dashboard app → Weekly review view: renders weekly review