# therealpurle/appmeai architecture

> Architecture diagram of the GitHub repository therealpurle/appmeai, 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/therealpurle/appmeai
- Repository: https://github.com/therealpurle/appmeai

## Overview

This repository builds and refreshes AppMeAI’s app-store catalogue from public store data, then optionally sends collected records to an import API. The main workflow searches Apple and Google by category terms, deduplicates and enriches results, writes catalogue files, and can import them; a separate worker refreshes Apple chart observations by market. Additional store-specific collectors cover Galaxy, Amazon, Huawei, and Xiaomi. The README is empty, and collector orchestration for those additional stores is not shown, so their connections are limited to evidence in the sampled modules.

Main entry points: [`catalogue-builder/collect.mjs`](https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/collect.mjs) (Query collector), [`catalogue-builder/import_catalogue.mjs`](https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/import_catalogue.mjs) (Import client), [`catalogue-builder/store_collector_common.mjs`](https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/store_collector_common.mjs) (Browser helpers), [`catalogue-builder/amazon_store.mjs`](https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/amazon_store.mjs) (Amazon collector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Catalogue collection"]
  node_categories["Search terms<br/>[categories.json]"]
  node_collector["Query collector<br/>[collect.mjs]"]
end

subgraph group_stores["Store integrations"]
  node_apple_search["Apple search<br/>[collect.mjs]"]
  node_google_search["Google search<br/>[collect.mjs]"]
  node_shared_store["Browser helpers"]
  node_galaxy["Galaxy collector<br/>[galaxy_store.mjs]"]
  node_amazon["Amazon collector<br/>[amazon_store.mjs]"]
  node_huawei["Huawei collector<br/>[huawei_store.mjs]"]
  node_xiaomi["Xiaomi collector<br/>[xiaomi_store.mjs]"]
end

subgraph group_processing["Catalogue processing"]
  node_dedupe["Merge and filter<br/>[collect.mjs]"]
  node_google_enrich["Google enrichment<br/>[collect.mjs]"]
  node_catalogue_files["Catalogue files<br/>[collect.mjs]"]
end

subgraph group_delivery["Import and refresh"]
  node_import_client["Import client"]
  node_refresh_worker["Chart refresh<br/>[refresh_worker.js]"]
end

node_apple_charts(("Apple chart feeds"))
node_google_play(("Google Play"))
node_galaxy_service(("Galaxy Store"))
node_amazon_service(("Amazon Appstore"))
node_huawei_service(("Huawei AppGallery"))
node_xiaomi_service(("Xiaomi GetApps"))
node_import_api(("Import API"))

node_collector -->|"reads terms"| node_categories
node_collector -->|"queries"| node_apple_search
node_collector -->|"queries"| node_google_search
node_collector -->|"merges results"| node_dedupe
node_dedupe -->|"enriches records"| node_google_enrich
node_collector -->|"writes files"| node_catalogue_files
node_google_enrich -->|"updates files"| node_catalogue_files
node_collector -->|"optionally imports"| node_import_client
node_import_client -->|"reads JSONL"| node_catalogue_files
node_import_client -->|"posts batches"| node_import_api
node_apple_search -->|"searches"| node_apple_charts
node_google_search -->|"searches"| node_google_play
node_refresh_worker -->|"fetches charts"| node_apple_charts
node_refresh_worker -->|"posts batches"| node_import_api
node_amazon -->|"uses helpers"| node_shared_store
node_huawei -->|"uses helpers"| node_shared_store
node_xiaomi -->|"uses helpers"| node_shared_store
node_amazon -->|"renders pages"| node_amazon_service
node_huawei -->|"renders pages"| node_huawei_service
node_xiaomi -->|"renders pages"| node_xiaomi_service
node_galaxy -->|"requests catalogue"| node_galaxy_service

click node_categories "https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/categories.json"
click node_collector "https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/collect.mjs"
click node_apple_search "https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/collect.mjs"
click node_google_search "https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/collect.mjs"
click node_shared_store "https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/store_collector_common.mjs"
click node_galaxy "https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/galaxy_store.mjs"
click node_amazon "https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/amazon_store.mjs"
click node_huawei "https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/huawei_store.mjs"
click node_xiaomi "https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/xiaomi_store.mjs"
click node_dedupe "https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/collect.mjs"
click node_google_enrich "https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/collect.mjs"
click node_catalogue_files "https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/collect.mjs"
click node_import_client "https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/import_catalogue.mjs"
click node_refresh_worker "https://github.com/therealpurle/appmeai/blob/main/refresh_worker.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_categories,node_collector toneBlue
class node_apple_search,node_google_search,node_shared_store,node_galaxy,node_amazon,node_huawei,node_xiaomi toneAmber
class node_dedupe,node_google_enrich,node_catalogue_files,node_import_api toneMint
class node_import_client,node_refresh_worker toneRose
class node_apple_charts,node_google_play,node_galaxy_service,node_amazon_service,node_huawei_service,node_xiaomi_service toneIndigo
```

## Components

### Catalogue collection

- [Search terms](https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/categories.json): `catalogue-builder/categories.json`
- [Query collector](https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/collect.mjs): `catalogue-builder/collect.mjs`

### Store integrations

- [Apple search](https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/collect.mjs): `catalogue-builder/collect.mjs`
- [Google search](https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/collect.mjs): `catalogue-builder/collect.mjs`
- [Browser helpers](https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/store_collector_common.mjs): `catalogue-builder/store_collector_common.mjs`
- [Galaxy collector](https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/galaxy_store.mjs): `catalogue-builder/galaxy_store.mjs`
- [Amazon collector](https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/amazon_store.mjs): `catalogue-builder/amazon_store.mjs`
- [Huawei collector](https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/huawei_store.mjs): `catalogue-builder/huawei_store.mjs`
- [Xiaomi collector](https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/xiaomi_store.mjs): `catalogue-builder/xiaomi_store.mjs`

### Catalogue processing

- [Merge and filter](https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/collect.mjs): `catalogue-builder/collect.mjs`
- [Google enrichment](https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/collect.mjs): `catalogue-builder/collect.mjs`
- [Catalogue files](https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/collect.mjs): `catalogue-builder/collect.mjs`

### Import and refresh

- [Import client](https://github.com/therealpurle/appmeai/blob/main/catalogue-builder/import_catalogue.mjs): `catalogue-builder/import_catalogue.mjs`
- [Chart refresh](https://github.com/therealpurle/appmeai/blob/main/refresh_worker.js): `refresh_worker.js`

### Other components

- **Apple chart feeds**
- **Google Play**
- **Galaxy Store**
- **Amazon Appstore**
- **Huawei AppGallery**
- **Xiaomi GetApps**
- **Import API**

## Connections

- Query collector → Search terms: reads terms (evidence: `catalogue-builder/collect.mjs`)
- Query collector → Apple search: queries (evidence: `catalogue-builder/collect.mjs`)
- Query collector → Google search: queries (evidence: `catalogue-builder/collect.mjs`)
- Query collector → Merge and filter: merges results (evidence: `catalogue-builder/collect.mjs`)
- Merge and filter → Google enrichment: enriches records (evidence: `catalogue-builder/collect.mjs`)
- Query collector → Catalogue files: writes files (evidence: `catalogue-builder/collect.mjs`)
- Google enrichment → Catalogue files: updates files (evidence: `catalogue-builder/collect.mjs`)
- Query collector → Import client: optionally imports (evidence: `catalogue-builder/collect.mjs`)
- Import client → Catalogue files: reads JSONL (evidence: `catalogue-builder/import_catalogue.mjs`)
- Import client → Import API: posts batches (evidence: `catalogue-builder/import_catalogue.mjs`)
- Apple search → Apple chart feeds: searches (evidence: `catalogue-builder/collect.mjs`)
- Google search → Google Play: searches (evidence: `catalogue-builder/collect.mjs`)
- Chart refresh → Apple chart feeds: fetches charts (evidence: `refresh_worker.js`)
- Chart refresh → Import API: posts batches (evidence: `refresh_worker.js`)
- Amazon collector → Browser helpers: uses helpers (evidence: `catalogue-builder/amazon_store.mjs`)
- Huawei collector → Browser helpers: uses helpers (evidence: `catalogue-builder/huawei_store.mjs`)
- Xiaomi collector → Browser helpers: uses helpers (evidence: `catalogue-builder/xiaomi_store.mjs`)
- Amazon collector → Amazon Appstore: renders pages (evidence: `catalogue-builder/amazon_store.mjs`)
- Huawei collector → Huawei AppGallery: renders pages (evidence: `catalogue-builder/huawei_store.mjs`)
- Xiaomi collector → Xiaomi GetApps: renders pages (evidence: `catalogue-builder/xiaomi_store.mjs`)
- Galaxy collector → Galaxy Store: requests catalogue (evidence: `catalogue-builder/galaxy_store.mjs`)