SolveStream Server

Backend for SolveStream — receives whiteboard photos, produces educational video explanations.

Architecture: Node.js Express API + Python worker + TypeScript/Remotion worker + Supabase + AWS (SQS, S3). Local dev uses LocalStack for AWS services.

Quick start (separate terminals)

Prerequisites: Node.js 20+, Python 3.11 or 3.12 (see dev.sh for worker Python notes), and Docker with Docker Compose (for LocalStack).

1. AWS locally (LocalStack — SQS + S3)
   From the repo root:

   docker compose up localstack

   This starts LocalStack on port 4566 and runs localstack/init-aws.sh on ready (SQS queues + S3 buckets). If you ever need to re-seed resources from your host, install awscli-local and run bash localstack/init-aws.sh.

2. Run migrations

   npx supabase db push

   Or apply manually via Supabase Dashboard → SQL Editor.

3. API (Node / npx)

   cd server/api && npm install && cp .env.example .env
   npx tsx src/index.ts

   For reload-on-change, use npm run dev instead of the npx line.

4. Python pipeline worker (Manim) — pip

   cd server/worker
   python3 -m venv .venv && source .venv/bin/activate
   pip install -r requirements.txt
   cp .env.example .env   # first time only
   python -m src.consumer

5. CAS service — pip (used by the TypeScript worker; point CAS_SERVICE_URL at it)

   cd server/cas-service
   python3 -m venv .venv && source .venv/bin/activate
   pip install -r requirements.txt
   uvicorn app:app --host 127.0.0.1 --port 8090

6. TypeScript worker (Remotion)

   cd server/worker-ts && cp .env.example .env && npm install && npm run dev

7. Route a dev job to the TS worker

   ./test-pipeline.sh test-images/problem-with-answer.png Calculus slow_teach typescript

Project structure

SolveStream-Server/
├── server/
│   ├── api/          # Node.js Express API
│   ├── worker/       # Python pipeline worker (Manim)
│   ├── worker-ts/    # TypeScript pipeline worker (Remotion)
│   ├── cas-service/  # SymPy CAS HTTP API
│   └── migrations/   # SQL migrations
├── localstack/       # LocalStack init scripts
├── docker-compose.yml
├── MasterDoc.md      # Full documentation
└── README.md

See MasterDoc.md for full documentation.

npx tsx src/index.ts (api) docker compose up (worker, localstack, cas-service) stripe listen --forward-to localhost:3000/v1/webhooks/stripe (stripe cli)