# huangyixin666/methodpal- architecture

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

- Interactive diagram: https://gitdiagram.com/huangyixin666/methodpal-
- Repository: https://github.com/huangyixin666/methodpal-

## Overview

MethodPal is an AI-assisted data-analysis workspace for social-science researchers. Users authenticate, create a project, upload or edit a dataset, review variables and choose an analysis method; they can run analyses manually or ask the agent to clarify goals and execute a resumable workflow, then inspect charts, explanations and exported reports. The graph combines the documented product workflow with sampled API, persistence and orchestration relationships. Several feature modules are represented at their exact directory path because their implementation was not sampled; those links are documented capabilities, not claims of source inspection.

Main entry points: [`src/app/App.tsx`](https://github.com/huangyixin666/methodpal-/blob/main/src/app/App.tsx) (App shell), [`src/app/lib/api.ts`](https://github.com/huangyixin666/methodpal-/blob/main/src/app/lib/api.ts) (API client), [`src/app/components/AiPanel.tsx`](https://github.com/huangyixin666/methodpal-/blob/main/src/app/components/AiPanel.tsx) (Agent panel), [`backend/app/api/datasets.py`](https://github.com/huangyixin666/methodpal-/blob/main/backend/app/api/datasets.py) (Dataset API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Workspace UI"]
  node_app["App shell<br/>[App.tsx]"]
  node_auth["Authentication UI<br/>[AuthGate.tsx]"]
  node_workspace["Workspace state"]
  node_upload["Dataset editor<br/>[UploadPage.tsx]"]
  node_agentui["Agent panel<br/>[AiPanel.tsx]"]
  node_apiclient["API client<br/>[api.ts]"]
end

subgraph group_api["API and data"]
  node_projectapi["Project API<br/>[projects.py]"]
  node_datasetapi["Dataset API<br/>[datasets.py]"]
  node_profiler["Data profiling<br/>[data_profiler.py]"]
  node_agentapi["Agent API<br/>[agent.py]"]
  node_analysisapi["Analysis API<br/>[analysis.py]"]
end

subgraph group_analysis["Analysis and agents"]
  node_methods["Method selection"]
  node_workflow["Autonomous workflow"]
  node_agenttools["Agent tools"]
  node_runner["Analysis runner<br/>[analysis_runner.py]"]
  node_modeltools["Statistical models"]
end

subgraph group_persistence["Persistence and jobs"]
  node_jobs["Background jobs<br/>[background_jobs.py]"]
  node_store["Owner-scoped store<br/>[store.py]"]
  node_database[("SQLite database<br/>[database.py]")]
end

subgraph group_outputs["Results and exports"]
  node_results["Results and charts<br/>[ResultsPage.tsx]"]
  node_charts["Chart service<br/>[chart_runner.py]"]
  node_reports["Report export<br/>[reports.py]"]
end

node_researcher(("Researcher"))
node_llm{{"DeepSeek service"}}

node_researcher -->|"uses workspace"| node_app
node_app -->|"gates access"| node_auth
node_app -->|"provides state"| node_workspace
node_app -->|"shows upload"| node_upload
node_app -->|"shows assistant"| node_agentui
node_upload -->|"uploads data"| node_apiclient
node_workspace -->|"loads and saves"| node_apiclient
node_agentui -->|"sends requests"| node_apiclient
node_apiclient -->|"requests projects"| node_projectapi
node_apiclient -->|"requests datasets"| node_datasetapi
node_datasetapi -->|"profiles data"| node_profiler
node_researcher -->|"selects method"| node_methods
node_agentui -->|"submits prompts"| node_agentapi
node_agentapi -->|"runs autonomous analysis"| node_workflow
node_workflow -->|"uses tools"| node_agenttools
node_agentapi -->|"dispatches background runs"| node_jobs
node_researcher -->|"requests manual analysis"| node_analysisapi
node_analysisapi -->|"runs analysis"| node_runner
node_runner -.->|"executes methods"| node_modeltools
node_projectapi -->|"reads and writes"| node_store
node_datasetapi -->|"reads and writes"| node_store
node_store -->|"persists records"| node_database
node_jobs -->|"uses job persistence"| node_database
node_researcher -->|"reviews results"| node_results
node_researcher -->|"requests charts"| node_charts
node_researcher -->|"exports reports"| node_reports
node_reports -.->|"uses report writing"| node_llm

click node_app "https://github.com/huangyixin666/methodpal-/blob/main/src/app/App.tsx"
click node_auth "https://github.com/huangyixin666/methodpal-/blob/main/src/app/components/AuthGate.tsx"
click node_workspace "https://github.com/huangyixin666/methodpal-/blob/main/src/app/context/WorkspaceContext.tsx"
click node_upload "https://github.com/huangyixin666/methodpal-/blob/main/src/app/components/UploadPage.tsx"
click node_agentui "https://github.com/huangyixin666/methodpal-/blob/main/src/app/components/AiPanel.tsx"
click node_apiclient "https://github.com/huangyixin666/methodpal-/blob/main/src/app/lib/api.ts"
click node_projectapi "https://github.com/huangyixin666/methodpal-/blob/main/backend/app/api/projects.py"
click node_datasetapi "https://github.com/huangyixin666/methodpal-/blob/main/backend/app/api/datasets.py"
click node_profiler "https://github.com/huangyixin666/methodpal-/blob/main/backend/app/services/data_profiler.py"
click node_methods "https://github.com/huangyixin666/methodpal-/blob/main/backend/app/services/method_recommender.py"
click node_agentapi "https://github.com/huangyixin666/methodpal-/blob/main/backend/app/api/agent.py"
click node_workflow "https://github.com/huangyixin666/methodpal-/blob/main/backend/app/services/langgraph_agent/autonomous_workflow.py"
click node_agenttools "https://github.com/huangyixin666/methodpal-/tree/main/backend/app/services/agent_tools"
click node_analysisapi "https://github.com/huangyixin666/methodpal-/blob/main/backend/app/api/analysis.py"
click node_runner "https://github.com/huangyixin666/methodpal-/blob/main/backend/app/services/analysis_runner.py"
click node_modeltools "https://github.com/huangyixin666/methodpal-/tree/main/backend/app/services/model_tools"
click node_jobs "https://github.com/huangyixin666/methodpal-/blob/main/backend/app/services/background_jobs.py"
click node_store "https://github.com/huangyixin666/methodpal-/blob/main/backend/app/services/store.py"
click node_database "https://github.com/huangyixin666/methodpal-/blob/main/backend/app/services/database.py"
click node_results "https://github.com/huangyixin666/methodpal-/blob/main/src/app/components/ResultsPage.tsx"
click node_charts "https://github.com/huangyixin666/methodpal-/blob/main/backend/app/services/chart_tools/chart_runner.py"
click node_reports "https://github.com/huangyixin666/methodpal-/blob/main/backend/app/api/reports.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_app,node_auth,node_workspace,node_upload,node_agentui,node_apiclient toneBlue
class node_projectapi,node_datasetapi,node_profiler,node_agentapi,node_analysisapi toneAmber
class node_methods,node_workflow,node_agenttools,node_runner,node_modeltools toneMint
class node_jobs,node_store,node_database toneRose
class node_results,node_charts,node_reports,node_researcher,node_llm toneIndigo
```

## Components

### Workspace UI

- [App shell](https://github.com/huangyixin666/methodpal-/blob/main/src/app/App.tsx): `src/app/App.tsx`
- [Authentication UI](https://github.com/huangyixin666/methodpal-/blob/main/src/app/components/AuthGate.tsx): `src/app/components/AuthGate.tsx`
- [Workspace state](https://github.com/huangyixin666/methodpal-/blob/main/src/app/context/WorkspaceContext.tsx): `src/app/context/WorkspaceContext.tsx`
- [Dataset editor](https://github.com/huangyixin666/methodpal-/blob/main/src/app/components/UploadPage.tsx): `src/app/components/UploadPage.tsx`
- [Agent panel](https://github.com/huangyixin666/methodpal-/blob/main/src/app/components/AiPanel.tsx): `src/app/components/AiPanel.tsx`
- [API client](https://github.com/huangyixin666/methodpal-/blob/main/src/app/lib/api.ts): `src/app/lib/api.ts`

### API and data

- [Project API](https://github.com/huangyixin666/methodpal-/blob/main/backend/app/api/projects.py): `backend/app/api/projects.py`
- [Dataset API](https://github.com/huangyixin666/methodpal-/blob/main/backend/app/api/datasets.py): `backend/app/api/datasets.py`
- [Data profiling](https://github.com/huangyixin666/methodpal-/blob/main/backend/app/services/data_profiler.py): `backend/app/services/data_profiler.py`
- [Agent API](https://github.com/huangyixin666/methodpal-/blob/main/backend/app/api/agent.py): `backend/app/api/agent.py`
- [Analysis API](https://github.com/huangyixin666/methodpal-/blob/main/backend/app/api/analysis.py): `backend/app/api/analysis.py`

### Analysis and agents

- [Method selection](https://github.com/huangyixin666/methodpal-/blob/main/backend/app/services/method_recommender.py): `backend/app/services/method_recommender.py`
- [Autonomous workflow](https://github.com/huangyixin666/methodpal-/blob/main/backend/app/services/langgraph_agent/autonomous_workflow.py): `backend/app/services/langgraph_agent/autonomous_workflow.py`
- [Agent tools](https://github.com/huangyixin666/methodpal-/tree/main/backend/app/services/agent_tools): `backend/app/services/agent_tools`
- [Analysis runner](https://github.com/huangyixin666/methodpal-/blob/main/backend/app/services/analysis_runner.py): `backend/app/services/analysis_runner.py`
- [Statistical models](https://github.com/huangyixin666/methodpal-/tree/main/backend/app/services/model_tools): `backend/app/services/model_tools`

### Persistence and jobs

- [Background jobs](https://github.com/huangyixin666/methodpal-/blob/main/backend/app/services/background_jobs.py): `backend/app/services/background_jobs.py`
- [Owner-scoped store](https://github.com/huangyixin666/methodpal-/blob/main/backend/app/services/store.py): `backend/app/services/store.py`
- [SQLite database](https://github.com/huangyixin666/methodpal-/blob/main/backend/app/services/database.py): `backend/app/services/database.py`

### Results and exports

- [Results and charts](https://github.com/huangyixin666/methodpal-/blob/main/src/app/components/ResultsPage.tsx): `src/app/components/ResultsPage.tsx`
- [Chart service](https://github.com/huangyixin666/methodpal-/blob/main/backend/app/services/chart_tools/chart_runner.py): `backend/app/services/chart_tools/chart_runner.py`
- [Report export](https://github.com/huangyixin666/methodpal-/blob/main/backend/app/api/reports.py): `backend/app/api/reports.py`

### Other components

- **Researcher**
- **DeepSeek service**

## Connections

- Researcher → App shell: uses workspace (evidence: `README.md`)
- App shell → Authentication UI: gates access (evidence: `src/app/App.tsx`)
- App shell → Workspace state: provides state (evidence: `src/app/App.tsx`)
- App shell → Dataset editor: shows upload (evidence: `src/app/App.tsx`)
- App shell → Agent panel: shows assistant (evidence: `src/app/App.tsx`)
- Dataset editor → API client: uploads data (evidence: `src/app/components/UploadPage.tsx`)
- Workspace state → API client: loads and saves (evidence: `src/app/context/WorkspaceContext.tsx`)
- Agent panel → API client: sends requests (evidence: `src/app/components/AiPanel.tsx`)
- API client → Project API: requests projects (evidence: `backend/app/api/projects.py`)
- API client → Dataset API: requests datasets (evidence: `backend/app/api/datasets.py`)
- Dataset API → Data profiling: profiles data (evidence: `backend/app/api/datasets.py`)
- Researcher → Method selection: selects method (evidence: `README.md`)
- Agent panel → Agent API: submits prompts (evidence: `src/app/components/AiPanel.tsx`)
- Agent API → Autonomous workflow: runs autonomous analysis (evidence: `backend/app/api/agent.py`)
- Autonomous workflow → Agent tools: uses tools (evidence: `backend/app/services/langgraph_agent/autonomous_workflow.py`)
- Agent API → Background jobs: dispatches background runs (evidence: `backend/app/services/background_jobs.py`)
- Researcher → Analysis API: requests manual analysis (evidence: `README.md`)
- Analysis API → Analysis runner: runs analysis (evidence: `backend/app/api/analysis.py`)
- Analysis runner → Statistical models: executes methods
- Project API → Owner-scoped store: reads and writes (evidence: `backend/app/api/projects.py`)
- Dataset API → Owner-scoped store: reads and writes (evidence: `backend/app/api/datasets.py`)
- Owner-scoped store → SQLite database: persists records (evidence: `backend/app/services/store.py`)
- Background jobs → SQLite database: uses job persistence (evidence: `backend/app/services/background_jobs.py`)
- Researcher → Results and charts: reviews results (evidence: `README.md`)
- Researcher → Chart service: requests charts (evidence: `README.md`)
- Researcher → Report export: exports reports (evidence: `README.md`)
- Report export → DeepSeek service: uses report writing
