# msakash443-lgtm/research architecture

> Architecture diagram of the GitHub repository msakash443-lgtm/research, 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/msakash443-lgtm/research
- Repository: https://github.com/msakash443-lgtm/research

## Overview

Research AI Platform is a same-origin research workspace centered on private projects, structured context, auditable evidence, and durable evidence-synthesis runs. Researchers use the browser to create a project, save decisions and verified excerpts, then launch a run; the web service persists work for a separate worker, which may call a configured LLM. Optional retrieval is deliberately separate and off by default. The graph follows README-described flows and sampled/indexed references; many specialized routes and their internal calls were not inspected, so those links are omitted.

Main entry points: [`backend/app/main.py`](https://github.com/msakash443-lgtm/research/blob/main/backend/app/main.py) (FastAPI service), [`backend/app/routers/documents.py`](https://github.com/msakash443-lgtm/research/blob/main/backend/app/routers/documents.py) (Evidence library), [`backend/app/worker.py`](https://github.com/msakash443-lgtm/research/blob/main/backend/app/worker.py) (Research worker), [`backend/arc_retrieval/web/agent.py`](https://github.com/msakash443-lgtm/research/blob/main/backend/arc_retrieval/web/agent.py) (Web search agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Research workspace"]
  node_browser["Browser UI<br/>[app.js]"]
end

subgraph group_service["Web service"]
  node_web_api["FastAPI service<br/>[main.py]"]
  node_auth["Sign-in<br/>[auth.py]"]
  node_projects["Projects and context<br/>[projects.py]"]
  node_data_model["Research records<br/>[models.py]"]
  node_database[("PostgreSQL<br/>[database.py]")]
  node_audit["Audit trail<br/>[audit.py]"]
end

subgraph group_evidence["Evidence and synthesis"]
  node_evidence_api["Evidence library<br/>[documents.py]"]
  node_object_storage["Object storage<br/>[object_storage.py]"]
  node_agent_context["Evidence context<br/>[context.py]"]
  node_prompt_registry["Prompt registry<br/>[prompt_registry.py]"]
  node_llm["LLM adapter<br/>[llm.py]"]
  node_untrusted_text["Untrusted text guard<br/>[untrusted_text.py]"]
  node_extraction["Extraction schemas"]
end

subgraph group_processing["Durable processing"]
  node_run_api["Research runs<br/>[research_runs.py]"]
  node_worker["Research worker<br/>[worker.py]"]
  node_task_queue["Task queue<br/>[task_queue.py]"]
end

subgraph group_retrieval["Optional retrieval"]
  node_connector_catalogue["Scholarly connectors"]
  node_arc_client["ARC client<br/>[arc_client.py]"]
  node_arc_service["ARC retrieval API<br/>[retrieval_api.py]"]
  node_arc_agent["Web search agent<br/>[agent.py]"]
  node_ssrf_guard["SSRF protection<br/>[_ssrf.py]"]
  node_web_search["Web search<br/>[search.py]"]
end

node_researcher(("Researcher"))
node_llm_provider(("LLM provider"))
node_arc_http(("ARC HTTP service"))

node_researcher -->|"uses"| node_browser
node_browser -->|"calls API"| node_web_api
node_web_api -->|"routes to"| node_auth
node_web_api -->|"routes to"| node_projects
node_web_api -->|"routes to"| node_evidence_api
node_web_api -->|"persists data"| node_database
node_projects -.->|"stores records"| node_data_model
node_evidence_api -.->|"stores evidence"| node_data_model
node_data_model -->|"uses ORM"| node_database
node_web_api -->|"routes to"| node_run_api
node_run_api -->|"queues run"| node_task_queue
node_task_queue -->|"dispatches"| node_worker
node_worker -->|"requests synthesis"| node_llm
node_llm -->|"calls endpoint"| node_llm_provider
node_worker -->|"stores run"| node_database
node_evidence_api -.->|"stores files"| node_object_storage
node_web_api -.->|"records actions"| node_audit
node_web_api -.->|"offers opt-in"| node_connector_catalogue
node_web_api -.->|"offers opt-in"| node_arc_client
node_arc_client -->|"calls HTTP"| node_arc_http
node_arc_http -.->|"serves requests"| node_arc_service
node_arc_service -->|"dispatches"| node_arc_agent
node_arc_agent -->|"searches with"| node_web_search
node_arc_agent -.->|"fetches safely"| node_ssrf_guard

click node_browser "https://github.com/msakash443-lgtm/research/blob/main/backend/app/web/app.js"
click node_web_api "https://github.com/msakash443-lgtm/research/blob/main/backend/app/main.py"
click node_auth "https://github.com/msakash443-lgtm/research/blob/main/backend/app/routers/auth.py"
click node_projects "https://github.com/msakash443-lgtm/research/blob/main/backend/app/routers/projects.py"
click node_evidence_api "https://github.com/msakash443-lgtm/research/blob/main/backend/app/routers/documents.py"
click node_data_model "https://github.com/msakash443-lgtm/research/blob/main/backend/app/models.py"
click node_database "https://github.com/msakash443-lgtm/research/blob/main/backend/app/database.py"
click node_audit "https://github.com/msakash443-lgtm/research/blob/main/backend/app/audit.py"
click node_object_storage "https://github.com/msakash443-lgtm/research/blob/main/backend/app/object_storage.py"
click node_run_api "https://github.com/msakash443-lgtm/research/blob/main/backend/app/routers/research_runs.py"
click node_worker "https://github.com/msakash443-lgtm/research/blob/main/backend/app/worker.py"
click node_task_queue "https://github.com/msakash443-lgtm/research/blob/main/backend/app/task_queue.py"
click node_agent_context "https://github.com/msakash443-lgtm/research/blob/main/backend/app/agent/context.py"
click node_prompt_registry "https://github.com/msakash443-lgtm/research/blob/main/backend/app/prompt_registry.py"
click node_llm "https://github.com/msakash443-lgtm/research/blob/main/backend/app/agent/llm.py"
click node_untrusted_text "https://github.com/msakash443-lgtm/research/blob/main/backend/app/untrusted_text.py"
click node_extraction "https://github.com/msakash443-lgtm/research/blob/main/backend/app/extraction_schema.py"
click node_connector_catalogue "https://github.com/msakash443-lgtm/research/tree/main/backend/app/connectors"
click node_arc_client "https://github.com/msakash443-lgtm/research/blob/main/backend/app/agent/arc_client.py"
click node_arc_service "https://github.com/msakash443-lgtm/research/blob/main/backend/arc_retrieval/retrieval_api.py"
click node_arc_agent "https://github.com/msakash443-lgtm/research/blob/main/backend/arc_retrieval/web/agent.py"
click node_ssrf_guard "https://github.com/msakash443-lgtm/research/blob/main/backend/arc_retrieval/web/_ssrf.py"
click node_web_search "https://github.com/msakash443-lgtm/research/blob/main/backend/arc_retrieval/web/search.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_browser toneBlue
class node_web_api,node_auth,node_projects,node_data_model,node_database,node_audit toneAmber
class node_evidence_api,node_object_storage,node_agent_context,node_prompt_registry,node_llm,node_untrusted_text,node_extraction toneMint
class node_run_api,node_worker,node_task_queue toneRose
class node_connector_catalogue,node_arc_client,node_arc_service,node_arc_agent,node_ssrf_guard,node_web_search,node_researcher,node_llm_provider,node_arc_http toneIndigo
```

## Components

### Research workspace

- [Browser UI](https://github.com/msakash443-lgtm/research/blob/main/backend/app/web/app.js): `backend/app/web/app.js`

### Web service

- [FastAPI service](https://github.com/msakash443-lgtm/research/blob/main/backend/app/main.py): `backend/app/main.py`
- [Sign-in](https://github.com/msakash443-lgtm/research/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Projects and context](https://github.com/msakash443-lgtm/research/blob/main/backend/app/routers/projects.py): `backend/app/routers/projects.py`
- [Research records](https://github.com/msakash443-lgtm/research/blob/main/backend/app/models.py): `backend/app/models.py`
- [PostgreSQL](https://github.com/msakash443-lgtm/research/blob/main/backend/app/database.py): `backend/app/database.py`
- [Audit trail](https://github.com/msakash443-lgtm/research/blob/main/backend/app/audit.py): `backend/app/audit.py`

### Evidence and synthesis

- [Evidence library](https://github.com/msakash443-lgtm/research/blob/main/backend/app/routers/documents.py): `backend/app/routers/documents.py`
- [Object storage](https://github.com/msakash443-lgtm/research/blob/main/backend/app/object_storage.py): `backend/app/object_storage.py`
- [Evidence context](https://github.com/msakash443-lgtm/research/blob/main/backend/app/agent/context.py): `backend/app/agent/context.py`
- [Prompt registry](https://github.com/msakash443-lgtm/research/blob/main/backend/app/prompt_registry.py): `backend/app/prompt_registry.py`
- [LLM adapter](https://github.com/msakash443-lgtm/research/blob/main/backend/app/agent/llm.py): `backend/app/agent/llm.py`
- [Untrusted text guard](https://github.com/msakash443-lgtm/research/blob/main/backend/app/untrusted_text.py): `backend/app/untrusted_text.py`
- [Extraction schemas](https://github.com/msakash443-lgtm/research/blob/main/backend/app/extraction_schema.py): `backend/app/extraction_schema.py`

### Durable processing

- [Research runs](https://github.com/msakash443-lgtm/research/blob/main/backend/app/routers/research_runs.py): `backend/app/routers/research_runs.py`
- [Research worker](https://github.com/msakash443-lgtm/research/blob/main/backend/app/worker.py): `backend/app/worker.py`
- [Task queue](https://github.com/msakash443-lgtm/research/blob/main/backend/app/task_queue.py): `backend/app/task_queue.py`

### Optional retrieval

- [Scholarly connectors](https://github.com/msakash443-lgtm/research/tree/main/backend/app/connectors): `backend/app/connectors`
- [ARC client](https://github.com/msakash443-lgtm/research/blob/main/backend/app/agent/arc_client.py): `backend/app/agent/arc_client.py`
- [ARC retrieval API](https://github.com/msakash443-lgtm/research/blob/main/backend/arc_retrieval/retrieval_api.py): `backend/arc_retrieval/retrieval_api.py`
- [Web search agent](https://github.com/msakash443-lgtm/research/blob/main/backend/arc_retrieval/web/agent.py): `backend/arc_retrieval/web/agent.py`
- [SSRF protection](https://github.com/msakash443-lgtm/research/blob/main/backend/arc_retrieval/web/_ssrf.py): `backend/arc_retrieval/web/_ssrf.py`
- [Web search](https://github.com/msakash443-lgtm/research/blob/main/backend/arc_retrieval/web/search.py): `backend/arc_retrieval/web/search.py`

### Other components

- **Researcher**
- **LLM provider**
- **ARC HTTP service**

## Connections

- Researcher → Browser UI: uses (evidence: `README.md`)
- Browser UI → FastAPI service: calls API (evidence: `README.md`)
- FastAPI service → Sign-in: routes to (evidence: `backend/app/main.py`)
- FastAPI service → Projects and context: routes to (evidence: `backend/app/main.py`)
- FastAPI service → Evidence library: routes to (evidence: `backend/app/main.py`)
- FastAPI service → PostgreSQL: persists data (evidence: `README.md`)
- Projects and context → Research records: stores records
- Evidence library → Research records: stores evidence
- Research records → PostgreSQL: uses ORM (evidence: `backend/app/models.py`)
- FastAPI service → Research runs: routes to (evidence: `backend/app/main.py`)
- Research runs → Task queue: queues run (evidence: `README.md`)
- Task queue → Research worker: dispatches (evidence: `README.md`)
- Research worker → LLM adapter: requests synthesis (evidence: `README.md`)
- LLM adapter → LLM provider: calls endpoint (evidence: `README.md`)
- Research worker → PostgreSQL: stores run (evidence: `README.md`)
- Evidence library → Object storage: stores files
- FastAPI service → Audit trail: records actions
- FastAPI service → Scholarly connectors: offers opt-in (evidence: `README.md`)
- FastAPI service → ARC client: offers opt-in (evidence: `README.md`)
- ARC client → ARC HTTP service: calls HTTP (evidence: `README.md`)
- ARC HTTP service → ARC retrieval API: serves requests
- ARC retrieval API → Web search agent: dispatches (evidence: `backend/arc_retrieval/retrieval_api.py`)
- Web search agent → Web search: searches with (evidence: `backend/arc_retrieval/web/agent.py`)
- Web search agent → SSRF protection: fetches safely
