A prototype exploring the architectural gap between real-time state management (hot layer) and traceable event history (audit layer) — two concerns that are usually treated separately but interact in every move-based game.

Live Demo

• Connect 4 Real-Time Prototype
  • Table of Contents
  • Architecture
  • Stack
  • Project Layout
  • Quick Start
  • Environment Variables
  • API
    • WebSocket Protocol
  • Testing
    • E2E Browser Tests (Playwright)
  • Development
  • AWS Deployment
  • Trade-offs

flowchart LR
    Client["🌐 Browser"]

    subgraph Compute["FastAPI · Uvicorn"]
        API["REST + WebSocket\nPydantic validation\nSETNX locks"]
    end

    subgraph Hot["🔴 Hot Layer"]
        Redis[("Redis\nBoard state\nTTL: 24 h")]
    end

    subgraph Cold["🔵 Cold Layer"]
        PG[("PostgreSQL\nPlayers · Games\nLeaderboard · ELO")]
    end

    subgraph Audit["🟢 Audit Layer"]
        Log["JSONL\nAppend-only\nevents.log"]
    end

    Client -- "REST / WebSocket" --> API
    API -- "read · write · lock" --> Redis
    API -- "players · games · moves" --> PG
    API -- "fire-and-forget append" --> Log

Each layer is optimised for its access pattern: Redis for sub-millisecond reads during active play, PostgreSQL for relational queries and leaderboard, and an append-only log as the immutable event record.

app/              # FastAPI backend — routes, game logic, Redis/DB layers
  routes/         #   REST endpoints (games, players, matchmaking)
static/           # Single-page frontend (vanilla JS + CSS, zero build step)
tests/
  unit/           # Pure logic: game, models, store, audit, ELO (incl. Hypothesis)
  integration/    # Full HTTP/WS journeys with FakeRedis + mock DB
  e2e/            # Playwright browser tests (opt-in via --e2e)
infra/            # AWS CDK stack (Fargate + RDS + ElastiCache)
alembic/          # Database migrations
docs/             # Architecture rationale + deployment guide

git clone https://github.com/izu-x/connect4-realtime-prototype.git
cd connect4-realtime-prototype
./setup.sh

Open http://localhost:8000 to play, or http://localhost:8000/docs for the interactive API explorer.

Mise users: The project includes a .mise.toml that auto-selects Python 3.13 and activates .venv. If mise is installed, ./setup.sh native will configure the shell hook automatically. For manual setup: mise trust && eval "$(mise activate zsh)" (or replace zsh with your shell).

docker compose up --build

# Make a move — player 1 drops into column 3
curl -X POST http://localhost:8000/games/my-game/move \
  -H "Content-Type: application/json" \
  -d '{"game_id": "my-game", "player": 1, "column": 3}'

# Current board state
curl http://localhost:8000/games/my-game

# Real-time WebSocket
wscat -c ws://localhost:8000/ws/my-game
# Send: {"player": 2, "column": 4}

In AWS deployments, database and Redis credentials are injected by CDK from Secrets Manager at runtime.

Full REST API documentation is auto-generated — run the server and visit /docs for the interactive OpenAPI reference.

Connect to ws://host/ws/{game_id} and exchange JSON messages:

The first move from a WebSocket connection permanently binds that socket to the sending player number. Use separate connections for each player.

pytest -v                  # 267 unit + integration tests, ~2 s, no external deps
pytest tests/unit/         # Unit tests only (includes property-based / Hypothesis)
pytest tests/integration/  # Integration tests only
pytest --e2e -v tests/e2e/ # 123 E2E browser tests (requires docker compose up)

All unit and integration tests run against an in-process FakeRedis and mock DB sessions — no external services required.

End-to-end tests drive a real Chromium browser against the running application. They cover user flows that unit/integration tests cannot: CSS animations, screen transitions, WebSocket-driven updates across two browser tabs, page refresh recovery, and session persistence.

# 1. Install E2E dependencies + browser
pip install -e ".[dev,e2e]"
playwright install chromium

# 2. Start the full stack
docker compose up --build -d

# 3. Run E2E tests
pytest --e2e -v tests/e2e/

# Run a specific E2E test
pytest --e2e -v tests/e2e/test_game_lobby.py::test_matchmaking_cancel_and_retry_spinner_animates

E2E tests are opt-in — they require the --e2e flag and a running server. Without --e2e, they are automatically skipped so pytest -v remains fast and dependency-free.

pip install -e ".[dev]"    # Install with dev dependencies
pip install -e ".[e2e]"    # Install E2E test dependencies (Playwright)

ruff check app/ tests/     # Lint
ruff format app/ tests/    # Format

pytest -v                  # Run unit + integration tests
pytest --e2e -v            # Run E2E browser tests (requires docker compose up)

alembic upgrade head       # Apply database migrations
alembic revision --autogenerate -m "description"  # Generate migration

Pre-commit hooks (trailing whitespace, YAML/TOML checks, ruff, pytest) are configured — run pre-commit install once after cloning to enable them.

cdk deploy --profile <your-profile> --context free_tier=true

Deploys to ECS Fargate with RDS PostgreSQL and ElastiCache Redis. See docs/AWS_DEPLOYMENT.md for full details.

For full architecture rationale see docs/TECHNICAL_DECISIONS.md.