vizzhub

Internal tracking platform.

Setup

Prerequisites

• uv (Python toolchain), Node.js 18+, PostgreSQL 16, Redis (optional). uv installs the right Python automatically.

Backend

cd backend
uv sync                 # installs Python 3.13 + all deps from uv.lock
cp .env.example .env    # edit as needed
uv run python run_server.py  # http://localhost:8000, docs at /docs

Frontend

cd frontend
npm install
npm run dev  # http://localhost:5173

Worker (background jobs)

cd backend
uv run arq app.worker.settings.WorkerSettings

Docker alternative

docker-compose up -d

Dev mode shortcuts

• DEBUG=true (backend) — auth bypassed
• BYPASS_AUTH=true (frontend) — no login required

Stack

• Backend: FastAPI, PostgreSQL 16, SQLAlchemy 2.0 (async), ARQ, Redis
• Frontend: React 18, TypeScript, Vite, Tailwind, shadcn/ui, React Query, Recharts
• Infra: AWS (EC2, RDS, ALB, ECR), Terraform, GitHub Actions
• Observability: structlog, Sentry, Prometheus metrics, CloudWatch Logs — details

Branches

Branch	Purpose
main	Production
dev	Active development
feature/*	PRs to dev

License

Copyright (c) 2026 Vizzuality. All rights reserved. See LICENSE.md.