Development

Repository map

Path	Purpose
backend/app/api	HTTP endpoints and schemas
backend/app/core	Configuration, DB, authentication, HTTP and middleware
backend/app/services	Business and worker logic
backend/app/games	Game providers and OCR parsing
backend/app/prices and backend/app/sources	Market and supplemental-source plugins
backend/app/models, backend/alembic	SQLAlchemy models and migrations
backend/tests	Backend tests, fixtures, source mocks
web/src	React pages, components, API client and translations
android	Kotlin/Compose Android application
deploy	Entrypoint and development identity-provider configuration
.github/workflows	Backend/web checks, images, Android builds and releases
scripts	Asset/data helpers and CI scripts

Run the source-build stack

Create .env as described in Docker installation, then:

docker compose -f docker-compose-dev.yml up -d --build

This builds the combined web/backend image locally. Project name is zukan-dev, persistent state is data-dev, and the default host port is still 8000. It is not a live-reloading source mount.

Backend environment

Use Python 3.13 or newer as required by pyproject.toml. From backend:

python3.13 -m venv .venv
.venv/bin/pip install -e '.[dev]'

Use a dedicated PostgreSQL database for development. Set TCG_DATABASE_URL, TCG_SECRET_KEY and other needed settings in the environment or the working directory's .env. Run migrations before launching Uvicorn:

.venv/bin/alembic upgrade head
.venv/bin/uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Production images build the web bundle into /app/web. For a local backend, set TCG_WEB_DIR to a real web/dist build if you want the backend to serve it.

Web environment

CI uses Node 24 and the committed npm lockfile. From web:

npm ci
npm run dev

The Vite development proxy configuration controls API forwarding. Inspect web/vite.config.ts before changing backend addresses. Production build: npm run build (TypeScript build followed by Vite).

After an API contract change, use npm run gen:api from web; it expects backend/.venv/bin/python, obtains FastAPI OpenAPI and regenerates src/api/schema.d.ts.

Backend checks

.venv/bin/ruff check .
.venv/bin/ruff format --check .
.venv/bin/pytest -q

Tests default to postgresql+asyncpg://tcg:tcg@localhost:5432/tcg_test. Use an isolated test database. The fixtures create/drop tables and truncate data. Never point these tests at production or a database containing work you want to keep. Most external network access is blocked/mocked by test fixtures.

pytest -m smoke runs the marked fast subset. Full CI also runs Alembic upgrade/check against its isolated database.

Web checks

npx tsc -b
npm run check:i18n
npm run lint
npm run build

Full CI checks generated API types for drift and performs an npm dependency audit. Review current workflow files as the authoritative check list; this wiki does not imply those checks were executed during documentation preparation.

Android build

Use the checked-in Gradle wrapper and a compatible JDK 17/Android toolchain. The reviewed configuration uses compile/target SDK 37 and minimum SDK 26. From android:

./gradlew assembleDebug
./gradlew testDebugUnitTest

Debug ID is fr.zukan.app.dev; configure its OIDC redirect separately. Release signing is provided through ANDROID_KEYSTORE_PATH, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS and ANDROID_KEY_PASSWORD. Never commit signing material. Without signing configuration, release output is unsigned; local debug builds use the debug key.

Schema and provider changes

Create Alembic migrations for persistent schema changes. Update both OpenAPI-generated web types and Android DTOs when contracts change. Preserve external IDs across catalog imports; test moves and regional splits with owned cards before release. A provider catalog-version bump requests a fresh import, not a SQL schema migration.

Contributions

Open an issue to discuss substantial changes before implementation. Include reproduction steps and focused tests for behavior changes. Constructive reviews, translations, documentation and new game integrations are welcome. Keep secrets and real user data out of fixtures and screenshots.

Implementation references

• backend/pyproject.toml
• web/package.json
• .github/workflows/_checks.yml
• android/app/build.gradle.kts