Financial market prediction platform using Fed-style modeling and news sentiment analysis.
| Layer | Tech |
|---|---|
| Runtime | Bun |
| API | Hono |
| Dashboard | Next.js 16 + shadcn/ui |
| ML | Python (FastAPI) |
| Database | PostgreSQL + TimescaleDB (2 databases) |
| Queue | BullMQ + Redis |
| Deployment | SST (AWS) |
Before running the project, ensure you have:
| Requirement | Version | Check Command |
|---|---|---|
| Node.js | 20+ | node --version |
| pnpm | 10+ | pnpm --version |
| Docker | Latest | docker --version |
| Bun | 1.1+ | bun --version |
# Clone and setup everything
git clone <repo-url> && cd volatio
make setupThis single command:
- Installs all dependencies (
pnpm install) - Starts Docker services (TimescaleDB × 2 + Redis)
- Waits for services to be healthy
- Runs database migrations for both databases
- Sets up TimescaleDB hypertables for time-series data
- Seeds the superuser account
- Seeds sample demonstration data
Alternative using pnpm:
pnpm setupCopy the example environment file:
cp .env.example .envThe .env.example includes all required and optional variables with documentation.
For local development, the defaults work out of the box with Docker.
Required for auth:
# Generate a secure auth secret
openssl rand -base64 32
# Add to .env as AUTH_SECRET=<generated-value>pnpm devOpens:
- Dashboard: http://localhost:3000
- API: http://localhost:3001
- API Docs: http://localhost:3001/docs
Use the seeded test account:
- Email:
admin@volatio.io - Password:
Trading2024!
pnpm checkThis runs scripts/check-prereqs.sh to verify Docker, Postgres, and Redis are running.
Volatio uses two TimescaleDB databases:
| Database | Port | Package | Purpose |
|---|---|---|---|
| Main DB | 5432 | @volatio/db |
Users, economic calendars, news, job schedules |
| Market DB | 5433 | @volatio/market-db |
OHLCV bars, FRED data, SEC filings, Fed documents |
Both databases use TimescaleDB hypertables for efficient time-series queries.
| Command | Description |
|---|---|
pnpm db:setup |
Setup main database (migrate + hypertables + seed) |
pnpm market-db:setup |
Setup market database (migrate + hypertables + seed) |
pnpm db:setup:all |
Setup both databases |
pnpm db:migrate |
Run main DB migrations only |
pnpm market-db:migrate |
Run market DB migrations only |
pnpm db:seed |
Seed superuser account |
pnpm db:seed:sample |
Seed sample demonstration data |
pnpm market-db:seed |
Seed sample market data |
pnpm db:reset |
Drop and recreate main database |
pnpm market-db:reset |
Drop and recreate market database |
| Command | Description |
|---|---|
make setup |
Full setup from fresh clone (all dependencies + both databases) |
make db-setup |
Setup both databases (when Docker is already running) |
make db-reset |
Reset and reseed all databases (WARNING: destroys data) |
make kill-servers |
Kill zombie processes on dev ports |
make test-all |
Run all tests (TypeScript + Python) |
make py-setup |
Setup Python ML environment |
| Command | Description |
|---|---|
pnpm dev |
Start all dev servers (Dashboard + API) |
pnpm dev:dashboard |
Start only Dashboard |
pnpm dev:api |
Start only API |
pnpm test |
Run unit tests (Vitest) |
pnpm test:e2e |
Run E2E tests (Playwright) |
pnpm lint |
Check code style |
pnpm typecheck |
Type check all packages |
| Command | Description |
|---|---|
pnpm docker:up |
Start all containers (Postgres × 2 + Redis) |
pnpm docker:down |
Stop containers |
pnpm docker:logs |
Tail container logs |
Dev and E2E tests use separate ports to avoid conflicts:
| Service | Dev Port | E2E Port | Notes |
|---|---|---|---|
| Dashboard | 3000 | 3100 | Next.js |
| API | 3001 | 3101 | Hono (Bun) |
| Main PostgreSQL | 5432 | 5432 | Docker (TimescaleDB) |
| Market PostgreSQL | 5433 | 5433 | Docker (TimescaleDB) |
| Redis | 6379 | 6379 | Docker |
| ML Service | 8000 | 8000 | FastAPI |
If ports are stuck from zombie processes:
# Kill all dev server processes
make kill-servers
# Or use pnpm
pnpm clean:ports
# Check what's running on ports
lsof -i :3000,:3001,:3100,:3101Copy the example and fill in values:
cp .env.example .envThe .env.example file is organized into REQUIRED and OPTIONAL sections.
| Variable | Description | Default |
|---|---|---|
DATABASE_URL |
Main PostgreSQL connection | postgres://volatio:vibes123@localhost:5432/volatio |
MARKET_DATABASE_URL |
Market data PostgreSQL connection | postgres://volatio:vibes123@localhost:5433/volatio_market |
AUTH_SECRET |
NextAuth secret | Generate with openssl rand -base64 32 |
REDIS_URL |
Redis connection string | redis://localhost:6379 |
| Variable | Description | Default |
|---|---|---|
NEXT_PUBLIC_API_URL |
API URL for dashboard | http://localhost:3001 |
ML_SERVICE_URL |
Python ML service URL | http://localhost:8000 |
SUPERUSER_EMAIL |
Seed user email | admin@volatio.io |
SUPERUSER_PASSWORD |
Seed user password | Trading2024! |
POLYGON_API_KEY |
Polygon.io API key | For market data |
FRED_API_KEY |
Federal Reserve API key | For economic data |
BRIGHTDATA_PROXY_URL |
Proxy for web scraping | For scrapers |
These are set automatically by Playwright config:
| Variable | Description |
|---|---|
PLAYWRIGHT |
Set to 1 to enable test auth bypass |
AUTH_URL |
Points to E2E dashboard port |
# Run all unit tests
pnpm test
# Watch mode
pnpm test:watch
# With coverage
pnpm test:coverageE2E tests require the database to be seeded (for test user login):
# Ensure database is ready
pnpm db:setup
# Run E2E tests (starts servers automatically)
pnpm test:e2e
# With UI for debugging
pnpm test:e2e:ui
# Headed mode (see browser)
pnpm test:e2e:headed# TypeScript + Python
make test-all# Check if Docker is running
docker ps
# Start Docker services
pnpm docker:up
# Check prerequisites
pnpm check# Kill zombie processes
make kill-servers
# Run tests with explicit timeout
pnpm test:e2e --timeout=30000# Re-run migrations for both databases
pnpm db:migrate
pnpm market-db:migrate
# Or reset and re-seed everything
make db-reset# Find what's using the port
lsof -i :3000
# Kill all dev ports
make kill-serversEnsure the test user exists:
# Re-seed the database
pnpm db:seedvolatio/
├── apps/
│ ├── api/ # Hono API server (Bun)
│ ├── dashboard/ # Next.js dashboard
│ └── agents/ # Mastra AI agents
├── packages/
│ ├── db/ # Main database (Drizzle ORM + migrations)
│ ├── market-db/ # Market data database (OHLCV, FRED, SEC, Fed)
│ ├── jobs/ # BullMQ job queues + scrapers
│ ├── shared/ # Shared types + utilities
│ ├── browser/ # Playwright browser automation
│ ├── scraper/ # Web scraping utilities
│ └── agents/ # Agent definitions
├── services/
│ └── ml/ # Python FastAPI ML service
├── e2e/ # Playwright E2E tests
├── scripts/ # Dev scripts
└── docs/ # Documentation
docs/architecture.md— System architecture & design decisionsdocs/plans/— Feature plans & RFCs
Private