Architecture

Details and every decision: docs/architecture.md.

Next.js web app  -->  Flask API  -->  holidays library (closures, half days)
 (SSR pages,          (Pydantic,  -->  MySQL (settlement cycles, official closures)
  tools, embed)        blueprints) -->  Redis (cache)

The API is the only part that talks to MySQL and Redis; the web app only calls the API.

Folder	What
backend/app/core/	pure date logic: calendar, settlement, status, data quality, iCalendar. No Flask or database imports, 100% branch coverage
backend/app/api/	Flask blueprints, one per area
backend/app/	app factory, config, models, schemas, OpenAPI, cache, rate limit, headers, seed
backend/migrations/	Alembic
frontend/src/app/	Next.js routes, robots, sitemap, llms files, embed, error and offline pages
frontend/src/lib/	API client, generated schema types, data cache, SEO helpers

Rules that shape the code

• Holiday dates are never copied; the library is the single source.
• Every outside fact has a source URL that was read. Unverifiable means left out.
• Dates are plain datetime.date; timezones only for "open right now".
• The OpenAPI file is generated from the Pydantic models and the web app's types from it; CI fails when either drifts.

Caching

Redis caches holidays per library version, market and year (an outage only skips the cache); the Next.js data cache keeps the market list and holidays for hours; reference data is max-age=300, feeds an hour, live status no-store.