SPARC

SPARC is an internal labor forecasting and cost intelligence app.

Local Docker

docker compose up --build

• Frontend: http://localhost:5173
• Backend: http://localhost:8000
• API docs: http://localhost:8000/docs
• PostgreSQL: localhost:5433

Useful local commands:

docker compose exec backend python -m app.cli reset-db
docker compose exec backend python -m app.cli seed-db
docker compose exec backend pytest
docker compose exec frontend npm run build

Stage-Style Container

Stage uses one SPARC app container: FastAPI serves /api/*, health checks, and the built React frontend.

docker compose -f docker-compose.stage.yml --profile migrate run --rm migrate
docker compose -f docker-compose.stage.yml up --build app

For stage, provide DATABASE_URL from Azure PostgreSQL/Key Vault and keep:

AUTO_CREATE_SCHEMA=false
SEED_ON_STARTUP=false

Local Without Docker

Run PostgreSQL locally or use the Compose postgres service, then:

python -m venv backend/.venv
source backend/.venv/bin/activate
pip install -r backend/requirements.txt
uvicorn app.main:app --app-dir backend --reload

npm install --prefix frontend
npm --prefix frontend run dev

Notes

• Product scope and constraints live in docs/product-brief.md.
• MVP milestones live in docs/build-milestones.md.
• MVP completion notes live in docs/mvp-completion.md.
• Deployment notes live in docs/deployment.md.
• STAGE deployment direction lives in docs/stage-environment-plan.md.
• Seeding is reference-only: buckets, FY2026 months from July 2025 through June 2026, and baseline app settings. It does not create demo products, people, forecasts, actuals, or Jira mappings.
• Jira sync is app-owned and server-side. Configure JIRA_SITE_URL, JIRA_API_EMAIL, and JIRA_API_TOKEN in .env, restart Compose, then use Product Settings to map SPARC products to Jira projects before running live sync. Live Jira Actuals sync also runs automatically once every morning at 07:30 Central by default.
• STAGE is expected to run containerized on Kubernetes with Azure PostgreSQL and Key Vault-backed secrets.
• For STAGE, set AUTO_CREATE_SCHEMA=false and run alembic upgrade head against Azure PostgreSQL before the app starts.