# soloiaros/archies-appstore-lookup architecture

> Architecture diagram of the GitHub repository soloiaros/archies-appstore-lookup, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/soloiaros/archies-appstore-lookup
- Repository: https://github.com/soloiaros/archies-appstore-lookup

## Overview

10K / App Store Indexor turns natural-language queries into factual, comparative, or scored discovery results from an indexed catalog of Apple listings. The main workflow runs from the search UI through the query API and router to retrieval, optional Jev scoring, and rendered results; factual detail and comparative momentum are separate branches. A second product workflow grows the catalog from chart and Lookup feeds, then enriches it with embeddings, visual signals, and estimates. The README documents these capabilities; unsampled implementation details and some subsystem wiring are therefore shown only where documented.

Main entry points: [`lib/router/index.ts`](https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/router/index.ts) (Query router), [`lib/scrape/store.ts`](https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/scrape/store.ts) (Catalog storage), [`lib/catalog/detail.ts`](https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/catalog/detail.ts) (App details), [`lib/scrape/index.ts`](https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/scrape/index.ts) (Catalog ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_search["Search and answers"]
  node_query_api["Query endpoint<br/>[route.ts]"]
  node_router["Query router<br/>[index.ts]"]
  node_classify["Query classification<br/>[classify.ts]"]
  node_factual["Factual lookup<br/>[factual.ts]"]
  node_comparative["Comparative ranking<br/>[comparative.ts]"]
  node_discovery["Discovery retrieval<br/>[finalists.ts]"]
  node_jev["Jev scoring<br/>[score.ts]"]
end

subgraph group_catalog["Catalog and enrichment"]
  node_catalog_runtime[("Catalog access<br/>[cloud.ts]")]
  node_detail["App details<br/>[detail.ts]"]
  node_provenance["Provenance rules<br/>[provenance.ts]"]
  node_scrape["Catalog ingestion<br/>[index.ts]"]
  node_catalog_store[("Catalog storage<br/>[store.ts]")]
  node_enrichment["Offline enrichment<br/>[embed.ts]"]
end

subgraph group_site["Account and site services"]
  node_site_api["Site endpoints<br/>[route.ts]"]
  node_site_services["Site services<br/>[stats.ts]"]
  node_site_db[("Site database<br/>[db.ts]")]
end

subgraph group_experience["Product experience"]
  node_search_ui["Search interface<br/>[QueryScreen.tsx]"]
  node_query_hook["Query state<br/>[useQuery.ts]"]
  node_home["Home and icon scene<br/>[page.tsx]"]
  node_vending_api["Vending icon endpoints<br/>[route.ts]"]
end

node_visitor(("Researcher"))
node_chart_feeds["Apple chart feeds"]
node_lookup_api["Apple Lookup API"]
node_openrouter["OpenRouter"]

node_visitor -->|"enters query"| node_search_ui
node_search_ui -->|"submits query"| node_query_hook
node_query_hook -->|"posts query"| node_query_api
node_query_api -->|"dispatches query"| node_router
node_router -->|"classifies shape"| node_classify
node_router -->|"routes factual"| node_factual
node_router -->|"routes comparative"| node_comparative
node_router -->|"routes local discovery"| node_discovery
node_router -->|"selects catalog"| node_catalog_runtime
node_catalog_runtime -->|"retrieves finalists"| node_discovery
node_router -->|"scores finalists"| node_jev
node_jev -->|"requests scoring"| node_openrouter
node_router -->|"loads app detail"| node_detail
node_detail -->|"reads app records"| node_catalog_store
node_detail -->|"returns tiered fields"| node_provenance
node_chart_feeds -->|"provides chart data"| node_scrape
node_lookup_api -->|"provides listings"| node_scrape
node_scrape -->|"writes catalog"| node_catalog_store
node_catalog_store -->|"supplies app data"| node_enrichment
node_enrichment -->|"stores signals"| node_catalog_store
node_site_api -->|"records visits"| node_site_services
node_site_services -->|"reads and writes"| node_site_db
node_home -->|"introduces product"| node_visitor
node_vending_api -->|"serves catalog icons"| node_catalog_store

click node_search_ui "https://github.com/soloiaros/archies-appstore-lookup/blob/main/components/QueryScreen.tsx"
click node_query_hook "https://github.com/soloiaros/archies-appstore-lookup/blob/main/hooks/useQuery.ts"
click node_query_api "https://github.com/soloiaros/archies-appstore-lookup/blob/main/app/api/query/route.ts"
click node_router "https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/router/index.ts"
click node_classify "https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/router/classify.ts"
click node_factual "https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/router/factual.ts"
click node_comparative "https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/router/comparative.ts"
click node_discovery "https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/retrieve/finalists.ts"
click node_catalog_runtime "https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/catalog/cloud.ts"
click node_jev "https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/jev/score.ts"
click node_detail "https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/catalog/detail.ts"
click node_provenance "https://github.com/soloiaros/archies-appstore-lookup/blob/main/models/provenance.ts"
click node_scrape "https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/scrape/index.ts"
click node_catalog_store "https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/scrape/store.ts"
click node_enrichment "https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/pipeline/embed.ts"
click node_site_api "https://github.com/soloiaros/archies-appstore-lookup/blob/main/app/api/collect/route.ts"
click node_site_services "https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/site/stats.ts"
click node_site_db "https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/site/db.ts"
click node_home "https://github.com/soloiaros/archies-appstore-lookup/blob/main/app/page.tsx"
click node_vending_api "https://github.com/soloiaros/archies-appstore-lookup/blob/main/app/api/vending-icons/route.ts"

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_query_api,node_router,node_classify,node_factual,node_comparative,node_discovery,node_jev toneBlue
class node_catalog_runtime,node_detail,node_provenance,node_scrape,node_catalog_store,node_enrichment toneAmber
class node_site_api,node_site_services,node_site_db,node_lookup_api,node_openrouter toneMint
class node_search_ui,node_query_hook,node_home,node_vending_api toneRose
class node_visitor,node_chart_feeds toneIndigo
```

## Components

### Search and answers

- [Query endpoint](https://github.com/soloiaros/archies-appstore-lookup/blob/main/app/api/query/route.ts): `app/api/query/route.ts`
- [Query router](https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/router/index.ts): `lib/router/index.ts`
- [Query classification](https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/router/classify.ts): `lib/router/classify.ts`
- [Factual lookup](https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/router/factual.ts): `lib/router/factual.ts`
- [Comparative ranking](https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/router/comparative.ts): `lib/router/comparative.ts`
- [Discovery retrieval](https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/retrieve/finalists.ts): `lib/retrieve/finalists.ts`
- [Jev scoring](https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/jev/score.ts): `lib/jev/score.ts`

### Catalog and enrichment

- [Catalog access](https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/catalog/cloud.ts): `lib/catalog/cloud.ts`
- [App details](https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/catalog/detail.ts): `lib/catalog/detail.ts`
- [Provenance rules](https://github.com/soloiaros/archies-appstore-lookup/blob/main/models/provenance.ts): `models/provenance.ts`
- [Catalog ingestion](https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/scrape/index.ts): `lib/scrape/index.ts`
- [Catalog storage](https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/scrape/store.ts): `lib/scrape/store.ts`
- [Offline enrichment](https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/pipeline/embed.ts): `lib/pipeline/embed.ts`

### Account and site services

- [Site endpoints](https://github.com/soloiaros/archies-appstore-lookup/blob/main/app/api/collect/route.ts): `app/api/collect/route.ts`
- [Site services](https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/site/stats.ts): `lib/site/stats.ts`
- [Site database](https://github.com/soloiaros/archies-appstore-lookup/blob/main/lib/site/db.ts): `lib/site/db.ts`

### Product experience

- [Search interface](https://github.com/soloiaros/archies-appstore-lookup/blob/main/components/QueryScreen.tsx): `components/QueryScreen.tsx`
- [Query state](https://github.com/soloiaros/archies-appstore-lookup/blob/main/hooks/useQuery.ts): `hooks/useQuery.ts`
- [Home and icon scene](https://github.com/soloiaros/archies-appstore-lookup/blob/main/app/page.tsx): `app/page.tsx`
- [Vending icon endpoints](https://github.com/soloiaros/archies-appstore-lookup/blob/main/app/api/vending-icons/route.ts): `app/api/vending-icons/route.ts`

### Other components

- **Researcher**
- **Apple chart feeds**
- **Apple Lookup API**
- **OpenRouter**

## Connections

- Researcher → Search interface: enters query
- Search interface → Query state: submits query (evidence: `components/QueryScreen.tsx`)
- Query state → Query endpoint: posts query (evidence: `hooks/useQuery.ts`)
- Query endpoint → Query router: dispatches query (evidence: `app/api/query/route.ts`)
- Query router → Query classification: classifies shape (evidence: `lib/router/index.ts`)
- Query router → Factual lookup: routes factual (evidence: `lib/router/index.ts`)
- Query router → Comparative ranking: routes comparative (evidence: `lib/router/index.ts`)
- Query router → Discovery retrieval: routes local discovery (evidence: `lib/router/index.ts`)
- Query router → Catalog access: selects catalog (evidence: `lib/router/index.ts`)
- Catalog access → Discovery retrieval: retrieves finalists
- Query router → Jev scoring: scores finalists (evidence: `lib/router/index.ts`)
- Jev scoring → OpenRouter: requests scoring
- Query router → App details: loads app detail
- App details → Catalog storage: reads app records (evidence: `lib/catalog/detail.ts`)
- App details → Provenance rules: returns tiered fields (evidence: `lib/catalog/detail.ts`)
- Apple chart feeds → Catalog ingestion: provides chart data
- Apple Lookup API → Catalog ingestion: provides listings
- Catalog ingestion → Catalog storage: writes catalog
- Catalog storage → Offline enrichment: supplies app data
- Offline enrichment → Catalog storage: stores signals
- Site endpoints → Site services: records visits (evidence: `app/api/collect/route.ts`)
- Site services → Site database: reads and writes (evidence: `lib/site/stats.ts`)
- Home and icon scene → Researcher: introduces product (evidence: `app/page.tsx`)
- Vending icon endpoints → Catalog storage: serves catalog icons (evidence: `app/api/vending-icons/route.ts`)
