Skip to content

DEVELOPER_CONTRIBUTOR_GUIDE.md

Latest commit

 

History

History
175 lines (135 loc) · 3.69 KB

DEVELOPER_CONTRIBUTOR_GUIDE.md

File metadata and controls

175 lines (135 loc) · 3.69 KB

Developer & Contributor Guide

This guide is for developers who want to run, extend, or contribute to openecon-data.

Scope

Use this guide for:

  • local setup
  • environment configuration
  • development workflow
  • testing
  • deployment references
  • contribution process

If you only want to use the product, start with:

Prerequisites

  • Node.js 18+ and npm 9+
  • Python 3.9+
  • OpenRouter API key (required)
  • FRED and Comtrade API keys (recommended)

Local Setup

Clone and run setup script:

Linux/macOS:

git clone https://github.com/hanlulong/openecon-data.git
cd openecon-data
./scripts/setup.sh

Windows PowerShell:

git clone https://github.com/hanlulong/openecon-data.git
cd openecon-data
.\scripts\setup.ps1

Windows CMD:

git clone https://github.com/hanlulong/openecon-data.git
cd openecon-data
scripts\setup.bat

Environment

Create .env in repo root and set:

# Required
LLM_PROVIDER=openrouter
LLM_MODEL=openai/gpt-4o-mini
OPENROUTER_API_KEY=sk-or-...
JWT_SECRET=<random-string>

# Recommended
FRED_API_KEY=...
COMTRADE_API_KEY=...

# Optional (Supabase for production-style auth)
SUPABASE_URL=...
SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_KEY=...

Notes:

  • backend/data/indicators.db is created if missing.
  • backend/data/faiss_index is created/rebuilt on demand when vector search is enabled.
  • In development, Supabase is optional (mock auth path is available).

Run Locally

Run both services:

source backend/.venv/bin/activate
npm run dev

Or run separately:

# Backend
source backend/.venv/bin/activate
npm run dev:backend

# Frontend
npm run dev:frontend

Default URLs:

  • Frontend: http://localhost:5173
  • Backend: http://localhost:3001
  • MCP endpoint: http://localhost:3001/mcp

MCP For Development

Hosted endpoint:

  • https://data.openecon.ai/mcp

Local endpoint:

  • http://localhost:3001/mcp

Codex:

codex mcp add openecon-data-local --url http://localhost:3001/mcp
codex mcp get openecon-data-local

Claude Code:

claude mcp add --transport sse openecon-data-local http://localhost:3001/mcp --scope user
claude mcp get openecon-data-local

Testing

Backend:

cd backend
source .venv/bin/activate
python -m unittest discover -s backend/tests

Frontend:

npm run test --workspace=packages/frontend

Additional references:

Architecture At A Glance

openecon-data has:

  • FastAPI backend in backend/
  • React + TypeScript frontend in packages/frontend/
  • Provider integrations in backend/providers/
  • Query orchestration and routing in backend/services/

Detailed references:

Deployment

Primary references:

Production checklist:

  1. Generate strong JWT_SECRET.
  2. Configure ALLOWED_ORIGINS for your domain.
  3. Set production auth configuration (Supabase keys).
  4. Build frontend and run backend with production settings.
  5. Put HTTPS reverse proxy in front of backend.

Contribution Workflow

  1. Fork the repository.
  2. Create a branch: git checkout -b feature/<name>.
  3. Make changes with tests and docs updates.
  4. Run relevant test suites.
  5. Open a pull request to main.

More details: