# lucasnovack/youmightlike architecture

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

- Interactive diagram: https://gitdiagram.com/lucasnovack/youmightlike
- Repository: https://github.com/lucasnovack/youmightlike

## Overview

youmightlike is a local-first, cross-media recommendation product: cultural data is ingested into DuckDB, transformed into a graph, and used by a Rust engine to serve search and personalized recommendations to a web interface. The principal path runs from user-selected taste seeds through HTTP service orchestration, graph diffusion and domain-specific candidate extraction to results. The README also describes UI capabilities including live neighborhood inspection and printable taste receipts. Some Python web-to-engine wiring and unsampled route details are not shown, so those relationships are left unverified.

Main entry points: [`crates/engine/src/service.rs`](https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/service.rs) (HTTP API), [`python/src/youmightlike/storage/database.py`](https://github.com/lucasnovack/youmightlike/blob/main/python/src/youmightlike/storage/database.py) (DuckDB Feature Store), [`crates/engine/src/recommendation/mod.rs`](https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/recommendation/mod.rs) (Seed Orchestration), [`crates/engine/src/graph.rs`](https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/graph.rs) (CSR Affinity Graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Data Ingestion"]
  node_pipeline["Batch Ingestion<br/>[pipeline.py]"]
  node_connectors["Data Connectors"]
  node_ingest["Dataset Ingestors"]
end

subgraph group_engine["Rust Recommendation Engine"]
  node_rustserver["HTTP API<br/>[service.rs]"]
  node_search["Catalog Search<br/>[search.rs]"]
  node_catalog["Catalog &amp; State<br/>[models.rs]"]
  node_graphload["Graph Construction<br/>[graph_builder.rs]"]
  node_graph["CSR Affinity Graph<br/>[graph.rs]"]
  node_orchestrator["Seed Orchestration<br/>[mod.rs]"]
  node_ppr["PageRank Diffusion<br/>[ppr.rs]"]
  node_domain["Media Extractors"]
  node_trackrec["Track Recommendations<br/>[tracks.rs]"]
  node_recommender["Recommendation API<br/>[recommender.rs]"]
end

subgraph group_interface["Web Experience"]
  node_web["Web Server<br/>[server.py]"]
  node_app["Discovery Panel<br/>[app.js]"]
  node_receipt["Cultural Receipt<br/>[receipt.js]"]
  node_pwa["Offline Cache<br/>[sw.js]"]
end

subgraph group_pythonrec["Python Recommendation"]
  node_pyrec["Python Recommender<br/>[engine.py]"]
  node_resolver["Seed Resolver<br/>[resolver.py]"]
end

node_user(("User"))
node_db[("DuckDB Feature Store<br/>[database.py]")]

node_pipeline -->|"uses"| node_connectors
node_pipeline -->|"initializes"| node_db
node_connectors -->|"writes"| node_db
node_ingest -->|"writes"| node_db
node_db -.->|"supplies edges"| node_graphload
node_rustserver -->|"loads"| node_graph
node_rustserver -->|"loads"| node_catalog
node_rustserver -->|"routes search"| node_search
node_rustserver -->|"routes recommendations"| node_recommender
node_graphload -->|"builds"| node_graph
node_orchestrator -->|"diffuses seeds"| node_ppr
node_orchestrator -->|"extracts candidates"| node_domain
node_orchestrator -->|"delegates tracks"| node_trackrec
node_recommender -->|"delegates"| node_orchestrator
node_search -->|"reads metadata"| node_catalog
node_search -->|"checks connectivity"| node_graph
node_domain -->|"uses metadata"| node_catalog
node_domain -.->|"scores neighbors"| node_graph
node_user -.->|"selects taste"| node_app
node_app -.->|"requests API"| node_web
node_web -.->|"forwards requests"| node_rustserver
node_web -.->|"provides receipt data"| node_receipt
node_app -.->|"uses offline cache"| node_pwa
node_pyrec -->|"resolves seeds"| node_resolver
node_pyrec -.->|"queries"| node_db
node_pyrec -.->|"calls Rust service"| node_rustserver

click node_pipeline "https://github.com/lucasnovack/youmightlike/blob/main/python/src/youmightlike/pipeline.py"
click node_connectors "https://github.com/lucasnovack/youmightlike/tree/main/python/src/youmightlike/connectors"
click node_ingest "https://github.com/lucasnovack/youmightlike/tree/main/python/src/youmightlike/storage"
click node_db "https://github.com/lucasnovack/youmightlike/blob/main/python/src/youmightlike/storage/database.py"
click node_rustserver "https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/service.rs"
click node_search "https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/search.rs"
click node_catalog "https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/models.rs"
click node_graphload "https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/recommendation/graph_builder.rs"
click node_graph "https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/graph.rs"
click node_orchestrator "https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/recommendation/mod.rs"
click node_ppr "https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/ppr.rs"
click node_domain "https://github.com/lucasnovack/youmightlike/tree/main/crates/engine/src/recommendation/extractors"
click node_trackrec "https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/recommendation/tracks.rs"
click node_recommender "https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/recommender.rs"
click node_web "https://github.com/lucasnovack/youmightlike/blob/main/python/src/youmightlike/web/server.py"
click node_app "https://github.com/lucasnovack/youmightlike/blob/main/python/src/youmightlike/web/static/js/app.js"
click node_receipt "https://github.com/lucasnovack/youmightlike/blob/main/python/src/youmightlike/web/static/js/receipt.js"
click node_pwa "https://github.com/lucasnovack/youmightlike/blob/main/python/src/youmightlike/web/static/sw.js"
click node_pyrec "https://github.com/lucasnovack/youmightlike/blob/main/python/src/youmightlike/recommendation/engine.py"
click node_resolver "https://github.com/lucasnovack/youmightlike/blob/main/python/src/youmightlike/resolution/resolver.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_pipeline,node_connectors,node_ingest,node_user toneBlue
class node_rustserver,node_search,node_catalog,node_graphload,node_graph,node_orchestrator,node_ppr,node_domain,node_trackrec,node_recommender,node_db toneAmber
class node_web,node_app,node_receipt,node_pwa toneMint
class node_pyrec,node_resolver toneRose
```

## Components

### Data Ingestion

- [Batch Ingestion](https://github.com/lucasnovack/youmightlike/blob/main/python/src/youmightlike/pipeline.py): `python/src/youmightlike/pipeline.py`
- [Data Connectors](https://github.com/lucasnovack/youmightlike/tree/main/python/src/youmightlike/connectors): `python/src/youmightlike/connectors`
- [Dataset Ingestors](https://github.com/lucasnovack/youmightlike/tree/main/python/src/youmightlike/storage): `python/src/youmightlike/storage`

### Rust Recommendation Engine

- [HTTP API](https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/service.rs): `crates/engine/src/service.rs`
- [Catalog Search](https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/search.rs): `crates/engine/src/search.rs`
- [Catalog & State](https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/models.rs): `crates/engine/src/models.rs`
- [Graph Construction](https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/recommendation/graph_builder.rs): `crates/engine/src/recommendation/graph_builder.rs`
- [CSR Affinity Graph](https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/graph.rs): `crates/engine/src/graph.rs`
- [Seed Orchestration](https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/recommendation/mod.rs): `crates/engine/src/recommendation/mod.rs`
- [PageRank Diffusion](https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/ppr.rs): `crates/engine/src/ppr.rs`
- [Media Extractors](https://github.com/lucasnovack/youmightlike/tree/main/crates/engine/src/recommendation/extractors): `crates/engine/src/recommendation/extractors`
- [Track Recommendations](https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/recommendation/tracks.rs): `crates/engine/src/recommendation/tracks.rs`
- [Recommendation API](https://github.com/lucasnovack/youmightlike/blob/main/crates/engine/src/recommender.rs): `crates/engine/src/recommender.rs`

### Web Experience

- [Web Server](https://github.com/lucasnovack/youmightlike/blob/main/python/src/youmightlike/web/server.py): `python/src/youmightlike/web/server.py`
- [Discovery Panel](https://github.com/lucasnovack/youmightlike/blob/main/python/src/youmightlike/web/static/js/app.js): `python/src/youmightlike/web/static/js/app.js`
- [Cultural Receipt](https://github.com/lucasnovack/youmightlike/blob/main/python/src/youmightlike/web/static/js/receipt.js): `python/src/youmightlike/web/static/js/receipt.js`
- [Offline Cache](https://github.com/lucasnovack/youmightlike/blob/main/python/src/youmightlike/web/static/sw.js): `python/src/youmightlike/web/static/sw.js`

### Python Recommendation

- [Python Recommender](https://github.com/lucasnovack/youmightlike/blob/main/python/src/youmightlike/recommendation/engine.py): `python/src/youmightlike/recommendation/engine.py`
- [Seed Resolver](https://github.com/lucasnovack/youmightlike/blob/main/python/src/youmightlike/resolution/resolver.py): `python/src/youmightlike/resolution/resolver.py`

### Other components

- **User**
- [DuckDB Feature Store](https://github.com/lucasnovack/youmightlike/blob/main/python/src/youmightlike/storage/database.py): `python/src/youmightlike/storage/database.py`

## Connections

- Batch Ingestion → Data Connectors: uses (evidence: `python/src/youmightlike/pipeline.py`)
- Batch Ingestion → DuckDB Feature Store: initializes (evidence: `python/src/youmightlike/pipeline.py`)
- Data Connectors → DuckDB Feature Store: writes (evidence: `python/src/youmightlike/connectors/music.py`)
- Dataset Ingestors → DuckDB Feature Store: writes (evidence: `python/src/youmightlike/storage/ingest_music.py`)
- DuckDB Feature Store → Graph Construction: supplies edges
- HTTP API → CSR Affinity Graph: loads (evidence: `crates/engine/src/service.rs`)
- HTTP API → Catalog & State: loads (evidence: `crates/engine/src/service.rs`)
- HTTP API → Catalog Search: routes search (evidence: `crates/engine/src/service.rs`)
- HTTP API → Recommendation API: routes recommendations (evidence: `crates/engine/src/service.rs`)
- Graph Construction → CSR Affinity Graph: builds (evidence: `crates/engine/src/recommendation/graph_builder.rs`)
- Seed Orchestration → PageRank Diffusion: diffuses seeds (evidence: `crates/engine/src/recommendation/mod.rs`)
- Seed Orchestration → Media Extractors: extracts candidates (evidence: `crates/engine/src/recommendation/mod.rs`)
- Seed Orchestration → Track Recommendations: delegates tracks (evidence: `crates/engine/src/recommendation/mod.rs`)
- Recommendation API → Seed Orchestration: delegates (evidence: `crates/engine/src/recommender.rs`)
- Catalog Search → Catalog & State: reads metadata (evidence: `crates/engine/src/search.rs`)
- Catalog Search → CSR Affinity Graph: checks connectivity (evidence: `crates/engine/src/search.rs`)
- Media Extractors → Catalog & State: uses metadata (evidence: `crates/engine/src/recommendation/extractors/music.rs`)
- Media Extractors → CSR Affinity Graph: scores neighbors (evidence: `crates/engine/src/recommendation/extractors/games.rs`)
- User → Discovery Panel: selects taste
- Discovery Panel → Web Server: requests API
- Web Server → HTTP API: forwards requests
- Web Server → Cultural Receipt: provides receipt data
- Discovery Panel → Offline Cache: uses offline cache
- Python Recommender → Seed Resolver: resolves seeds (evidence: `python/src/youmightlike/recommendation/engine.py`)
- Python Recommender → DuckDB Feature Store: queries
- Python Recommender → HTTP API: calls Rust service
