Marvox Development Guide

Status: Active (Storyworld Production Studio)

This guide reflects the current PostgreSQL-only, Docker-based development setup with the inference provider backend.

Prerequisites

• Docker Desktop (or Docker Engine + Docker Compose) — required for PostgreSQL + Redis
• Python 3.11+ (match production runtime)
• Node.js 20.9+, npm 10+

1. Start Docker Services

PostgreSQL and Redis must run via Docker:

bashCopy
docker-compose up -d

Verify connectivity:

bashCopy
docker ps  # Should show postgres and redis containers running

2. Install Dependencies

bashCopy
pip install -r requirements.txt
npm install

3. Environment Setup

1. Copy .env.example to .env.
2. Set required values:

envCopy
DATABASE_URL=postgresql://marvox:marvox@localhost:5432/marvox
REDIS_URL=redis://localhost:6379/0
OPENAI_API_KEY=sk-...
JWT_SECRET_KEY=change-me-to-random-256-bit-value

Optional but common:

• OPENAI_MODEL_NAME (configures the language model)
• CORS_ALLOWED_ORIGINS
• VECTOR_DB_BACKEND (default: pgvector — PostgreSQL is the only supported vector backend)

4. Run Services

Backend:

bashCopy
# Terminal 1
source .venv/bin/activate
python main.py

Frontend:

bashCopy
# Terminal 2
npm run dev

API docs: http://localhost:8000/docs
Frontend: http://localhost:3000

Auth in Development

Most /api/* routes require a JWT Bearer token.

Register:

bashCopy
curl -X POST http://localhost:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"password","name":"You"}'

Or demo login:

bashCopy
curl -X POST http://localhost:8000/api/auth/demo-login \
  -H "Content-Type: application/json"

Useful Scripts

• scripts/export_openapi.py exports OpenAPI to docs/openapi.json
• scripts/scan_env_vars.py builds the env var inventory
• scripts/scan_routes.py builds the route inventory
• scripts/run_docs_checks.sh runs doc link checks and OpenAPI diff

Tests

Backend tests:

bashCopy
pytest tests/

Frontend checks:

bashCopy
npm run type-check

E2E tests (Playwright):

bashCopy
npx playwright test

Documentation Source of Truth

• API reference is generated from docs/openapi.json into docs/API.md
• Primary onboarding docs: START_HERE.md and README.md
• System design: ARCHITECTURE.md

Deployment

See DEPLOYMENT.md for Railway + Vercel deployment and production environment variables.