Developer Setup

Requirements

Docker, Python 3.12 and Node 22.

First run

git clone https://github.com/ahmershahdev/marketclock.git
cd marketclock
cp .env.example .env                              # set your own passwords
docker compose up -d                              # MySQL 8.4, Redis 8.2 and the API on :5000
docker compose exec api alembic upgrade head      # tables
docker compose exec api flask --app wsgi seed     # sourced settlement cycles and calendars

cd frontend
npm install
npm run dev                                       # web app on http://localhost:3000

Environment

Variable	What it is
MYSQL_USER, MYSQL_PASSWORD, MYSQL_ROOT_PASSWORD	database credentials for Compose
DATABASE_URL, TEST_DATABASE_URL, REDIS_URL	for running the API and tests on the host
MARKETCLOCK_ENV	dev, test or prod
RATE_LIMIT_PER_MINUTE	requests a minute per client (default 120, 0 turns it off)

Tests and linters

CI runs these on every pull request; run them first.

cd backend                        # Windows paths; on macOS or Linux use .venv/bin/
py -3.12 -m venv .venv
.venv/Scripts/pip install -r requirements-dev.txt
.venv/Scripts/pytest              # needs the Compose MySQL and TEST_DATABASE_URL
.venv/Scripts/ruff check . && .venv/Scripts/ruff format --check . && .venv/Scripts/mypy

cd ../frontend
npm run lint && npm run typecheck && npm test && npm run build

After changing an API model, regenerate the schema and the web app's types in the same PR:

cd backend && .venv/Scripts/python write_openapi.py
cd ../frontend && npm run api:types

Tests use MySQL, never SQLite.