# besteaydogan/recoengine architecture

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

- Interactive diagram: https://gitdiagram.com/besteaydogan/recoengine
- Repository: https://github.com/besteaydogan/recoengine

## Overview

RecoEngine streams product-view events into PostgreSQL, then serves user history, personalized recommendations, and ETL-calculated bestsellers through FastAPI to a React dashboard. The graph includes event ingestion, scheduled bestseller computation, API/cache and frontend layers. Some wiring—especially simulator-to-producer and frontend HTTP calls—is documented at a high level; unsampled details are not inferred beyond that evidence.

Main entry points: [`api/endpoints.py`](https://github.com/besteaydogan/recoengine/blob/main/api/endpoints.py) (HTTP endpoints), [`database.py`](https://github.com/besteaydogan/recoengine/blob/main/database.py) (Async DB access), [`kafka_stream/consumer.py`](https://github.com/besteaydogan/recoengine/blob/main/kafka_stream/consumer.py) (Event consumer), [`batch/etl.py`](https://github.com/besteaydogan/recoengine/blob/main/batch/etl.py) (Bestseller ETL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Event ingestion"]
  node_producer["Kafka producer<br/>[producer.py]"]
  node_broker["Kafka broker"]
  node_consumer["Event consumer<br/>[consumer.py]"]
end

subgraph group_data["Persistence and ETL"]
  node_db_access["Async DB access<br/>[database.py]"]
  node_models["ORM entities<br/>[orm_models.py]"]
  node_postgres[("PostgreSQL")]
  node_scheduler["ETL scheduler<br/>[scheduler.py]"]
  node_etl["Bestseller ETL<br/>[etl.py]"]
end

subgraph group_backend["API and caching"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_routes["HTTP endpoints<br/>[endpoints.py]"]
  node_crud["Domain queries<br/>[crud.py]"]
  node_cache["Bestseller cache<br/>[cache.py]"]
  node_redis[("Redis")]
end

subgraph group_frontend["React dashboard"]
  node_app["Dashboard app<br/>[App.jsx]"]
  node_panels["Dashboard panels"]
  node_queries["Query hooks<br/>[useRecoQueries.js]"]
  node_client["API client<br/>[recoApi.js]"]
  node_ui_state["UI state<br/>[useAppStore.js]"]
end

node_simulator(("Event simulator"))
node_browser(("Dashboard user"))

node_simulator -.->|"supplies events"| node_producer
node_producer -->|"publishes events"| node_broker
node_broker -->|"delivers events"| node_consumer
node_consumer -->|"stores events"| node_db_access
node_db_access -->|"connects to"| node_postgres
node_consumer -->|"uses entities"| node_models
node_scheduler -->|"runs job"| node_etl
node_etl -->|"writes bestseller data"| node_db_access
node_etl -->|"invalidates cache"| node_redis
node_api_app -->|"mounts routes"| node_routes
node_routes -->|"calls queries"| node_crud
node_routes -->|"injects sessions"| node_db_access
node_crud -->|"queries entities"| node_models
node_routes -->|"reads and writes"| node_cache
node_cache -->|"uses cache store"| node_redis
node_browser -.->|"uses dashboard"| node_app
node_app -->|"renders panels"| node_panels
node_panels -->|"uses queries"| node_queries
node_queries -->|"calls API client"| node_client
node_client -.->|"requests data"| node_api_app
node_panels -->|"reads UI state"| node_ui_state
node_app -.->|"fetches bestsellers"| node_api_app

click node_producer "https://github.com/besteaydogan/recoengine/blob/main/kafka_stream/producer.py"
click node_consumer "https://github.com/besteaydogan/recoengine/blob/main/kafka_stream/consumer.py"
click node_api_app "https://github.com/besteaydogan/recoengine/blob/main/main.py"
click node_routes "https://github.com/besteaydogan/recoengine/blob/main/api/endpoints.py"
click node_crud "https://github.com/besteaydogan/recoengine/blob/main/api/crud.py"
click node_cache "https://github.com/besteaydogan/recoengine/blob/main/cache.py"
click node_db_access "https://github.com/besteaydogan/recoengine/blob/main/database.py"
click node_models "https://github.com/besteaydogan/recoengine/blob/main/api/orm_models.py"
click node_scheduler "https://github.com/besteaydogan/recoengine/blob/main/scheduler.py"
click node_etl "https://github.com/besteaydogan/recoengine/blob/main/batch/etl.py"
click node_app "https://github.com/besteaydogan/recoengine/blob/main/frontend2/src/App.jsx"
click node_panels "https://github.com/besteaydogan/recoengine/tree/main/frontend2/src/components/dashboard"
click node_queries "https://github.com/besteaydogan/recoengine/blob/main/frontend2/src/hooks/useRecoQueries.js"
click node_client "https://github.com/besteaydogan/recoengine/blob/main/frontend2/src/api/recoApi.js"
click node_ui_state "https://github.com/besteaydogan/recoengine/blob/main/frontend2/src/store/useAppStore.js"

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_producer,node_broker,node_consumer,node_browser toneBlue
class node_db_access,node_models,node_postgres,node_scheduler,node_etl toneAmber
class node_api_app,node_routes,node_crud,node_cache,node_redis toneMint
class node_app,node_panels,node_queries,node_client,node_ui_state toneRose
class node_simulator toneIndigo
```

## Components

### Event ingestion

- [Kafka producer](https://github.com/besteaydogan/recoengine/blob/main/kafka_stream/producer.py): `kafka_stream/producer.py`
- **Kafka broker**
- [Event consumer](https://github.com/besteaydogan/recoengine/blob/main/kafka_stream/consumer.py): `kafka_stream/consumer.py`

### Persistence and ETL

- [Async DB access](https://github.com/besteaydogan/recoengine/blob/main/database.py): `database.py`
- [ORM entities](https://github.com/besteaydogan/recoengine/blob/main/api/orm_models.py): `api/orm_models.py`
- **PostgreSQL**
- [ETL scheduler](https://github.com/besteaydogan/recoengine/blob/main/scheduler.py): `scheduler.py`
- [Bestseller ETL](https://github.com/besteaydogan/recoengine/blob/main/batch/etl.py): `batch/etl.py`

### API and caching

- [FastAPI app](https://github.com/besteaydogan/recoengine/blob/main/main.py): `main.py`
- [HTTP endpoints](https://github.com/besteaydogan/recoengine/blob/main/api/endpoints.py): `api/endpoints.py`
- [Domain queries](https://github.com/besteaydogan/recoengine/blob/main/api/crud.py): `api/crud.py`
- [Bestseller cache](https://github.com/besteaydogan/recoengine/blob/main/cache.py): `cache.py`
- **Redis**

### React dashboard

- [Dashboard app](https://github.com/besteaydogan/recoengine/blob/main/frontend2/src/App.jsx): `frontend2/src/App.jsx`
- [Dashboard panels](https://github.com/besteaydogan/recoengine/tree/main/frontend2/src/components/dashboard): `frontend2/src/components/dashboard`
- [Query hooks](https://github.com/besteaydogan/recoengine/blob/main/frontend2/src/hooks/useRecoQueries.js): `frontend2/src/hooks/useRecoQueries.js`
- [API client](https://github.com/besteaydogan/recoengine/blob/main/frontend2/src/api/recoApi.js): `frontend2/src/api/recoApi.js`
- [UI state](https://github.com/besteaydogan/recoengine/blob/main/frontend2/src/store/useAppStore.js): `frontend2/src/store/useAppStore.js`

### Other components

- **Event simulator**
- **Dashboard user**

## Connections

- Event simulator → Kafka producer: supplies events (evidence: `README.md`)
- Kafka producer → Kafka broker: publishes events (evidence: `README.md`)
- Kafka broker → Event consumer: delivers events (evidence: `README.md`)
- Event consumer → Async DB access: stores events (evidence: `kafka_stream/consumer.py`)
- Async DB access → PostgreSQL: connects to (evidence: `database.py`)
- Event consumer → ORM entities: uses entities (evidence: `kafka_stream/consumer.py`)
- ETL scheduler → Bestseller ETL: runs job (evidence: `scheduler.py`)
- Bestseller ETL → Async DB access: writes bestseller data (evidence: `batch/etl.py`)
- Bestseller ETL → Redis: invalidates cache (evidence: `batch/etl.py`)
- FastAPI app → HTTP endpoints: mounts routes (evidence: `main.py`)
- HTTP endpoints → Domain queries: calls queries (evidence: `api/endpoints.py`)
- HTTP endpoints → Async DB access: injects sessions (evidence: `api/endpoints.py`)
- Domain queries → ORM entities: queries entities (evidence: `api/crud.py`)
- HTTP endpoints → Bestseller cache: reads and writes (evidence: `api/endpoints.py`)
- Bestseller cache → Redis: uses cache store (evidence: `cache.py`)
- Dashboard user → Dashboard app: uses dashboard
- Dashboard app → Dashboard panels: renders panels (evidence: `frontend2/src/App.jsx`)
- Dashboard panels → Query hooks: uses queries (evidence: `frontend2/src/components/dashboard/UserRecommendationPanel.jsx`)
- Query hooks → API client: calls API client (evidence: `frontend2/src/hooks/useRecoQueries.js`)
- API client → FastAPI app: requests data (evidence: `README.md`)
- Dashboard panels → UI state: reads UI state (evidence: `frontend2/src/components/dashboard/UserRecommendationPanel.jsx`)
- Dashboard app → FastAPI app: fetches bestsellers (evidence: `README.md`)