# almarch/pokedex architecture

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

- Interactive diagram: https://gitdiagram.com/almarch/pokedex
- Repository: https://github.com/almarch/pokedex
- Video tour (about a minute): https://gitdiagram.com/almarch/pokedex/video

## Overview

Pokédex is a multilingual Pokémon question-answering service. A user sends a request through Open-WebUI to the agent, which summarizes it, checks for named Pokémon and retrieves relevant descriptions, reranks the results, and adds them as instructions before proxying the request to Ollama; streamed answers return through the proxy. The README also documents notebook-based vector-database population. The request-processing and retrieval links are supported by sampled source; notebook ingestion and deployment wiring are documented but not sampled in detail.

Main entry points: [`agent/agent/Agent.py`](https://github.com/almarch/pokedex/blob/main/agent/agent/Agent.py) (Request orchestrator), [`agent/agent/app.py`](https://github.com/almarch/pokedex/blob/main/agent/agent/app.py) (Agent proxy), [`agent/agent/ollama.py`](https://github.com/almarch/pokedex/blob/main/agent/agent/ollama.py) (Ollama client), [`agent/agent/regex.py`](https://github.com/almarch/pokedex/blob/main/agent/agent/regex.py) (Name matching)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_webui["Open-WebUI"]
  node_ingress["Ingress and TLS"]
end

subgraph group_agent["Agent processing"]
  node_proxy["Agent proxy<br/>[app.py]"]
  node_agent_core["Request orchestrator<br/>[Agent.py]"]
  node_summary["Intent and language<br/>[summarize.py]"]
  node_instructions["Answer instructions<br/>[instructions.py]"]
  node_logs["Request logs"]
end

subgraph group_knowledge["Knowledge retrieval"]
  node_name_check["Name matching<br/>[regex.py]"]
  node_retrieval["Document retrieval<br/>[retrieve.py]"]
  node_rerank["Relevance ranking<br/>[rerank.py]"]
  node_qdrant_client["Qdrant client<br/>[qdrant.py]"]
  node_notebook["Data preparation<br/>[pokemons.ipynb]"]
end

subgraph group_services["Inference and data"]
  node_ollama_client["Ollama client<br/>[ollama.py]"]
  node_ollama["Ollama inference"]
  node_qdrant[("Qdrant vector store")]
end

node_user(("User"))

node_user -->|"sends request"| node_ingress
node_ingress -->|"routes traffic"| node_webui
node_webui -->|"submits chat"| node_proxy
node_proxy -->|"processes streaming request"| node_agent_core
node_proxy -->|"writes transactions"| node_logs
node_agent_core -->|"summarizes conversation"| node_summary
node_agent_core -->|"checks mentioned names"| node_name_check
node_agent_core -->|"searches query elements"| node_retrieval
node_agent_core -->|"ranks documents"| node_rerank
node_agent_core -->|"formats answer context"| node_instructions
node_summary -->|"requests structured generation"| node_ollama_client
node_name_check -->|"reads name collection"| node_qdrant_client
node_name_check -->|"verifies candidates"| node_ollama_client
node_retrieval -->|"embeds query"| node_ollama_client
node_retrieval -->|"queries descriptions"| node_qdrant_client
node_rerank -->|"scores documents"| node_ollama_client
node_qdrant_client -->|"reads and writes vectors"| node_qdrant
node_ollama_client -->|"calls model APIs"| node_ollama
node_notebook -.->|"populates knowledge"| node_qdrant
node_proxy -->|"forwards processed request"| node_ollama
node_ollama -->|"streams response"| node_proxy
node_proxy -->|"returns stream"| node_webui

click node_webui "https://github.com/almarch/pokedex/tree/main/k8s/webui"
click node_proxy "https://github.com/almarch/pokedex/blob/main/agent/agent/app.py"
click node_agent_core "https://github.com/almarch/pokedex/blob/main/agent/agent/Agent.py"
click node_summary "https://github.com/almarch/pokedex/blob/main/agent/agent/summarize.py"
click node_name_check "https://github.com/almarch/pokedex/blob/main/agent/agent/regex.py"
click node_retrieval "https://github.com/almarch/pokedex/blob/main/agent/agent/retrieve.py"
click node_rerank "https://github.com/almarch/pokedex/blob/main/agent/agent/rerank.py"
click node_instructions "https://github.com/almarch/pokedex/blob/main/agent/agent/instructions.py"
click node_ollama_client "https://github.com/almarch/pokedex/blob/main/agent/agent/ollama.py"
click node_ollama "https://github.com/almarch/pokedex/tree/main/k8s/ollama"
click node_qdrant_client "https://github.com/almarch/pokedex/blob/main/agent/agent/qdrant.py"
click node_qdrant "https://github.com/almarch/pokedex/tree/main/k8s/qdrant"
click node_notebook "https://github.com/almarch/pokedex/blob/main/notebook/pokemons.ipynb"
click node_logs "https://github.com/almarch/pokedex/tree/main/logs"
click node_ingress "https://github.com/almarch/pokedex/tree/main/k8s/cert"

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_webui,node_ingress,node_user toneBlue
class node_proxy,node_agent_core,node_summary,node_instructions,node_logs toneAmber
class node_name_check,node_retrieval,node_rerank,node_qdrant_client,node_notebook toneMint
class node_ollama_client,node_ollama,node_qdrant toneRose
```

## Components

### User experience

- [Open-WebUI](https://github.com/almarch/pokedex/tree/main/k8s/webui): `k8s/webui`
- [Ingress and TLS](https://github.com/almarch/pokedex/tree/main/k8s/cert): `k8s/cert`

### Agent processing

- [Agent proxy](https://github.com/almarch/pokedex/blob/main/agent/agent/app.py): `agent/agent/app.py`
- [Request orchestrator](https://github.com/almarch/pokedex/blob/main/agent/agent/Agent.py): `agent/agent/Agent.py`
- [Intent and language](https://github.com/almarch/pokedex/blob/main/agent/agent/summarize.py): `agent/agent/summarize.py`
- [Answer instructions](https://github.com/almarch/pokedex/blob/main/agent/agent/instructions.py): `agent/agent/instructions.py`
- [Request logs](https://github.com/almarch/pokedex/tree/main/logs): `logs`

### Knowledge retrieval

- [Name matching](https://github.com/almarch/pokedex/blob/main/agent/agent/regex.py): `agent/agent/regex.py`
- [Document retrieval](https://github.com/almarch/pokedex/blob/main/agent/agent/retrieve.py): `agent/agent/retrieve.py`
- [Relevance ranking](https://github.com/almarch/pokedex/blob/main/agent/agent/rerank.py): `agent/agent/rerank.py`
- [Qdrant client](https://github.com/almarch/pokedex/blob/main/agent/agent/qdrant.py): `agent/agent/qdrant.py`
- [Data preparation](https://github.com/almarch/pokedex/blob/main/notebook/pokemons.ipynb): `notebook/pokemons.ipynb`

### Inference and data

- [Ollama client](https://github.com/almarch/pokedex/blob/main/agent/agent/ollama.py): `agent/agent/ollama.py`
- [Ollama inference](https://github.com/almarch/pokedex/tree/main/k8s/ollama): `k8s/ollama`
- [Qdrant vector store](https://github.com/almarch/pokedex/tree/main/k8s/qdrant): `k8s/qdrant`

### Other components

- **User**

## Connections

- User → Ingress and TLS: sends request
- Ingress and TLS → Open-WebUI: routes traffic
- Open-WebUI → Agent proxy: submits chat
- Agent proxy → Request orchestrator: processes streaming request
- Agent proxy → Request logs: writes transactions
- Request orchestrator → Intent and language: summarizes conversation
- Request orchestrator → Name matching: checks mentioned names
- Request orchestrator → Document retrieval: searches query elements
- Request orchestrator → Relevance ranking: ranks documents
- Request orchestrator → Answer instructions: formats answer context
- Intent and language → Ollama client: requests structured generation
- Name matching → Qdrant client: reads name collection
- Name matching → Ollama client: verifies candidates
- Document retrieval → Ollama client: embeds query
- Document retrieval → Qdrant client: queries descriptions
- Relevance ranking → Ollama client: scores documents
- Qdrant client → Qdrant vector store: reads and writes vectors
- Ollama client → Ollama inference: calls model APIs
- Data preparation → Qdrant vector store: populates knowledge
- Agent proxy → Ollama inference: forwards processed request
- Ollama inference → Agent proxy: streams response
- Agent proxy → Open-WebUI: returns stream