# umair706/amazon-omniscient architecture

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

- Interactive diagram: https://gitdiagram.com/umair706/amazon-omniscient
- Repository: https://github.com/umair706/amazon-omniscient

## Overview

Omniscient is a self-hosted Amazon FBA research product. Sellers discover or analyze a niche; the API queues background work that gathers marketplace and supplier data, enriches products and reviews, scores the opportunity, and produces financial projections and a launch brief for the frontend. The graph also preserves settings, exports, and the MCP toolbox. API routing and selected worker/service calls are evidenced by excerpts or the SOURCE INDEX; broader data-store and external-service connections are documented in the README, while unsampled internals are not expanded.

Main entry points: [`backend/app/workers/tasks.py`](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/workers/tasks.py) (Analysis worker), [`backend/app/api/router.py`](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/api/router.py) (API router), [`backend/app/main.py`](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/llm/base_client.py`](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/llm/base_client.py) (LLM providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_frontend["Research UI<br/>[page.tsx]"]
end

subgraph group_api["API and access"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_api_router["API router<br/>[router.py]"]
  node_niche_api["Niche API<br/>[niches.py]"]
  node_jobs_api["Jobs API<br/>[jobs.py]"]
  node_product_api["Product API<br/>[products.py]"]
  node_recommendation_api["Recommendation API<br/>[recommendations.py]"]
  node_settings_api["Settings API<br/>[settings.py]"]
  node_exports_api["Exports API<br/>[exports.py]"]
  node_mcp["MCP toolbox<br/>[tools.py]"]
end

subgraph group_research["Research workflow"]
  node_worker["Analysis worker<br/>[tasks.py]"]
  node_scraper["Amazon scraper<br/>[scraper_service.py]"]
  node_browser_session["Browser session<br/>[session.py]"]
  node_spapi["SP-API integration<br/>[spapi_service.py]"]
  node_supplier["Supplier sourcing"]
end

subgraph group_analysis["Analysis and outputs"]
  node_review_analysis["Review analysis<br/>[review_analyzer.py]"]
  node_competitors["Competitor analysis"]
  node_scoring["Opportunity scoring<br/>[scoring_service.py]"]
  node_score_config["Scoring settings<br/>[scoring_config.py]"]
  node_recommendations["Recommendation engine"]
  node_financials["Financial projections"]
  node_llm["LLM providers<br/>[base_client.py]"]
end

subgraph group_state["Data and integrations"]
  node_postgres[("PostgreSQL")]
  node_redis["Redis queue/cache"]
  node_amazon["Amazon marketplace"]
  node_supplier_sites["Supplier sites"]
  node_llm_provider["LLM service"]
  node_proxy["Proxy service"]
end

node_seller(("FBA seller"))

node_seller -->|"uses"| node_frontend
node_frontend -->|"REST requests"| node_api_app
node_api_app -->|"mounts"| node_api_router
node_api_router -->|"routes"| node_niche_api
node_api_router -->|"routes"| node_jobs_api
node_api_router -->|"routes"| node_product_api
node_api_router -->|"routes"| node_recommendation_api
node_api_router -->|"routes"| node_settings_api
node_api_router -->|"routes"| node_exports_api
node_jobs_api -->|"dispatches jobs"| node_worker
node_worker -->|"queues tasks"| node_redis
node_redis -->|"delivers tasks"| node_worker
node_worker -->|"uses"| node_scraper
node_worker -->|"builds session"| node_browser_session
node_scraper -->|"uses session"| node_browser_session
node_scraper -->|"scrapes pages"| node_amazon
node_worker -->|"uses"| node_spapi
node_worker -->|"sources suppliers"| node_supplier
node_supplier -->|"scrapes data"| node_supplier_sites
node_worker -->|"runs analysis"| node_review_analysis
node_review_analysis -->|"uses"| node_llm
node_competitors -->|"uses"| node_llm
node_worker -->|"computes score"| node_scoring
node_scoring -->|"loads rules"| node_score_config
node_worker -->|"builds brief"| node_recommendations
node_recommendations -->|"scores metrics"| node_scoring
node_recommendations -->|"generates analysis"| node_llm
node_worker -->|"produces projections"| node_financials
node_llm -->|"requests analysis"| node_llm_provider
node_browser_session -->|"rotates IPs"| node_proxy
node_api_app -->|"stores data"| node_postgres
node_worker -->|"persists results"| node_postgres
node_api_app -->|"uses cache"| node_redis
node_api_app -.->|"exposes tools"| node_mcp
node_seller -->|"connects agent"| node_mcp

click node_frontend "https://github.com/umair706/amazon-omniscient/blob/main/frontend/src/app/page.tsx"
click node_api_app "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/main.py"
click node_api_router "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/api/router.py"
click node_niche_api "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/api/niches.py"
click node_jobs_api "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/api/jobs.py"
click node_product_api "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/api/products.py"
click node_recommendation_api "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/api/recommendations.py"
click node_settings_api "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/api/settings.py"
click node_exports_api "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/api/exports.py"
click node_mcp "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/mcp/tools.py"
click node_worker "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/workers/tasks.py"
click node_scraper "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/services/scraper_service.py"
click node_browser_session "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/scraping/session.py"
click node_spapi "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/services/spapi_service.py"
click node_supplier "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/services/made_in_china_scraper.py"
click node_review_analysis "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/services/review_analyzer.py"
click node_competitors "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/services/competitor_service.py"
click node_scoring "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/services/scoring_service.py"
click node_score_config "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/services/scoring_config.py"
click node_recommendations "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/services/recommendation_engine.py"
click node_financials "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/services/financial_report.py"
click node_llm "https://github.com/umair706/amazon-omniscient/blob/main/backend/app/llm/base_client.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_frontend toneBlue
class node_api_app,node_api_router,node_niche_api,node_jobs_api,node_product_api,node_recommendation_api,node_settings_api,node_exports_api,node_mcp toneAmber
class node_worker,node_scraper,node_browser_session,node_spapi,node_supplier toneMint
class node_review_analysis,node_competitors,node_scoring,node_score_config,node_recommendations,node_financials,node_llm toneRose
class node_postgres,node_redis,node_amazon,node_supplier_sites,node_llm_provider,node_proxy,node_seller toneIndigo
```

## Components

### Client

- [Research UI](https://github.com/umair706/amazon-omniscient/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`

### API and access

- [FastAPI app](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/main.py): `backend/app/main.py`
- [API router](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [Niche API](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/api/niches.py): `backend/app/api/niches.py`
- [Jobs API](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/api/jobs.py): `backend/app/api/jobs.py`
- [Product API](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/api/products.py): `backend/app/api/products.py`
- [Recommendation API](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/api/recommendations.py): `backend/app/api/recommendations.py`
- [Settings API](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/api/settings.py): `backend/app/api/settings.py`
- [Exports API](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/api/exports.py): `backend/app/api/exports.py`
- [MCP toolbox](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/mcp/tools.py): `backend/app/mcp/tools.py`

### Research workflow

- [Analysis worker](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/workers/tasks.py): `backend/app/workers/tasks.py`
- [Amazon scraper](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/services/scraper_service.py): `backend/app/services/scraper_service.py`
- [Browser session](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/scraping/session.py): `backend/app/scraping/session.py`
- [SP-API integration](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/services/spapi_service.py): `backend/app/services/spapi_service.py`
- [Supplier sourcing](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/services/made_in_china_scraper.py): `backend/app/services/made_in_china_scraper.py`

### Analysis and outputs

- [Review analysis](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/services/review_analyzer.py): `backend/app/services/review_analyzer.py`
- [Competitor analysis](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/services/competitor_service.py): `backend/app/services/competitor_service.py`
- [Opportunity scoring](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/services/scoring_service.py): `backend/app/services/scoring_service.py`
- [Scoring settings](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/services/scoring_config.py): `backend/app/services/scoring_config.py`
- [Recommendation engine](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/services/recommendation_engine.py): `backend/app/services/recommendation_engine.py`
- [Financial projections](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/services/financial_report.py): `backend/app/services/financial_report.py`
- [LLM providers](https://github.com/umair706/amazon-omniscient/blob/main/backend/app/llm/base_client.py): `backend/app/llm/base_client.py`

### Data and integrations

- **PostgreSQL**
- **Redis queue/cache**
- **Amazon marketplace**
- **Supplier sites**
- **LLM service**
- **Proxy service**

### Other components

- **FBA seller**

## Connections

- FBA seller → Research UI: uses (evidence: `README.md`)
- Research UI → FastAPI app: REST requests (evidence: `README.md`)
- FastAPI app → API router: mounts (evidence: `backend/app/main.py`)
- API router → Niche API: routes (evidence: `backend/app/api/router.py`)
- API router → Jobs API: routes (evidence: `backend/app/api/router.py`)
- API router → Product API: routes (evidence: `backend/app/api/router.py`)
- API router → Recommendation API: routes (evidence: `backend/app/api/router.py`)
- API router → Settings API: routes (evidence: `backend/app/api/router.py`)
- API router → Exports API: routes (evidence: `backend/app/api/router.py`)
- Jobs API → Analysis worker: dispatches jobs (evidence: `backend/app/api/jobs.py`)
- Analysis worker → Redis queue/cache: queues tasks (evidence: `README.md`)
- Redis queue/cache → Analysis worker: delivers tasks (evidence: `README.md`)
- Analysis worker → Amazon scraper: uses (evidence: `backend/app/workers/tasks.py`)
- Analysis worker → Browser session: builds session (evidence: `backend/app/workers/tasks.py`)
- Amazon scraper → Browser session: uses session (evidence: `backend/app/services/scraper_service.py`)
- Amazon scraper → Amazon marketplace: scrapes pages (evidence: `README.md`)
- Analysis worker → SP-API integration: uses (evidence: `backend/app/workers/tasks.py`)
- Analysis worker → Supplier sourcing: sources suppliers (evidence: `README.md`)
- Supplier sourcing → Supplier sites: scrapes data (evidence: `README.md`)
- Analysis worker → Review analysis: runs analysis (evidence: `backend/app/workers/tasks.py`)
- Review analysis → LLM providers: uses (evidence: `backend/app/services/review_analyzer.py`)
- Competitor analysis → LLM providers: uses (evidence: `backend/app/services/competitor_service.py`)
- Analysis worker → Opportunity scoring: computes score (evidence: `backend/app/workers/tasks.py`)
- Opportunity scoring → Scoring settings: loads rules (evidence: `backend/app/services/scoring_service.py`)
- Analysis worker → Recommendation engine: builds brief (evidence: `backend/app/services/recommendation_engine.py`)
- Recommendation engine → Opportunity scoring: scores metrics (evidence: `backend/app/services/recommendation_engine.py`)
- Recommendation engine → LLM providers: generates analysis (evidence: `backend/app/services/recommendation_engine.py`)
- Analysis worker → Financial projections: produces projections (evidence: `README.md`)
- LLM providers → LLM service: requests analysis (evidence: `README.md`)
- Browser session → Proxy service: rotates IPs (evidence: `README.md`)
- FastAPI app → PostgreSQL: stores data (evidence: `README.md`)
- Analysis worker → PostgreSQL: persists results (evidence: `README.md`)
- FastAPI app → Redis queue/cache: uses cache (evidence: `README.md`)
- FastAPI app → MCP toolbox: exposes tools
- FBA seller → MCP toolbox: connects agent (evidence: `README.md`)
