Architecture

Zukan has one shared PostgreSQL catalog and independent per-user collections. The same Python image is used for API and worker processes.

flowchart TD
    Web["Web browser: React"] --> API["FastAPI: web assets and API"]
    Android["Android: camera and local OCR"] --> API
    API --> DB["PostgreSQL 17"]
    API --> Images["Image and source cache"]
    API --> IdP["OIDC identity provider"]
    Worker["Background worker"] --> DB
    Worker --> Images
    Worker --> Sources["Catalog and market sources"]
    API --> Sources

Loading

Backend

Python 3.13, FastAPI, Pydantic and HTTPX implement the API, validation, provider calls and administrative CLI. SQLAlchemy 2 uses async PostgreSQL access; Alembic owns schema evolution. PostgreSQL trigram/unaccent functionality supports approximate and accent-insensitive name matching.

app/api contains HTTP contracts and authorization dependencies. app/services owns stock, CSV, catalog imports, prices, images, identification, jobs, schedules, cross-checks and load monitoring. app/games, app/prices and app/sources provide plugin contracts and implementations. app/models defines persistence.

Web

React 19 and TypeScript use Vite builds, TanStack Query, React Router and i18next. Tailwind CSS 4 and daisyUI 5 style the interface. Production static assets are served by FastAPI on the API origin, avoiding a separate production web server/CORS deployment requirement.

The API client uses types generated from OpenAPI. Page modules are lazy-loaded; authenticated layout and administrator pages enforce appropriate UI routes, while the backend remains the authority for permissions.

Android

Kotlin, Compose, CameraX, ML Kit, Retrofit/OkHttp and AppAuth implement the phone interface. ML Kit models are bundled for Latin, Japanese, Chinese and Korean scripts. DataStore persists the server URL, session tokens and scanner preferences. The backend holds authoritative stock.

Background work

The worker has an automatic scheduler and a manual-queue loop. Automatic checks use persisted schedule rules or environment defaults. UI sync requests store queued runs in PostgreSQL; the worker executes them. Run records include ownership, heartbeat, result counters, errors and cancellation state.

Identification path

1. Android obtains stable OCR lines and normalized boxes.
2. /api/scan/identify validates input.
3. Game parsers extract names, set codes, numbers and language hints.
4. The server ranks exact set/number, number/name and fuzzy name candidates.
5. A missing candidate can trigger provider lookup.
6. The user confirms the printing and submits an independent stock change.

Stock is never inferred solely from receiving a camera frame.

Shared versus isolated state

Catalog refreshes, source arbitrations and images affect the server-wide dataset. Collections, manual prices and notes belong to users. Sessions and identities are separate database entities. A worker catalog reset is therefore an operator action with shared effects, not a personal collection edit.

Deployment boundary

Compose provides database, API and worker services. HTTPS/reverse proxy, external identity provider, off-host backups and monitoring remain operator responsibilities. The repository includes a development Keycloak profile, not a production identity-provider stack.

Implementation references

• backend/app/main.py
• backend/app/worker.py
• backend/app/games/base.py
• web/src/main.tsx