Cosmic Architect

Web-based, multiplayer successor to the legacy MythInc/Cosmic Architect Pygame prototype in the sibling mythinc-cardgame/ repository. That legacy tree is reference material only — rules, terminology, and card data inform this implementation; new product code belongs here.

The MVP is a local/private Docker stack: authoritative Python/FastAPI backend, React/TypeScript frontend, dual PostgreSQL databases, and Redis for realtime fan-out.

Prerequisites

• Git
• Docker with Compose V2 (docker compose)

Native Python, Node, and PostgreSQL are not required for normal development.

First run (clone → playable)

git clone <repository-url> cosmic-architect
cd cosmic-architect

docker compose build
docker compose up -d identity-db game-db redis
docker compose run --rm identity-migrate
docker compose run --rm game-migrate
docker compose up -d backend frontend nginx
docker compose ps

Open http://localhost:8080 (NGINX gateway). Frontend and backend publish no host ports in the default stack.

Share with other players on a LAN / lab server

Do not use CA_ENV=production over plain HTTP, and do not share http://localhost:8080 with remote players. Use the server runbook:

docs/server-deployment.md and .env.server.example.

HTTPS production / staging

Canonical hardened path (Plan 182):

docs/production.md, .env.production.example, compose.production.yaml.

cp .env.production.example .env
# replace every CHANGE_ME; chmod 600 .env
./scripts/check-production-config.sh
docker compose -f compose.yaml -f compose.production.yaml up -d …
# terminate TLS on the host (Caddy/nginx/LB) → 127.0.0.1:8080

Create accounts and start a game

1. Register two accounts at /register (e.g. two browser profiles).
2. Sign in as the owner → Create lobby on /lobbies/new.
3. Copy the six-character join code or share link (/join/{code}).
4. Sign in as the second player → open the join link → Join lobby.
5. Owner clicks Start game → both players open /games/{id}.

Gateway and API health (through NGINX):

• Gateway: http://localhost:8080/healthz
• Liveness: http://localhost:8080/api/v1/health/live
• Readiness: http://localhost:8080/api/v1/health/ready

Startup never applies migrations automatically.

Direct frontend/backend ports are available only via the opt-in debug overlay:

docker compose -f compose.yaml -f compose.debug.yaml up -d

Shutdown and reset

Stop services (keep database volumes):

docker compose down --remove-orphans

Reset databases and restart (destructive — wipes accounts/games):

./scripts/reset.sh --yes

Safe rebuild/redeploy without destroying database volumes (Plan 208):

./scripts/redploy.sh
./scripts/redploy.sh --dry-run
./scripts/redploy.sh --pull
./scripts/test-redploy.sh

redploy.sh rebuilds application images, keeps identity-data / game-data, runs Alembic migrations once, redeploys backend/frontend/nginx, waits for health, and smoke-tests through NGINX. It never runs docker compose down -v.

Remove all local data including volumes manually:

docker compose down -v --remove-orphans

Verification

Backend and frontend gates

docker compose --profile test run --rm backend-test
docker compose --profile test run --rm frontend-test

Backend: Ruff, mypy, pytest (including integration), 90% coverage floor. Frontend: ESLint, strict TypeScript, Vitest, production build, and release gates (style:check, CSS/SVG audits, perf budgets, asset checksums). Host-side aggregate:

cd frontend && npm run release:check

End-to-end (dual backend)

docker compose --profile test build e2e
docker compose --profile test run --rm e2e

Playwright runs against load-balanced nginx-e2e (frontend-e2e + backend-a/b). Artifacts: e2e/artifacts/test-results/, e2e/artifacts/report/.

Content, contracts, and balance (no DB)

docker compose run --rm --no-deps backend uv run cosmic-architect-content validate
docker compose run --rm --no-deps backend uv run cosmic-architect-content compile --check
docker compose run --rm --no-deps backend uv run cosmic-architect-ai validate
docker compose run --rm --no-deps backend uv run cosmic-architect-ai compile --check
docker compose run --rm --no-deps backend uv run cosmic-architect-sim entropy-corpus --check

Regenerate HTTP/WebSocket contracts after schema changes (requires local venv):

cd backend
.venv/bin/python scripts/export_openapi.py
.venv/bin/python scripts/export_ws_schemas.py
cd ..
git diff --exit-code -- frontend/src/api/generated/openapi.v2.json \
  frontend/src/api/generated/openapi.v2.sha256 \
  frontend/src/api/ws/ws.v3.json \
  frontend/src/api/ws/ws.v3.sha256

Documentation validation

./scripts/validate-docs.sh

Plan 120 clean-room acceptance

Full rehearsal from empty volumes (20–40 minutes):

./scripts/accept-plan-120.sh

Plan 110 test-only acceptance (skips dev backend/frontend up):

./scripts/accept-plan-110.sh

Configuration

Copy .env.example for local overrides. Compose provides disposable credentials; deployed environments must use different identity and game database passwords, unique secrets. Prefer CA_ORIGIN_POLICY=same-origin (no hostname allowlist); use CA_PUBLIC_ORIGIN only for fixed mode or absolute link preference.

See docs/operations.md for retention, cleanup, health interpretation, and the local/private MVP boundary (internet deployment requires a separate approved plan).

Repository layout

