System shape

Architecture

The app stays deliberately small: Python for scraping and local API, vanilla JavaScript for the UI, JSON for persistence.

CLI scraper

main.py and pokedex/ scrape Pokepedia, normalize forms, attach regions and export JSON/CSV/YAML/XML.

FastAPI tracker

tracker/ exposes progress, binders, badges, trainer contacts, backup and health endpoints.

Vanilla SPA

web/ is served directly. No framework, no frontend build step, no hosted runtime.

JSON repositories

Each local state surface has a small repository/service pair for predictable file persistence.

Data flow

From reference data to user state.

Layer	Responsibility	Key files
Reference Pokedex	Stable catalog used by UI and tests.	`data/pokedex.json`, `pokedex/`
API models	Typed contracts for progress, trainer contacts with public contact links and exports.	`tracker/models.py`, `tracker/binder_models.py`
User JSON state	Single local state files, including received Trainer Cards.	`data/collection-progress.json`, `data/trainer-contacts.json`
Services	Business rules such as capture status, duplicate sharing and monotonic badges.	`tracker/services/`
Frontend modules	Route rendering, badges, binders, trainer contacts and settings.	`web/*.js`

API surface

Local integrations stay simple.

Progress

/api/progress, /api/progress/status and /api/progress/notes.

Reference data

/data/game-pokedexes.json complements the local Pokedex.

Workspace

/api/binder, /api/trainers, /api/export, /api/import.

Legacy local files

Simplified model migration is conservative.

Older installs may still have data/hunts.json from the explicit search-list workflow. It is ignored by the active app and omitted from new backups.

Legacy Trainer Card wants and badges fields are tolerated but ignored; only for_trade/Double is shared. Removed first_encounter badge ids are cleaned/ignored while the badge gallery remains available.