# eastbloods/player-scouting-recommendation-bot architecture

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

- Interactive diagram: https://gitdiagram.com/eastbloods/player-scouting-recommendation-bot
- Repository: https://github.com/eastbloods/player-scouting-recommendation-bot

## Overview

GoatScout is a football scouting platform: scouts submit natural-language queries with optional structured filters and receive ranked player profiles with scout notes. The main search path is documented and partially visible in the API and agent excerpts; ingestion fetches and normalizes player data before storing relational metadata and searchable vectors. The README also documents the two search modes and metadata capabilities. Some integrations and internal sequencing are shown only in documentation, so those edges cite the README rather than implying unshown source calls.

Main entry points: [`agents/search_agent.py`](https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/agents/search_agent.py) (Search Orchestrator), [`ingest.py`](https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/ingest.py) (Data Ingestion), [`routers/search.py`](https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/routers/search.py) (Search Endpoint), [`database/embedder.py`](https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/database/embedder.py) (Profile Embedding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_search["Scouting Search"]
  node_search_agent["Search Orchestrator<br/>[search_agent.py]"]
  node_filter_agent["Filter Extraction<br/>[filter_agent.py]"]
  node_retriever["Vector Retriever<br/>[retriever.py]"]
  node_result["Ranked Scout Notes<br/>[search_agent.py]"]
end

subgraph group_data["Player Data"]
  node_ingest["Data Ingestion<br/>[ingest.py]"]
  node_parser["Player Parser<br/>[parser.py]"]
  node_embedder["Profile Embedding<br/>[embedder.py]"]
end

subgraph group_stores["Search Stores"]
  node_models[("Player Metadata Models<br/>[models.py]")]
  node_db_session["Database Sessions<br/>[database.py]"]
  node_postgres[("PostgreSQL")]
  node_qdrant[("Qdrant Vector Store")]
end

subgraph group_api["API Surface"]
  node_search_route["Search Endpoint<br/>[search.py]"]
  node_meta_route["Metadata Endpoints<br/>[meta.py]"]
  node_app["FastAPI App<br/>[main.py]"]
end

node_scout(("Scout"))
node_groq{{"Groq LLM"}}
node_sportmonks{{"SportMonks API"}}
node_embedding_model{{"Sentence Transformer"}}
node_browser(("Web Scout<br/>[index.html]"))

node_scout -->|"submits query"| node_search_route
node_search_route -->|"invokes search"| node_search_agent
node_search_agent -->|"builds filters"| node_filter_agent
node_search_agent -->|"extracts and formats"| node_groq
node_search_agent -->|"retrieves candidates"| node_retriever
node_retriever -->|"queries vectors"| node_qdrant
node_search_agent -->|"formats candidates"| node_result
node_search_route -->|"returns results"| node_scout
node_sportmonks -->|"supplies football data"| node_ingest
node_ingest -->|"parses players"| node_parser
node_ingest -->|"upserts records"| node_db_session
node_db_session -->|"connects to"| node_postgres
node_ingest -->|"persists entities"| node_models
node_ingest -->|"indexes profiles"| node_embedder
node_embedder -->|"encodes profiles"| node_embedding_model
node_embedder -->|"upserts vectors"| node_qdrant
node_app -->|"registers route"| node_search_route
node_app -->|"registers route"| node_meta_route
node_meta_route -->|"reads metadata"| node_qdrant
node_browser -->|"loads interface"| node_app

click node_search_route "https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/routers/search.py"
click node_search_agent "https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/agents/search_agent.py"
click node_filter_agent "https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/agents/filter_agent.py"
click node_retriever "https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/vector_store/retriever.py"
click node_result "https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/agents/search_agent.py"
click node_ingest "https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/ingest.py"
click node_parser "https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/api/parser.py"
click node_models "https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/database/models.py"
click node_db_session "https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/database/database.py"
click node_embedder "https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/database/embedder.py"
click node_meta_route "https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/routers/meta.py"
click node_app "https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/main.py"
click node_browser "https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/index.html"

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_agent,node_filter_agent,node_retriever,node_result toneBlue
class node_ingest,node_parser,node_embedder toneAmber
class node_models,node_db_session,node_postgres,node_qdrant,node_sportmonks toneMint
class node_search_route,node_meta_route,node_app toneRose
class node_scout,node_groq,node_embedding_model toneIndigo
class node_browser toneTeal
```

## Components

### Scouting Search

- [Search Orchestrator](https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/agents/search_agent.py): `agents/search_agent.py`
- [Filter Extraction](https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/agents/filter_agent.py): `agents/filter_agent.py`
- [Vector Retriever](https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/vector_store/retriever.py): `vector_store/retriever.py`
- [Ranked Scout Notes](https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/agents/search_agent.py): `agents/search_agent.py`

### Player Data

- [Data Ingestion](https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/ingest.py): `ingest.py`
- [Player Parser](https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/api/parser.py): `api/parser.py`
- [Profile Embedding](https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/database/embedder.py): `database/embedder.py`

### Search Stores

- [Player Metadata Models](https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/database/models.py): `database/models.py`
- [Database Sessions](https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/database/database.py): `database/database.py`
- **PostgreSQL**
- **Qdrant Vector Store**

### API Surface

- [Search Endpoint](https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/routers/search.py): `routers/search.py`
- [Metadata Endpoints](https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/routers/meta.py): `routers/meta.py`
- [FastAPI App](https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/main.py): `main.py`

### Other components

- **Scout**
- **Groq LLM**
- **SportMonks API**
- **Sentence Transformer**
- [Web Scout](https://github.com/eastbloods/player-scouting-recommendation-bot/blob/main/index.html): `index.html`

## Connections

- Scout → Search Endpoint: submits query (evidence: `README.md`)
- Search Endpoint → Search Orchestrator: invokes search (evidence: `routers/search.py`)
- Search Orchestrator → Filter Extraction: builds filters (evidence: `agents/search_agent.py`)
- Search Orchestrator → Groq LLM: extracts and formats (evidence: `README.md`)
- Search Orchestrator → Vector Retriever: retrieves candidates (evidence: `agents/search_agent.py`)
- Vector Retriever → Qdrant Vector Store: queries vectors (evidence: `vector_store/retriever.py`)
- Search Orchestrator → Ranked Scout Notes: formats candidates (evidence: `agents/search_agent.py`)
- Search Endpoint → Scout: returns results (evidence: `README.md`)
- SportMonks API → Data Ingestion: supplies football data (evidence: `README.md`)
- Data Ingestion → Player Parser: parses players (evidence: `ingest.py`)
- Data Ingestion → Database Sessions: upserts records (evidence: `ingest.py`)
- Database Sessions → PostgreSQL: connects to (evidence: `database/database.py`)
- Data Ingestion → Player Metadata Models: persists entities (evidence: `ingest.py`)
- Data Ingestion → Profile Embedding: indexes profiles (evidence: `ingest.py`)
- Profile Embedding → Sentence Transformer: encodes profiles (evidence: `README.md`)
- Profile Embedding → Qdrant Vector Store: upserts vectors (evidence: `database/embedder.py`)
- FastAPI App → Search Endpoint: registers route (evidence: `main.py`)
- FastAPI App → Metadata Endpoints: registers route (evidence: `main.py`)
- Metadata Endpoints → Qdrant Vector Store: reads metadata (evidence: `routers/meta.py`)
- Web Scout → FastAPI App: loads interface (evidence: `main.py`)
