# yevhens-hue/oracle-agentic-ai architecture

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

- Interactive diagram: https://gitdiagram.com/yevhens-hue/oracle-agentic-ai
- Repository: https://github.com/yevhens-hue/oracle-agentic-ai

## Overview

The tree contains two distinct runtime products: a Zhaluzi customer-assistance API and a MarketZen competitive-intelligence web application. Their workflows cover assistant requests and research, scraping, SEO/GEO audits, and reporting. The README instead describes an Oracle Agentic AI knowledge hub and does not document these runtime products. The sampled API excerpt shows trigger evaluation and competitive-intelligence dispatch; the index identifies other modules, but does not establish their call relationships. Frontend route and panel files are present, but their wiring is not shown in the available evidence.

Main entry points: [`api/main.py`](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/main.py) (REST API), [`api/trigger_engine.py`](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/trigger_engine.py) (Behavior triggers), [`api/competitive_intelligence.py`](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/competitive_intelligence.py) (Competitive analysis), [`competitive-intel-app/app/page.tsx`](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/app/page.tsx) (Research home)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_zhaluzi["Zhaluzi Assistant"]
  node_api["REST API<br/>[main.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
  node_triggers["Behavior triggers<br/>[trigger_engine.py]"]
  node_leads["Lead scoring<br/>[lead_engine.py]"]
  node_agent["Tool-using assistant<br/>[agent_zhaluzi.py]"]
  node_fabricrag["Fabric search"]
end

subgraph group_research["Market Research"]
  node_intel["Competitive analysis"]
  node_advertools["SEO and GEO audit"]
  node_firecrawl["Firecrawl extraction"]
  node_crawl4ai["Crawl4AI extraction"]
end

subgraph group_web["Research Web App"]
  node_home["Research home<br/>[page.tsx]"]
  node_researchroutes["Research endpoints<br/>[route.ts]"]
  node_scraperoutes["Scraper endpoints<br/>[route.ts]"]
  node_auditroute["SEO audit endpoint<br/>[route.ts]"]
  node_trackerroute["Competitor tracking<br/>[route.ts]"]
  node_reports["Reports endpoint<br/>[route.ts]"]
  node_gptresearch["GPT research agent<br/>[gptResearcher.ts]"]
  node_subagents["Marketing subagents"]
  node_crawlengine["Crawl4AI engine<br/>[crawl4aiEngine.ts]"]
  node_fireengine["Firecrawl engine<br/>[firecrawlEngine.ts]"]
end

subgraph group_evaluation["Agent Evaluation"]
  node_mockagent["Mock agent<br/>[agent_mock.py]"]
end

node_visitor(("API client"))
node_webclient(("Research user"))

node_visitor -->|"requests"| node_api
node_api -->|"evaluates"| node_triggers
node_api -->|"runs pipeline"| node_intel
node_webclient -.->|"uses"| node_home

click node_api "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/main.py"
click node_schemas "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/schemas.py"
click node_triggers "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/trigger_engine.py"
click node_leads "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/lead_engine.py"
click node_agent "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/eval/agent_zhaluzi.py"
click node_fabricrag "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/eval/fabric_vector_rag.py"
click node_intel "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/competitive_intelligence.py"
click node_advertools "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/advertools_analyzer.py"
click node_firecrawl "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/firecrawl_scraper.py"
click node_crawl4ai "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/crawl4ai_scraper.py"
click node_home "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/app/page.tsx"
click node_researchroutes "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/app/api/research/competitive-intel/route.ts"
click node_scraperoutes "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/app/api/research/crawl4ai-scrape/route.ts"
click node_auditroute "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/app/api/seo/advertools-audit/route.ts"
click node_trackerroute "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/app/api/competitors/tracker/route.ts"
click node_reports "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/app/api/reports/route.ts"
click node_gptresearch "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/lib/agents/gptResearcher.ts"
click node_subagents "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/lib/agents/marketingSubagents.ts"
click node_crawlengine "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/lib/scrapers/crawl4aiEngine.ts"
click node_fireengine "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/lib/scrapers/firecrawlEngine.ts"
click node_mockagent "https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/eval/agent_mock.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_api,node_schemas,node_triggers,node_leads,node_agent,node_fabricrag,node_visitor,node_webclient toneBlue
class node_intel,node_advertools,node_firecrawl,node_crawl4ai toneAmber
class node_home,node_researchroutes,node_scraperoutes,node_auditroute,node_trackerroute,node_reports,node_gptresearch,node_subagents,node_crawlengine,node_fireengine toneMint
class node_mockagent toneRose
```

## Components

### Zhaluzi Assistant

- [REST API](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/main.py): `api/main.py`
- [API schemas](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/schemas.py): `api/schemas.py`
- [Behavior triggers](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/trigger_engine.py): `api/trigger_engine.py`
- [Lead scoring](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/lead_engine.py): `api/lead_engine.py`
- [Tool-using assistant](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/eval/agent_zhaluzi.py): `eval/agent_zhaluzi.py`
- [Fabric search](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/eval/fabric_vector_rag.py): `eval/fabric_vector_rag.py`

### Market Research

- [Competitive analysis](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/competitive_intelligence.py): `api/competitive_intelligence.py`
- [SEO and GEO audit](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/advertools_analyzer.py): `api/advertools_analyzer.py`
- [Firecrawl extraction](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/firecrawl_scraper.py): `api/firecrawl_scraper.py`
- [Crawl4AI extraction](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/api/crawl4ai_scraper.py): `api/crawl4ai_scraper.py`

### Research Web App

- [Research home](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/app/page.tsx): `competitive-intel-app/app/page.tsx`
- [Research endpoints](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/app/api/research/competitive-intel/route.ts): `competitive-intel-app/app/api/research/competitive-intel/route.ts`
- [Scraper endpoints](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/app/api/research/crawl4ai-scrape/route.ts): `competitive-intel-app/app/api/research/crawl4ai-scrape/route.ts`
- [SEO audit endpoint](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/app/api/seo/advertools-audit/route.ts): `competitive-intel-app/app/api/seo/advertools-audit/route.ts`
- [Competitor tracking](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/app/api/competitors/tracker/route.ts): `competitive-intel-app/app/api/competitors/tracker/route.ts`
- [Reports endpoint](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/app/api/reports/route.ts): `competitive-intel-app/app/api/reports/route.ts`
- [GPT research agent](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/lib/agents/gptResearcher.ts): `competitive-intel-app/lib/agents/gptResearcher.ts`
- [Marketing subagents](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/lib/agents/marketingSubagents.ts): `competitive-intel-app/lib/agents/marketingSubagents.ts`
- [Crawl4AI engine](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/lib/scrapers/crawl4aiEngine.ts): `competitive-intel-app/lib/scrapers/crawl4aiEngine.ts`
- [Firecrawl engine](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/competitive-intel-app/lib/scrapers/firecrawlEngine.ts): `competitive-intel-app/lib/scrapers/firecrawlEngine.ts`

### Agent Evaluation

- [Mock agent](https://github.com/yevhens-hue/oracle-agentic-ai/blob/main/eval/agent_mock.py): `eval/agent_mock.py`

### Other components

- **API client**
- **Research user**

## Connections

- API client → REST API: requests (evidence: `api/main.py`)
- REST API → Behavior triggers: evaluates (evidence: `api/main.py`)
- REST API → Competitive analysis: runs pipeline (evidence: `api/main.py`)
- Research user → Research home: uses
