Quickstart

Two paths: local with Docker (recommended for development) or GitHub-free-tier (for the public demo).

Local with Docker

Prerequisites: Docker, Docker Compose, Python 3.12+, uv (recommended) or pip.

git clone https://github.com/neeelkhadwal/market-view.git
cd market-view

# 1. Bring up Neo4j + Postgres (TimescaleDB + pgvector) + MinIO
docker compose up -d
docker compose ps                 # all services should be healthy

# 2. Configure
cp .env.example .env
# edit .env if you need to override defaults

# 3. Install Python deps
uv sync                           # or: pip install -e ".[dev]"

# 4. Apply schema constraints to the empty Neo4j
python -m kg.bootstrap

# 5. Load the static seed (sectors, regimes, indicators, S&P 100, sector maps)
market-view seed validate          # parse + cross-ref check, no DB needed
market-view seed apply             # MERGE everything into Neo4j (idempotent)

# 6. Verify
pytest -m "not integration"

# 7. Start the API
uvicorn api.main:app --reload
# → http://localhost:8000/health
# → http://localhost:7474           Neo4j browser (neo4j / changeme-local-only)
# → http://localhost:9001           MinIO console (minioadmin / minioadmin)

Hosted free tier

The whole project is designed to deploy on free-tier services reachable from GitHub. See the Architecture page for the full topology. In summary:

Component	Service	Free tier
Source, CI, cron, container registry, releases	GitHub	Unlimited for public repos
Static UI + docs	GitHub Pages	1 GB site, 100 GB/mo bandwidth
Property graph	Neo4j AuraDB Free	200k nodes / 400k rels
Postgres + pgvector + audit	Supabase Free	500 MB DB
Object storage	Cloudflare R2 Free	10 GB
Backend container	Hugging Face Spaces	16 GB RAM, sleeps after 48 h
LLM	Bring-your-own (Anthropic / OpenRouter / Ollama)	Maintainer pays $0

Deployment workflow files will land in .github/workflows/ in Phase 4. For now Phase 0 only deploys the docs site to Pages.