# lyp0746/mercari-monitor architecture

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

## Overview

The product monitors six secondhand marketplaces, stores and filters discovered listings, and notifies users; it can be operated through a web UI, desktop GUI, or headless mode. The web workflow is user → React client → FastAPI routes/runtime → marketplace monitors → persisted listings and notifications, with WebSocket events for live updates. The README documents filtering, watchlists, blocked items, settings, stats, and Telegram commands; those capabilities are represented, though some route implementations were not sampled. Edges reflect only shown calls or README claims; unsampled route internals are not inferred.

Main entry points: [`src/monitors/base.py`](https://github.com/lyp0746/mercari-monitor/blob/main/src/monitors/base.py) (Polling and filtering), [`src/api/deps.py`](https://github.com/lyp0746/mercari-monitor/blob/main/src/api/deps.py) (Monitor runtime), [`src/monitors`](https://github.com/lyp0746/mercari-monitor/tree/main/src/monitors) (Marketplace adapters), [`src/notifier.py`](https://github.com/lyp0746/mercari-monitor/blob/main/src/notifier.py) (Notification dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_webclient["API client<br/>[client.ts]"]
  node_websocket["Live event client<br/>[useWS.ts]"]
  node_webpages["Management pages"]
  node_desktop["Desktop GUI<br/>[app.py]"]
  node_headless["Headless runner<br/>[main.py]"]
end

subgraph group_api["Web API"]
  node_fastapi["API application<br/>[main.py]"]
  node_routes["API routes"]
  node_api_runtime["Monitor runtime<br/>[deps.py]"]
  node_broadcaster["Event broadcaster<br/>[deps.py]"]
end

subgraph group_monitoring["Monitoring"]
  node_monitor_core["Polling and filtering<br/>[base.py]"]
  node_marketplaces["Marketplace adapters"]
  node_mercari["Mercari adapter<br/>[mercari.py]"]
  node_carousell["Carousell adapter<br/>[carousell.py]"]
  node_yahoo["Yahoo Auctions adapter<br/>[yahoo_auctions.py]"]
end

subgraph group_state["Configuration and state"]
  node_config["JSON configuration<br/>[config.py]"]
  node_database[("SQLite database<br/>[database.py]")]
end

subgraph group_notify["Notifications"]
  node_notifier["Notification dispatcher<br/>[notifier.py]"]
  node_telegram_bot["Telegram command service"]
end

node_user(("Operator"))
node_telegram(("Telegram"))
node_discord(("Discord webhook"))
node_marketplaces_external(("Marketplace services"))

node_user -->|"operates"| node_webapp
node_webapp -->|"renders"| node_webpages
node_webapp -->|"uses"| node_webclient
node_webapp -->|"subscribes"| node_websocket
node_webpages -->|"requests data"| node_webclient
node_webclient -->|"HTTP requests"| node_fastapi
node_websocket -.->|"receives events"| node_api_runtime
node_user -->|"operates"| node_desktop
node_user -->|"starts"| node_headless
node_fastapi -->|"registers"| node_routes
node_routes -->|"delegates"| node_api_runtime
node_api_runtime -->|"selects adapters"| node_marketplaces
node_headless -->|"selects adapters"| node_marketplaces
node_desktop -->|"uses adapters"| node_marketplaces
node_marketplaces -->|"maps platform"| node_mercari
node_marketplaces -->|"maps platform"| node_carousell
node_marketplaces -->|"maps platform"| node_yahoo
node_mercari -->|"inherits"| node_monitor_core
node_carousell -->|"inherits"| node_monitor_core
node_yahoo -->|"inherits"| node_monitor_core
node_monitor_core -->|"polls"| node_marketplaces_external
node_monitor_core -->|"reads settings"| node_config
node_api_runtime -->|"reads keywords"| node_database
node_monitor_core -.->|"uses listing state"| node_database
node_config -->|"syncs settings"| node_database
node_api_runtime -->|"constructs"| node_notifier
node_monitor_core -.->|"notifies"| node_notifier
node_notifier -->|"sends messages"| node_telegram
node_notifier -->|"posts embeds"| node_discord
node_api_runtime -->|"broadcasts events"| node_broadcaster
node_notifier -->|"registers callback"| node_broadcaster
node_telegram -->|"sends commands"| node_telegram_bot
node_telegram_bot -.->|"processes commands"| node_notifier
node_desktop -->|"uses"| node_database

click node_webapp "https://github.com/lyp0746/mercari-monitor/blob/main/web/src/App.tsx"
click node_webclient "https://github.com/lyp0746/mercari-monitor/blob/main/web/src/api/client.ts"
click node_websocket "https://github.com/lyp0746/mercari-monitor/blob/main/web/src/hooks/useWS.ts"
click node_webpages "https://github.com/lyp0746/mercari-monitor/tree/main/web/src/pages"
click node_desktop "https://github.com/lyp0746/mercari-monitor/blob/main/src/gui/app.py"
click node_headless "https://github.com/lyp0746/mercari-monitor/blob/main/src/main.py"
click node_fastapi "https://github.com/lyp0746/mercari-monitor/blob/main/src/api/main.py"
click node_routes "https://github.com/lyp0746/mercari-monitor/tree/main/src/api/routes"
click node_api_runtime "https://github.com/lyp0746/mercari-monitor/blob/main/src/api/deps.py"
click node_broadcaster "https://github.com/lyp0746/mercari-monitor/blob/main/src/api/deps.py"
click node_monitor_core "https://github.com/lyp0746/mercari-monitor/blob/main/src/monitors/base.py"
click node_marketplaces "https://github.com/lyp0746/mercari-monitor/tree/main/src/monitors"
click node_mercari "https://github.com/lyp0746/mercari-monitor/blob/main/src/monitors/mercari.py"
click node_carousell "https://github.com/lyp0746/mercari-monitor/blob/main/src/monitors/carousell.py"
click node_yahoo "https://github.com/lyp0746/mercari-monitor/blob/main/src/monitors/yahoo_auctions.py"
click node_config "https://github.com/lyp0746/mercari-monitor/blob/main/src/config.py"
click node_database "https://github.com/lyp0746/mercari-monitor/blob/main/src/database.py"
click node_notifier "https://github.com/lyp0746/mercari-monitor/blob/main/src/notifier.py"
click node_telegram_bot "https://github.com/lyp0746/mercari-monitor/blob/main/src/telegram_bot_service.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_webapp,node_webclient,node_websocket,node_webpages,node_desktop,node_headless toneBlue
class node_fastapi,node_routes,node_api_runtime,node_broadcaster toneAmber
class node_monitor_core,node_marketplaces,node_mercari,node_carousell,node_yahoo,node_discord toneMint
class node_config,node_database toneRose
class node_notifier,node_telegram_bot,node_user,node_telegram,node_marketplaces_external toneIndigo
```

## Components

### User interfaces

- [Web application](https://github.com/lyp0746/mercari-monitor/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [API client](https://github.com/lyp0746/mercari-monitor/blob/main/web/src/api/client.ts): `web/src/api/client.ts`
- [Live event client](https://github.com/lyp0746/mercari-monitor/blob/main/web/src/hooks/useWS.ts): `web/src/hooks/useWS.ts`
- [Management pages](https://github.com/lyp0746/mercari-monitor/tree/main/web/src/pages): `web/src/pages`
- [Desktop GUI](https://github.com/lyp0746/mercari-monitor/blob/main/src/gui/app.py): `src/gui/app.py`
- [Headless runner](https://github.com/lyp0746/mercari-monitor/blob/main/src/main.py): `src/main.py`

### Web API

- [API application](https://github.com/lyp0746/mercari-monitor/blob/main/src/api/main.py): `src/api/main.py`
- [API routes](https://github.com/lyp0746/mercari-monitor/tree/main/src/api/routes): `src/api/routes`
- [Monitor runtime](https://github.com/lyp0746/mercari-monitor/blob/main/src/api/deps.py): `src/api/deps.py`
- [Event broadcaster](https://github.com/lyp0746/mercari-monitor/blob/main/src/api/deps.py): `src/api/deps.py`

### Monitoring

- [Polling and filtering](https://github.com/lyp0746/mercari-monitor/blob/main/src/monitors/base.py): `src/monitors/base.py`
- [Marketplace adapters](https://github.com/lyp0746/mercari-monitor/tree/main/src/monitors): `src/monitors`
- [Mercari adapter](https://github.com/lyp0746/mercari-monitor/blob/main/src/monitors/mercari.py): `src/monitors/mercari.py`
- [Carousell adapter](https://github.com/lyp0746/mercari-monitor/blob/main/src/monitors/carousell.py): `src/monitors/carousell.py`
- [Yahoo Auctions adapter](https://github.com/lyp0746/mercari-monitor/blob/main/src/monitors/yahoo_auctions.py): `src/monitors/yahoo_auctions.py`

### Configuration and state

- [JSON configuration](https://github.com/lyp0746/mercari-monitor/blob/main/src/config.py): `src/config.py`
- [SQLite database](https://github.com/lyp0746/mercari-monitor/blob/main/src/database.py): `src/database.py`

### Notifications

- [Notification dispatcher](https://github.com/lyp0746/mercari-monitor/blob/main/src/notifier.py): `src/notifier.py`
- [Telegram command service](https://github.com/lyp0746/mercari-monitor/blob/main/src/telegram_bot_service.py): `src/telegram_bot_service.py`

### Other components

- **Operator**
- **Telegram**
- **Discord webhook**
- **Marketplace services**

## Connections

- Operator → Web application: operates (evidence: `README.md`)
- Web application → Management pages: renders (evidence: `web/src/App.tsx`)
- Web application → API client: uses (evidence: `web/src/App.tsx`)
- Web application → Live event client: subscribes (evidence: `web/src/App.tsx`)
- Management pages → API client: requests data (evidence: `web/src/pages/Dashboard.tsx`)
- API client → API application: HTTP requests (evidence: `web/src/api/client.ts`)
- Live event client → Monitor runtime: receives events
- Operator → Desktop GUI: operates (evidence: `README.md`)
- Operator → Headless runner: starts (evidence: `README.md`)
- API application → API routes: registers (evidence: `src/api/main.py`)
- API routes → Monitor runtime: delegates (evidence: `src/api/deps.py`)
- Monitor runtime → Marketplace adapters: selects adapters (evidence: `src/api/deps.py`)
- Headless runner → Marketplace adapters: selects adapters (evidence: `src/main.py`)
- Desktop GUI → Marketplace adapters: uses adapters (evidence: `src/gui/app.py`)
- Marketplace adapters → Mercari adapter: maps platform (evidence: `src/monitors/__init__.py`)
- Marketplace adapters → Carousell adapter: maps platform (evidence: `src/monitors/__init__.py`)
- Marketplace adapters → Yahoo Auctions adapter: maps platform (evidence: `src/monitors/__init__.py`)
- Mercari adapter → Polling and filtering: inherits (evidence: `src/monitors/mercari.py`)
- Carousell adapter → Polling and filtering: inherits (evidence: `src/monitors/carousell.py`)
- Yahoo Auctions adapter → Polling and filtering: inherits (evidence: `src/monitors/yahoo_auctions.py`)
- Polling and filtering → Marketplace services: polls (evidence: `README.md`)
- Polling and filtering → JSON configuration: reads settings (evidence: `src/monitors/base.py`)
- Monitor runtime → SQLite database: reads keywords (evidence: `src/api/deps.py`)
- Polling and filtering → SQLite database: uses listing state
- JSON configuration → SQLite database: syncs settings (evidence: `src/config.py`)
- Monitor runtime → Notification dispatcher: constructs (evidence: `src/api/deps.py`)
- Polling and filtering → Notification dispatcher: notifies
- Notification dispatcher → Telegram: sends messages (evidence: `README.md`)
- Notification dispatcher → Discord webhook: posts embeds (evidence: `README.md`)
- Monitor runtime → Event broadcaster: broadcasts events (evidence: `src/api/deps.py`)
- Notification dispatcher → Event broadcaster: registers callback (evidence: `src/api/deps.py`)
- Telegram → Telegram command service: sends commands (evidence: `README.md`)
- Telegram command service → Notification dispatcher: processes commands
- Desktop GUI → SQLite database: uses (evidence: `src/gui/app.py`)