backend/
  content/cards/           Human-authored card YAML
  content/assets/          Asset manifest, placeholders, and Plan 211 guide/ SVGs
  content/assets/guide/    Canonical Guide illustrations (1200×800); sync to frontend/public/guide-art/
  src/cosmic_architect/    Domain, application, API, infrastructure
  migrations/identity/     Identity Alembic history
  migrations/game/         Game Alembic history
  tests/                   Backend and integration tests
docs/                      Architecture, gameplay, protocol, operations
frontend/
  src/                     React application, generated API contracts
  src/assets/              Brand masters, manifest, derivatives (plan 155)
  src/styles/              Design-token specifications (adopted in plan 160)
  scripts/assets_pipeline.py
compose.yaml               Development, test, and E2E services
compose.debug.yaml         Opt-in direct frontend/backend host ports
compose.production.yaml    Plan 182 HTTPS staging/production overlay
deploy/nginx/              Plan 180 configurable NGINX gateway
scripts/                   Acceptance, gateway smoke, production config checks

Documentation

Document	Topic
docs/architecture.md	Layers, data flow, command/outbox path
docs/gameplay.md	Phases, scoring, entropy/Doom
docs/rules-dsl.md	Card YAML DSL, compile workflow, tutorial
docs/multiplayer-protocol.md	REST, WebSocket, join codes
docs/migrations.md	Dual-database Alembic policy
docs/testing.md	Test pyramid, Compose profiles, E2E
docs/operations.md	Env vars, health, cleanup, hardening, NGINX gateway
docs/server-deployment.md	LAN / lab server share + HTTPS staging origin settings
docs/production.md	Plan 182 production-hardened HTTPS runbook
docs/plan-182-acceptance.md	Plan 182 acceptance evidence
docs/plans/180-nginx-gateway-and-service-isolation.md	Plan 180 gateway architecture
docs/plan-180-acceptance.md	Plan 180 acceptance evidence
docs/plans/181-deployment-agnostic-origin-policy.md	Plan 181 same-origin / proxy-aware origins
docs/plan-181-acceptance.md	Plan 181 acceptance evidence
docs/rules-decisions.md	Legacy reconciliation ledger
docs/frontend-visual-audit.md	Plan 155 visual audit and dispositions
docs/frontend-visual-tokens.md	Palette, type, contrast
docs/frontend-brand-usage.md	Logo/splash usage contract
docs/frontend-visual-style-guidelines.md	Plan 161 living visual style canon
docs/plan-160-acceptance.md	Plan 160 visual overhaul acceptance
docs/plan-161-acceptance.md	Plan 161 style canon enforcement acceptance
docs/plan-162-acceptance.md	Plan 162 Compendium Phase 1 acceptance
docs/plan-165-acceptance.md	Plan 165 visual/a11y release evidence
docs/frontend-visual-release-matrix.md	Route/viewport coverage
docs/browser-gateway-matrix.md	Plan 202 NGINX-only browser matrix
docs/sentience-simulation.md	Plan 202 sentience corpus tiers
docs/plan-202-acceptance.md	Plan 202 combat/visual/gateway/sim acceptance
docs/plans/214-mobile-gameplay-shell.md	Plan 214 mobile gameplay shell
docs/plan-214-acceptance.md	Plan 214 phone shell / card dock acceptance
docs/plans/215-direct-sentience-evolution.md	Plan 215 direct Sentience evolution
docs/plan-215-acceptance.md	Plan 215 Sentience rule acceptance
docs/compendium-editorial-guide.md	Plan 216 player-facing Compendium voice
docs/plans/216-player-facing-compendium-and-item-inspector.md	Plan 216 Compendium / inspector split
docs/plan-216-acceptance.md	Plan 216 acceptance evidence
docs/plans/217-modern-compendium-ux.md	Plan 217 modern Compendium IA / UX
docs/plan-217-acceptance.md	Plan 217 acceptance evidence
docs/plans/218-explicit-movement-commitment.md	Plan 218 explicit Move Species / Pass clarity
docs/plan-218-acceptance.md	Plan 218 acceptance evidence
docs/frontend-narrative-conformance-165.md	Plan 161 commandment review
docs/frontend-human-eval-165.md	Human task script + smoke notes
docs/frontend-privacy-review-165.md	Privacy/DOM review

Frontend routes

• / → branded launch (signed out) or lobby hub (signed in)
• /register, /login
• /compendium — visual library (home, family grids, search, item detail)
• /compendium/:family/:id — canonical entry deep links (legacy ?entry= redirects)
• /lobbies/new, /join, /join/:joinCode, /lobbies/:lobbyId
• /games/:gameId — world-centered SVG board; desktop dual-pane command dock (≥720px) or mobile tabbed dock with persistent Pass (≤719px)
• /campaigns, /campaigns/:runId — boss campaign hub and encounter arc

Session state uses HttpOnly cookies only; the client never stores tokens or hidden cards in browser storage.

Entropy balance corpus

Deterministic match-length evidence (optional slow suite):

docker compose run --rm --no-deps backend uv run pytest -m simulation

Rule normalization: docs/rules-decisions.md (plan 074 section).

Legacy relationship

Use mythinc-cardgame/ to understand historical rules, assets, and behavior. Do not add runtime imports, path hacks, or dependencies from this repository into the legacy tree. When legacy code and written docs disagree, record the discrepancy in docs/rules-decisions.md.