mediancode-app

Median Code monorepo. Combines the former mediancode-backend and mediancode-frontend repositories.

What lives here

Path	Purpose
backend/	FastAPI service; see backend/README.md
frontend/	SvelteKit app; see frontend/README.md
api-spec.yaml	Backend-generated OpenAPI contract; frontend-consumed source of truth
docs/	Cross-cutting architecture, standards, protocols, and work records
docs/operations/	Public, value-free configuration and recovery contracts
config/operational-settings.json	Machine-readable operational setting registry; contains no values
.github/workflows/	Path-filtered CI plus backend and frontend deployment
.githooks/	Root Git hooks delegating into backend and frontend commands
Makefile	Root entry points delegating to app-level commands
AGENTS.md, CLAUDE.md, CONTEXT.md	Cross-cutting agent and domain guidance

Quickstart

Prerequisites:

• Git and GNU Make;
• Python 3.13 and Poetry 2.3.x;
• Docker with Compose for PostgreSQL-backed development and tests;
• Bun 1.3.x for the frontend.

CI pins exact tool versions in the workflows. Use the compatible release line above locally; do not install Vercel CLI globally for ordinary development.

# install (one-time)
make install

# run both stacks in parallel
make dev

# run all tests
make test

# verify settings, examples, workflows, and operations docs agree
make config.check

Per-app docs: backend/CLAUDE.md, backend/AGENTS.md, backend/README.md, frontend/README.md.

Operations:

• Configuration and secret-name contract
• Application recovery protocol
• Mac server deployment boundary

Repo file placement policy: docs/architecture/app-root-file-policy.md.

API contract

api-spec.yaml at repo root is the single source of truth. The backend regenerates it from FastAPI routes; the frontend consumes it for type generation. Changes to it trigger both CI pipelines.

Branches

• main — production
• develop — integration / preview environments

Path-filtered CI: only the affected app's pipeline runs when a PR touches one side; both run when api-spec.yaml or root files change. Successful pushes to develop and main deploy through GitHub Actions.

History

Both source repos were rewritten with git filter-repo into the backend/ and frontend/ subdirectories before merge. git log --follow backend/src/... or git log --follow frontend/src/... traces individual files back to their original commits.