# devanimecx/jiro architecture

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

- Interactive diagram: https://gitdiagram.com/devanimecx/jiro
- Repository: https://github.com/devanimecx/jiro

## Overview

JIRO is a self-hosted search and scraping API, with cloud-compatible clients and AI-agent interfaces. The main workflow is a client request entering the API, being authenticated and routed to search or scraping, and returning normalized results; search can fan out to engine parsers and use hybrid ranking. Separate branches cover social scraping, AI answers, and MCP tools, with cache and database state supporting runtime services. The README documents capabilities beyond the sampled excerpts; links for those unsampled paths are included only where the tree and product description support them.

Main entry points: [`jiro/scraping/engines.py`](https://github.com/devanimecx/jiro/blob/main/jiro/scraping/engines.py) (Engine Orchestrator), [`jiro/server/routers/search.py`](https://github.com/devanimecx/jiro/blob/main/jiro/server/routers/search.py) (Search Routes), [`jiro/auth.py`](https://github.com/devanimecx/jiro/blob/main/jiro/auth.py) (Authentication), [`jiro/server/routers/scrape.py`](https://github.com/devanimecx/jiro/blob/main/jiro/server/routers/scrape.py) (Scrape Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Access"]
  node_search_api["Search Routes<br/>[search.py]"]
  node_scrape_api["Scrape Routes<br/>[scrape.py]"]
  node_ai_api["AI Routes<br/>[ai.py]"]
  node_social_api["Social Routes<br/>[social.py]"]
  node_auth["Authentication<br/>[auth.py]"]
end

subgraph group_search["Search"]
  node_search_engine["Engine Orchestrator<br/>[engines.py]"]
  node_engine_plugins["Search Engines<br/>[google_scholar.py]"]
  node_hybrid["Hybrid Search<br/>[hybrid.py]"]
  node_multiquery["Multi-Query<br/>[multiquery.py]"]
  node_semantic["Semantic Search<br/>[embeddings.py]"]
end

subgraph group_scrape["Scraping"]
  node_scrape_client["Scraping Client<br/>[client.py]"]
  node_scrape_engines["Scrape Engines<br/>[engines.py]"]
  node_parsers["SERP Parsers<br/>[google.py]"]
  node_social_router["Social Router<br/>[router.py]"]
  node_social_scrapers["Platform Scrapers<br/>[reddit.py]"]
end

subgraph group_ai["AI Interfaces"]
  node_ai_agent["Research Agent<br/>[agent.py]"]
  node_llm["LLM Providers<br/>[llm.py]"]
  node_mcp["MCP Server<br/>[mcp.py]"]
end

subgraph group_runtime["Runtime Services"]
  node_cache[("Cache<br/>[cache.py]")]
  node_database[("Database<br/>[db.py]")]
end

node_client(("API Client"))
node_external_engines(("Search Providers"))
node_web(("Web and Social Sites"))
node_llm_service(("LLM Services"))
node_mcp_client(("MCP Client"))

node_client -->|"requests search"| node_search_api
node_client -->|"requests scrape"| node_scrape_api
node_client -->|"requests AI"| node_ai_api
node_client -->|"requests social"| node_social_api
node_search_api -->|"checks access"| node_auth
node_scrape_api -->|"checks access"| node_auth
node_ai_api -->|"checks access"| node_auth
node_social_api -->|"checks access"| node_auth
node_search_api -->|"dispatches search"| node_search_engine
node_search_engine -->|"selects engine"| node_engine_plugins
node_engine_plugins -->|"fetches results"| node_external_engines
node_search_engine -->|"dispatches hybrid"| node_hybrid
node_hybrid -->|"embeds results"| node_semantic
node_search_engine -->|"reads and writes"| node_cache
node_search_api -->|"batch search"| node_multiquery
node_scrape_api -->|"dispatches scraping"| node_scrape_engines
node_scrape_engines -->|"fetches pages"| node_scrape_client
node_scrape_engines -->|"parses SERPs"| node_parsers
node_scrape_client -->|"fetches pages"| node_web
node_social_api -->|"routes URLs"| node_social_router
node_social_router -->|"selects scraper"| node_social_scrapers
node_social_scrapers -->|"fetches content"| node_scrape_client
node_ai_api -->|"runs research"| node_ai_agent
node_ai_agent -->|"searches sources"| node_search_engine
node_ai_agent -->|"requests synthesis"| node_llm
node_llm -.->|"calls provider"| node_llm_service
node_mcp_client -->|"invokes tools"| node_mcp
node_mcp -->|"searches"| node_search_engine
node_mcp -->|"scrapes"| node_scrape_engines
node_search_api -->|"records usage"| node_database

click node_search_api "https://github.com/devanimecx/jiro/blob/main/jiro/server/routers/search.py"
click node_scrape_api "https://github.com/devanimecx/jiro/blob/main/jiro/server/routers/scrape.py"
click node_ai_api "https://github.com/devanimecx/jiro/blob/main/jiro/server/routers/ai.py"
click node_social_api "https://github.com/devanimecx/jiro/blob/main/jiro/server/routers/social.py"
click node_auth "https://github.com/devanimecx/jiro/blob/main/jiro/auth.py"
click node_search_engine "https://github.com/devanimecx/jiro/blob/main/jiro/scraping/engines.py"
click node_engine_plugins "https://github.com/devanimecx/jiro/blob/main/jiro/plugins/engine/google_scholar.py"
click node_hybrid "https://github.com/devanimecx/jiro/blob/main/jiro/search/hybrid.py"
click node_multiquery "https://github.com/devanimecx/jiro/blob/main/jiro/search/multiquery.py"
click node_semantic "https://github.com/devanimecx/jiro/blob/main/jiro/search/embeddings.py"
click node_scrape_client "https://github.com/devanimecx/jiro/blob/main/jiro/scraping/client.py"
click node_scrape_engines "https://github.com/devanimecx/jiro/blob/main/jiro/scraping/engines.py"
click node_parsers "https://github.com/devanimecx/jiro/blob/main/jiro/scraping/parsers/google.py"
click node_social_router "https://github.com/devanimecx/jiro/blob/main/jiro/scraping/social/router.py"
click node_social_scrapers "https://github.com/devanimecx/jiro/blob/main/jiro/scraping/social/reddit.py"
click node_ai_agent "https://github.com/devanimecx/jiro/blob/main/jiro/ai/agent.py"
click node_llm "https://github.com/devanimecx/jiro/blob/main/jiro/ai/llm.py"
click node_mcp "https://github.com/devanimecx/jiro/blob/main/jiro/mcp.py"
click node_cache "https://github.com/devanimecx/jiro/blob/main/jiro/cache.py"
click node_database "https://github.com/devanimecx/jiro/blob/main/jiro/db.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_search_api,node_scrape_api,node_ai_api,node_social_api,node_auth,node_client,node_mcp_client toneBlue
class node_search_engine,node_engine_plugins,node_hybrid,node_multiquery,node_semantic toneAmber
class node_scrape_client,node_scrape_engines,node_parsers,node_social_router,node_social_scrapers toneMint
class node_ai_agent,node_llm,node_mcp toneRose
class node_cache,node_database,node_external_engines,node_web,node_llm_service toneIndigo
```

## Components

### API and Access

- [Search Routes](https://github.com/devanimecx/jiro/blob/main/jiro/server/routers/search.py): `jiro/server/routers/search.py`
- [Scrape Routes](https://github.com/devanimecx/jiro/blob/main/jiro/server/routers/scrape.py): `jiro/server/routers/scrape.py`
- [AI Routes](https://github.com/devanimecx/jiro/blob/main/jiro/server/routers/ai.py): `jiro/server/routers/ai.py`
- [Social Routes](https://github.com/devanimecx/jiro/blob/main/jiro/server/routers/social.py): `jiro/server/routers/social.py`
- [Authentication](https://github.com/devanimecx/jiro/blob/main/jiro/auth.py): `jiro/auth.py`

### Search

- [Engine Orchestrator](https://github.com/devanimecx/jiro/blob/main/jiro/scraping/engines.py): `jiro/scraping/engines.py`
- [Search Engines](https://github.com/devanimecx/jiro/blob/main/jiro/plugins/engine/google_scholar.py): `jiro/plugins/engine/google_scholar.py`
- [Hybrid Search](https://github.com/devanimecx/jiro/blob/main/jiro/search/hybrid.py): `jiro/search/hybrid.py`
- [Multi-Query](https://github.com/devanimecx/jiro/blob/main/jiro/search/multiquery.py): `jiro/search/multiquery.py`
- [Semantic Search](https://github.com/devanimecx/jiro/blob/main/jiro/search/embeddings.py): `jiro/search/embeddings.py`

### Scraping

- [Scraping Client](https://github.com/devanimecx/jiro/blob/main/jiro/scraping/client.py): `jiro/scraping/client.py`
- [Scrape Engines](https://github.com/devanimecx/jiro/blob/main/jiro/scraping/engines.py): `jiro/scraping/engines.py`
- [SERP Parsers](https://github.com/devanimecx/jiro/blob/main/jiro/scraping/parsers/google.py): `jiro/scraping/parsers/google.py`
- [Social Router](https://github.com/devanimecx/jiro/blob/main/jiro/scraping/social/router.py): `jiro/scraping/social/router.py`
- [Platform Scrapers](https://github.com/devanimecx/jiro/blob/main/jiro/scraping/social/reddit.py): `jiro/scraping/social/reddit.py`

### AI Interfaces

- [Research Agent](https://github.com/devanimecx/jiro/blob/main/jiro/ai/agent.py): `jiro/ai/agent.py`
- [LLM Providers](https://github.com/devanimecx/jiro/blob/main/jiro/ai/llm.py): `jiro/ai/llm.py`
- [MCP Server](https://github.com/devanimecx/jiro/blob/main/jiro/mcp.py): `jiro/mcp.py`

### Runtime Services

- [Cache](https://github.com/devanimecx/jiro/blob/main/jiro/cache.py): `jiro/cache.py`
- [Database](https://github.com/devanimecx/jiro/blob/main/jiro/db.py): `jiro/db.py`

### Other components

- **API Client**
- **Search Providers**
- **Web and Social Sites**
- **LLM Services**
- **MCP Client**

## Connections

- API Client → Search Routes: requests search
- API Client → Scrape Routes: requests scrape
- API Client → AI Routes: requests AI
- API Client → Social Routes: requests social
- Search Routes → Authentication: checks access
- Scrape Routes → Authentication: checks access
- AI Routes → Authentication: checks access
- Social Routes → Authentication: checks access
- Search Routes → Engine Orchestrator: dispatches search
- Engine Orchestrator → Search Engines: selects engine
- Search Engines → Search Providers: fetches results
- Engine Orchestrator → Hybrid Search: dispatches hybrid
- Hybrid Search → Semantic Search: embeds results
- Engine Orchestrator → Cache: reads and writes
- Search Routes → Multi-Query: batch search
- Scrape Routes → Scrape Engines: dispatches scraping
- Scrape Engines → Scraping Client: fetches pages
- Scrape Engines → SERP Parsers: parses SERPs
- Scraping Client → Web and Social Sites: fetches pages
- Social Routes → Social Router: routes URLs
- Social Router → Platform Scrapers: selects scraper
- Platform Scrapers → Scraping Client: fetches content
- AI Routes → Research Agent: runs research
- Research Agent → Engine Orchestrator: searches sources
- Research Agent → LLM Providers: requests synthesis
- LLM Providers → LLM Services: calls provider
- MCP Client → MCP Server: invokes tools
- MCP Server → Engine Orchestrator: searches
- MCP Server → Scrape Engines: scrapes
- Search Routes → Database: records usage