# lakshmanpanda/aegis architecture

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

- Interactive diagram: https://gitdiagram.com/lakshmanpanda/aegis
- Repository: https://github.com/lakshmanpanda/aegis

## Overview

AEGIS is a two-service competitive-intelligence product: its scraper resolves a product and extracts market signals; the core service turns those signals into graph-backed analysis, a scored strategy, and an executive report. The primary workflow runs through the core API and LangGraph agents, with the API conditionally requesting fresh scraper data. The README documents additional monitoring and email-alert capabilities. Some subsystem links are based on README documentation because their implementation excerpts were not provided.

Main entry points: [`Scrapper/main_agent.py`](https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/main_agent.py) (Extraction workflow), [`aegis_core/app/core/mcp_client.py`](https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/core/mcp_client.py) (MCP client), [`aegis_core/app/graph/workflow.py`](https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/graph/workflow.py) (Agent workflow), [`aegis_core/app/api/routes.py`](https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/api/routes.py) (Core API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scraper["Market sensor"]
  node_scrape_api["Scraper API<br/>[api.py]"]
  node_product_search["Product search"]
  node_scraper_flow["Extraction workflow<br/>[main_agent.py]"]
  node_fetcher["Page fetcher<br/>[fetcher.py]"]
  node_html_cleaner["HTML cleaner<br/>[html_cleaner.py]"]
  node_pricing["Pricing signals<br/>[pricing_agent.py]"]
  node_sentiment["Sentiment signals<br/>[sentiment_agent.py]"]
  node_market_intel["Market signals"]
  node_competitor_intel["Competitor signals"]
end

subgraph group_core["Intelligence workflow"]
  node_core_api["Core API<br/>[routes.py]"]
  node_core_workflow["Agent workflow<br/>[workflow.py]"]
  node_perception["Perception scout"]
  node_architect["Graph architect<br/>[graph_architect.py]"]
  node_strategist["Wargaming strategist"]
  node_pivot_math["Pivot scoring<br/>[mathematics.py]"]
  node_commander["Execution commander"]
  node_state["Shared agent state<br/>[state.py]"]
end

subgraph group_integrations["Graph and alerts"]
  node_mcp_client["MCP client<br/>[mcp_client.py]"]
  node_neo4j[("Neo4j graph")]
  node_intel_server["Graph tools<br/>[intel_server.py]"]
  node_command_server["Inventory tools<br/>[command_server.py]"]
  node_mail_server["Mail server<br/>[mcp_server_mail.py]"]
  node_scheduler["Monitor scheduler<br/>[routes.py]"]
end

subgraph group_interface["User interface"]
  node_ui["Command center<br/>[streamlit_app.py]"]
end

node_seller(("Seller"))

node_seller -.->|"submits target"| node_ui
node_ui -.->|"requests analysis"| node_core_api
node_core_api -->|"requests scrape"| node_scrape_api
node_scrape_api -->|"invokes pipeline"| node_scraper_flow
node_scraper_flow -->|"resolves product"| node_product_search
node_scraper_flow -->|"fetches page"| node_fetcher
node_scraper_flow -->|"extracts pricing"| node_pricing
node_scraper_flow -->|"extracts sentiment"| node_sentiment
node_scraper_flow -->|"extracts market"| node_market_intel
node_scraper_flow -->|"finds competitors"| node_competitor_intel
node_pricing -->|"cleans HTML"| node_html_cleaner
node_sentiment -->|"cleans HTML"| node_html_cleaner
node_market_intel -->|"cleans HTML"| node_html_cleaner
node_core_api -->|"runs analysis"| node_core_workflow
node_core_workflow -->|"dispatches"| node_perception
node_core_workflow -->|"dispatches"| node_architect
node_core_workflow -->|"dispatches"| node_strategist
node_core_workflow -->|"dispatches"| node_commander
node_strategist -->|"calculates score"| node_pivot_math
node_architect -->|"uses tools"| node_mcp_client
node_strategist -->|"invokes tools"| node_mcp_client
node_commander -->|"uses tools"| node_mcp_client
node_mcp_client -->|"starts subprocess"| node_intel_server
node_mcp_client -->|"starts subprocess"| node_command_server
node_mcp_client -->|"starts subprocess"| node_mail_server
node_intel_server -.->|"queries graph"| node_neo4j
node_command_server -.->|"reads inventory"| node_neo4j
node_commander -.->|"sends alerts"| node_mail_server
node_core_api -->|"schedules monitoring"| node_scheduler

click node_ui "https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/streamlit_app.py"
click node_core_api "https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/api/routes.py"
click node_scrape_api "https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/api.py"
click node_product_search "https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/agents/amazon_search_agent.py"
click node_scraper_flow "https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/main_agent.py"
click node_fetcher "https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/agents/fetcher.py"
click node_html_cleaner "https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/utils/html_cleaner.py"
click node_pricing "https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/agents/pricing_agent.py"
click node_sentiment "https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/agents/sentiment_agent.py"
click node_market_intel "https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/agents/market_intel_agent.py"
click node_competitor_intel "https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/agents/competitor_intel_agent.py"
click node_core_workflow "https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/graph/workflow.py"
click node_perception "https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/agents/perception_scout.py"
click node_architect "https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/agents/graph_architect.py"
click node_strategist "https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/agents/wargame_strategist.py"
click node_pivot_math "https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/core/mathematics.py"
click node_commander "https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/agents/execution_commander.py"
click node_state "https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/models/state.py"
click node_mcp_client "https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/core/mcp_client.py"
click node_intel_server "https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/mcp_servers/intel_server.py"
click node_command_server "https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/mcp_servers/command_server.py"
click node_mail_server "https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/mcp_servers/mcp_server_mail.py"
click node_scheduler "https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/api/routes.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_scrape_api,node_product_search,node_scraper_flow,node_fetcher,node_html_cleaner,node_pricing,node_sentiment,node_market_intel,node_competitor_intel toneBlue
class node_core_api,node_core_workflow,node_perception,node_architect,node_strategist,node_pivot_math,node_commander,node_state toneAmber
class node_mcp_client,node_neo4j,node_intel_server,node_command_server,node_mail_server,node_scheduler toneMint
class node_ui toneRose
class node_seller toneIndigo
```

## Components

### Market sensor

- [Scraper API](https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/api.py): `Scrapper/api.py`
- [Product search](https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/agents/amazon_search_agent.py): `Scrapper/agents/amazon_search_agent.py`
- [Extraction workflow](https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/main_agent.py): `Scrapper/main_agent.py`
- [Page fetcher](https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/agents/fetcher.py): `Scrapper/agents/fetcher.py`
- [HTML cleaner](https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/utils/html_cleaner.py): `Scrapper/utils/html_cleaner.py`
- [Pricing signals](https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/agents/pricing_agent.py): `Scrapper/agents/pricing_agent.py`
- [Sentiment signals](https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/agents/sentiment_agent.py): `Scrapper/agents/sentiment_agent.py`
- [Market signals](https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/agents/market_intel_agent.py): `Scrapper/agents/market_intel_agent.py`
- [Competitor signals](https://github.com/lakshmanpanda/aegis/blob/main/Scrapper/agents/competitor_intel_agent.py): `Scrapper/agents/competitor_intel_agent.py`

### Intelligence workflow

- [Core API](https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/api/routes.py): `aegis_core/app/api/routes.py`
- [Agent workflow](https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/graph/workflow.py): `aegis_core/app/graph/workflow.py`
- [Perception scout](https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/agents/perception_scout.py): `aegis_core/app/agents/perception_scout.py`
- [Graph architect](https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/agents/graph_architect.py): `aegis_core/app/agents/graph_architect.py`
- [Wargaming strategist](https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/agents/wargame_strategist.py): `aegis_core/app/agents/wargame_strategist.py`
- [Pivot scoring](https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/core/mathematics.py): `aegis_core/app/core/mathematics.py`
- [Execution commander](https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/agents/execution_commander.py): `aegis_core/app/agents/execution_commander.py`
- [Shared agent state](https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/models/state.py): `aegis_core/app/models/state.py`

### Graph and alerts

- [MCP client](https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/core/mcp_client.py): `aegis_core/app/core/mcp_client.py`
- **Neo4j graph**
- [Graph tools](https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/mcp_servers/intel_server.py): `aegis_core/app/mcp_servers/intel_server.py`
- [Inventory tools](https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/mcp_servers/command_server.py): `aegis_core/app/mcp_servers/command_server.py`
- [Mail server](https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/mcp_servers/mcp_server_mail.py): `aegis_core/app/mcp_servers/mcp_server_mail.py`
- [Monitor scheduler](https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/app/api/routes.py): `aegis_core/app/api/routes.py`

### User interface

- [Command center](https://github.com/lakshmanpanda/aegis/blob/main/aegis_core/streamlit_app.py): `aegis_core/streamlit_app.py`

### Other components

- **Seller**

## Connections

- Seller → Command center: submits target (evidence: `README.md`)
- Command center → Core API: requests analysis (evidence: `README.md`)
- Core API → Scraper API: requests scrape (evidence: `aegis_core/app/api/routes.py`)
- Scraper API → Extraction workflow: invokes pipeline (evidence: `Scrapper/api.py`)
- Extraction workflow → Product search: resolves product (evidence: `Scrapper/main_agent.py`)
- Extraction workflow → Page fetcher: fetches page (evidence: `Scrapper/main_agent.py`)
- Extraction workflow → Pricing signals: extracts pricing (evidence: `Scrapper/main_agent.py`)
- Extraction workflow → Sentiment signals: extracts sentiment (evidence: `Scrapper/main_agent.py`)
- Extraction workflow → Market signals: extracts market (evidence: `Scrapper/main_agent.py`)
- Extraction workflow → Competitor signals: finds competitors (evidence: `Scrapper/main_agent.py`)
- Pricing signals → HTML cleaner: cleans HTML (evidence: `Scrapper/agents/pricing_agent.py`)
- Sentiment signals → HTML cleaner: cleans HTML (evidence: `Scrapper/agents/sentiment_agent.py`)
- Market signals → HTML cleaner: cleans HTML (evidence: `Scrapper/agents/market_intel_agent.py`)
- Core API → Agent workflow: runs analysis (evidence: `aegis_core/app/api/routes.py`)
- Agent workflow → Perception scout: dispatches (evidence: `aegis_core/app/graph/workflow.py`)
- Agent workflow → Graph architect: dispatches (evidence: `aegis_core/app/graph/workflow.py`)
- Agent workflow → Wargaming strategist: dispatches (evidence: `aegis_core/app/graph/workflow.py`)
- Agent workflow → Execution commander: dispatches (evidence: `aegis_core/app/graph/workflow.py`)
- Wargaming strategist → Pivot scoring: calculates score (evidence: `aegis_core/app/agents/wargame_strategist.py`)
- Graph architect → MCP client: uses tools (evidence: `aegis_core/app/agents/graph_architect.py`)
- Wargaming strategist → MCP client: invokes tools (evidence: `aegis_core/app/agents/wargame_strategist.py`)
- Execution commander → MCP client: uses tools (evidence: `aegis_core/app/agents/execution_commander.py`)
- MCP client → Graph tools: starts subprocess (evidence: `aegis_core/app/core/mcp_client.py`)
- MCP client → Inventory tools: starts subprocess (evidence: `aegis_core/app/core/mcp_client.py`)
- MCP client → Mail server: starts subprocess (evidence: `aegis_core/app/core/mcp_client.py`)
- Graph tools → Neo4j graph: queries graph (evidence: `README.md`)
- Inventory tools → Neo4j graph: reads inventory (evidence: `README.md`)
- Execution commander → Mail server: sends alerts (evidence: `README.md`)
- Core API → Monitor scheduler: schedules monitoring (evidence: `aegis_core/app/api/routes.py`)
