# jainamd05/marketsim architecture

> Architecture diagram of the GitHub repository jainamd05/marketsim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jainamd05/marketsim
- Repository: https://github.com/jainamd05/marketsim

## Overview

MarketSim AI turns a branching business questionnaire into an evidence-backed market analysis and strategy report. Users review a business profile, choose demo or live research, and start an analysis; backend agents gather market evidence, draft strategies, simulate financial outcomes, critique assumptions, and produce a report for dashboard exploration and zero-search-credit what-if runs. The graph follows documented workflow relationships and sampled call sites; most agent internals and several frontend-to-API call sites were not sampled, so those links rely on README statements rather than inspected implementation.

Main entry points: [`backend/app/agents/graph.py`](https://github.com/jainamd05/marketsim/blob/main/backend/app/agents/graph.py) (Agent workflow), [`backend/app/services/analysis_service.py`](https://github.com/jainamd05/marketsim/blob/main/backend/app/services/analysis_service.py) (Analysis service), [`backend/app/serpapi/gateway.py`](https://github.com/jainamd05/marketsim/blob/main/backend/app/serpapi/gateway.py) (Search gateway), [`backend/app/api/routes.py`](https://github.com/jainamd05/marketsim/blob/main/backend/app/api/routes.py) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_onboarding["Profile onboarding"]
  node_profile_review["Profile review<br/>[ReviewPage.tsx]"]
  node_dashboard["Analysis dashboard"]
  node_frontend_api["Frontend API client<br/>[api.ts]"]
end

subgraph group_api["API and orchestration"]
  node_api_routes["API routes<br/>[routes.py]"]
  node_analysis_service["Analysis service"]
  node_agent_graph["Agent workflow<br/>[graph.py]"]
  node_agent_runtime["Agent runtime<br/>[runtime.py]"]
end

subgraph group_research["Market research"]
  node_planner["Research planner<br/>[planner.py]"]
  node_intelligence["Market intelligence"]
  node_serp_gateway["Search gateway<br/>[gateway.py]"]
  node_serp_adapters["Search adapters"]
  node_normalization["Evidence normalization<br/>[normalize.py]"]
end

subgraph group_decision["Strategy and simulation"]
  node_strategy_builder["Strategy builder"]
  node_llm_strategy["LLM strategy drafts<br/>[llm_strategy.py]"]
  node_simulation["Financial simulation<br/>[engine.py]"]
  node_critic["Strategy critic<br/>[critic.py]"]
  node_report["Report composer<br/>[report.py]"]
end

subgraph group_data["Data and integrations"]
  node_llm_adapter["LLM adapter<br/>[adapter.py]"]
  node_db[("SQLite persistence<br/>[db.py]")]
  node_models["Stored analysis models<br/>[models.py]"]
  node_profile_schema["Business profile schema<br/>[profile.py]"]
  node_analysis_schema["Analysis schemas<br/>[analysis.py]"]
  node_demo_fixtures["Demo fixtures<br/>[synthetic.py]"]
end

node_entrepreneur(("Entrepreneur"))
node_serpapi{{"SerpApi"}}
node_llm_provider{{"LLM providers"}}

node_entrepreneur -->|"answers questions"| node_onboarding
node_onboarding -->|"reviews profile"| node_profile_review
node_profile_review -->|"saves and starts"| node_frontend_api
node_frontend_api -.->|"calls API"| node_api_routes
node_api_routes -->|"creates analysis"| node_analysis_service
node_analysis_service -->|"invokes workflow"| node_agent_graph
node_agent_graph -->|"plans research"| node_planner
node_agent_graph -->|"gathers evidence"| node_intelligence
node_intelligence -.->|"requests searches"| node_serp_gateway
node_serp_gateway -.->|"dispatches engines"| node_serp_adapters
node_serp_gateway -.->|"queries"| node_serpapi
node_serp_gateway -->|"loads fixtures"| node_demo_fixtures
node_serp_adapters -->|"normalizes results"| node_normalization
node_agent_graph -->|"builds strategies"| node_strategy_builder
node_strategy_builder -.->|"drafts optionally"| node_llm_strategy
node_llm_strategy -->|"requests structured output"| node_llm_adapter
node_llm_adapter -->|"requests completion"| node_llm_provider
node_agent_graph -->|"simulates strategies"| node_simulation
node_analysis_service -->|"serves what-if runs"| node_simulation
node_agent_graph -->|"challenges assumptions"| node_critic
node_agent_graph -->|"composes report"| node_report
node_analysis_service -->|"builds runtime"| node_agent_runtime
node_analysis_service -->|"persists results"| node_db
node_api_routes -->|"reads and writes"| node_db
node_db -.->|"stores records"| node_models
node_onboarding -.->|"collects profile data"| node_profile_schema
node_agent_graph -->|"exchanges typed results"| node_analysis_schema
node_report -->|"presents results"| node_dashboard
node_dashboard -.->|"loads results and events"| node_api_routes

click node_onboarding "https://github.com/jainamd05/marketsim/blob/main/frontend/src/features/onboarding/OnboardingWizard.tsx"
click node_profile_review "https://github.com/jainamd05/marketsim/blob/main/frontend/src/features/onboarding/ReviewPage.tsx"
click node_dashboard "https://github.com/jainamd05/marketsim/tree/main/frontend/src/features/dashboard"
click node_frontend_api "https://github.com/jainamd05/marketsim/blob/main/frontend/src/lib/api.ts"
click node_api_routes "https://github.com/jainamd05/marketsim/blob/main/backend/app/api/routes.py"
click node_analysis_service "https://github.com/jainamd05/marketsim/blob/main/backend/app/services/analysis_service.py"
click node_agent_graph "https://github.com/jainamd05/marketsim/blob/main/backend/app/agents/graph.py"
click node_agent_runtime "https://github.com/jainamd05/marketsim/blob/main/backend/app/agents/runtime.py"
click node_planner "https://github.com/jainamd05/marketsim/blob/main/backend/app/agents/planner.py"
click node_intelligence "https://github.com/jainamd05/marketsim/tree/main/backend/app/intelligence"
click node_serp_gateway "https://github.com/jainamd05/marketsim/blob/main/backend/app/serpapi/gateway.py"
click node_serp_adapters "https://github.com/jainamd05/marketsim/tree/main/backend/app/serpapi/adapters"
click node_normalization "https://github.com/jainamd05/marketsim/blob/main/backend/app/serpapi/normalize.py"
click node_strategy_builder "https://github.com/jainamd05/marketsim/blob/main/backend/app/agents/strategy_builder.py"
click node_llm_strategy "https://github.com/jainamd05/marketsim/blob/main/backend/app/agents/llm_strategy.py"
click node_llm_adapter "https://github.com/jainamd05/marketsim/blob/main/backend/app/llm/adapter.py"
click node_simulation "https://github.com/jainamd05/marketsim/blob/main/backend/app/simulation/engine.py"
click node_critic "https://github.com/jainamd05/marketsim/blob/main/backend/app/agents/critic.py"
click node_report "https://github.com/jainamd05/marketsim/blob/main/backend/app/agents/report.py"
click node_db "https://github.com/jainamd05/marketsim/blob/main/backend/app/db.py"
click node_models "https://github.com/jainamd05/marketsim/blob/main/backend/app/models.py"
click node_profile_schema "https://github.com/jainamd05/marketsim/blob/main/backend/app/schemas/profile.py"
click node_analysis_schema "https://github.com/jainamd05/marketsim/blob/main/backend/app/schemas/analysis.py"
click node_demo_fixtures "https://github.com/jainamd05/marketsim/blob/main/backend/app/serpapi/synthetic.py"

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_onboarding,node_profile_review,node_dashboard,node_frontend_api toneBlue
class node_api_routes,node_analysis_service,node_agent_graph,node_agent_runtime toneAmber
class node_planner,node_intelligence,node_serp_gateway,node_serp_adapters,node_normalization,node_serpapi toneMint
class node_strategy_builder,node_llm_strategy,node_simulation,node_critic,node_report toneRose
class node_llm_adapter,node_db,node_models,node_profile_schema,node_analysis_schema,node_demo_fixtures,node_entrepreneur,node_llm_provider toneIndigo
```

## Components

### User experience

- [Profile onboarding](https://github.com/jainamd05/marketsim/blob/main/frontend/src/features/onboarding/OnboardingWizard.tsx): `frontend/src/features/onboarding/OnboardingWizard.tsx`
- [Profile review](https://github.com/jainamd05/marketsim/blob/main/frontend/src/features/onboarding/ReviewPage.tsx): `frontend/src/features/onboarding/ReviewPage.tsx`
- [Analysis dashboard](https://github.com/jainamd05/marketsim/tree/main/frontend/src/features/dashboard): `frontend/src/features/dashboard`
- [Frontend API client](https://github.com/jainamd05/marketsim/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and orchestration

- [API routes](https://github.com/jainamd05/marketsim/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Analysis service](https://github.com/jainamd05/marketsim/blob/main/backend/app/services/analysis_service.py): `backend/app/services/analysis_service.py`
- [Agent workflow](https://github.com/jainamd05/marketsim/blob/main/backend/app/agents/graph.py): `backend/app/agents/graph.py`
- [Agent runtime](https://github.com/jainamd05/marketsim/blob/main/backend/app/agents/runtime.py): `backend/app/agents/runtime.py`

### Market research

- [Research planner](https://github.com/jainamd05/marketsim/blob/main/backend/app/agents/planner.py): `backend/app/agents/planner.py`
- [Market intelligence](https://github.com/jainamd05/marketsim/tree/main/backend/app/intelligence): `backend/app/intelligence`
- [Search gateway](https://github.com/jainamd05/marketsim/blob/main/backend/app/serpapi/gateway.py): `backend/app/serpapi/gateway.py`
- [Search adapters](https://github.com/jainamd05/marketsim/tree/main/backend/app/serpapi/adapters): `backend/app/serpapi/adapters`
- [Evidence normalization](https://github.com/jainamd05/marketsim/blob/main/backend/app/serpapi/normalize.py): `backend/app/serpapi/normalize.py`

### Strategy and simulation

- [Strategy builder](https://github.com/jainamd05/marketsim/blob/main/backend/app/agents/strategy_builder.py): `backend/app/agents/strategy_builder.py`
- [LLM strategy drafts](https://github.com/jainamd05/marketsim/blob/main/backend/app/agents/llm_strategy.py): `backend/app/agents/llm_strategy.py`
- [Financial simulation](https://github.com/jainamd05/marketsim/blob/main/backend/app/simulation/engine.py): `backend/app/simulation/engine.py`
- [Strategy critic](https://github.com/jainamd05/marketsim/blob/main/backend/app/agents/critic.py): `backend/app/agents/critic.py`
- [Report composer](https://github.com/jainamd05/marketsim/blob/main/backend/app/agents/report.py): `backend/app/agents/report.py`

### Data and integrations

- [LLM adapter](https://github.com/jainamd05/marketsim/blob/main/backend/app/llm/adapter.py): `backend/app/llm/adapter.py`
- [SQLite persistence](https://github.com/jainamd05/marketsim/blob/main/backend/app/db.py): `backend/app/db.py`
- [Stored analysis models](https://github.com/jainamd05/marketsim/blob/main/backend/app/models.py): `backend/app/models.py`
- [Business profile schema](https://github.com/jainamd05/marketsim/blob/main/backend/app/schemas/profile.py): `backend/app/schemas/profile.py`
- [Analysis schemas](https://github.com/jainamd05/marketsim/blob/main/backend/app/schemas/analysis.py): `backend/app/schemas/analysis.py`
- [Demo fixtures](https://github.com/jainamd05/marketsim/blob/main/backend/app/serpapi/synthetic.py): `backend/app/serpapi/synthetic.py`

### Other components

- **Entrepreneur**
- **SerpApi**
- **LLM providers**

## Connections

- Entrepreneur → Profile onboarding: answers questions
- Profile onboarding → Profile review: reviews profile
- Profile review → Frontend API client: saves and starts
- Frontend API client → API routes: calls API
- API routes → Analysis service: creates analysis (evidence: `backend/app/api/routes.py`)
- Analysis service → Agent workflow: invokes workflow (evidence: `backend/app/services/analysis_service.py`)
- Agent workflow → Research planner: plans research
- Agent workflow → Market intelligence: gathers evidence
- Market intelligence → Search gateway: requests searches
- Search gateway → Search adapters: dispatches engines
- Search gateway → SerpApi: queries
- Search gateway → Demo fixtures: loads fixtures (evidence: `backend/app/serpapi/gateway.py`)
- Search adapters → Evidence normalization: normalizes results (evidence: `backend/app/serpapi/adapters/search.py`)
- Agent workflow → Strategy builder: builds strategies
- Strategy builder → LLM strategy drafts: drafts optionally (evidence: `backend/app/agents/llm_strategy.py`)
- LLM strategy drafts → LLM adapter: requests structured output (evidence: `backend/app/agents/llm_strategy.py`)
- LLM adapter → LLM providers: requests completion (evidence: `backend/app/llm/adapter.py`)
- Agent workflow → Financial simulation: simulates strategies
- Analysis service → Financial simulation: serves what-if runs (evidence: `backend/app/api/routes.py`)
- Agent workflow → Strategy critic: challenges assumptions
- Agent workflow → Report composer: composes report
- Analysis service → Agent runtime: builds runtime (evidence: `backend/app/services/analysis_service.py`)
- Analysis service → SQLite persistence: persists results (evidence: `backend/app/services/analysis_service.py`)
- API routes → SQLite persistence: reads and writes (evidence: `backend/app/api/routes.py`)
- SQLite persistence → Stored analysis models: stores records
- Profile onboarding → Business profile schema: collects profile data
- Agent workflow → Analysis schemas: exchanges typed results
- Report composer → Analysis dashboard: presents results
- Analysis dashboard → API routes: loads results and events
