Skip to main content

Development Setup

Complete guide for getting the PolySuggest development environment running.

Prerequisites​

  • Python 3.11+
  • Node.js 18+
  • PostgreSQL 14+
  • Docker & Docker Compose (recommended)

Quick Start (Docker)​

1. Clone & Start Databases​

git clone https://github.com/BeachTexture/PolySuggest.git
cd polysuggest
docker-compose up -d postgres redis

2. Install Dependencies​

Option A: Development from PyPI

# Install the CLI
pip install polymarket-ai-market-suggestor

# Install dev dependencies for frontend
cd polysuggest
npm install

Option B: Development from Source (for contributing)

# Backend
cd polymarket-ai-market-suggestor
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Frontend
cd ../polysuggest
npm install

3. Set Environment Variables​

Create polymarket-ai-market-suggestor/.env:

DATABASE_URL=postgresql://user:password@localhost:5432/polysuggest
GAMMA_API_URL=https://api.gamma.polymarket.com
OPENAI_API_KEY=sk_...
REDIS_URL=redis://localhost:6379/0
ENVIRONMENT=development

4. Initialize Database​

cd polymarket-ai-market-suggestor
alembic upgrade head

5. Run Services​

# Terminal 1: Backend
cd polymarket-ai-market-suggestor
uvicorn src.polysuggest.api.main:app --reload

# Terminal 2: Frontend
cd polysuggest
npm run dev

Access at:

Testing​

cd polymarket-ai-market-suggestor

# Run all tests
pytest

# Run with coverage
pytest --cov=src/polysuggest tests/

# Specific test
pytest tests/test_market_data.py::test_fetch -v

Linting & Formatting​

cd polymarket-ai-market-suggestor

# Check
ruff check src/ tests/

# Fix
ruff check --fix src/

# Format
black src/ tests/ --line-length=100

Database Migrations​

cd polymarket-ai-market-suggestor

# Create migration
alembic revision --autogenerate -m "Description"

# Apply
alembic upgrade head

# Rollback
alembic downgrade -1

Project Structure​

polysuggest/
├── polymarket-ai-market-suggestor/
│   ├── src/polysuggest/
│   │   ├── api/
│   │   │   ├── main.py
│   │   │   └── routes/
│   │   ├── core/
│   │   │   ├── market_data.py
│   │   │   ├── edge_detector.py
│   │   │   └── ...
│   │   ├── ai/
│   │   ├── db/
│   │   ├── cli/
│   │   └── utils/
│   ├── tests/
│   ├── requirements.txt
│   └── alembic.ini
│
├── polysuggest/
│   ├── app/
│   │   ├── (dashboard)/
│   │   └── layout.tsx
│   ├── lib/
│   ├── next.config.js
│   └── package.json
│
└── docker-compose.yml

Debugging​

Backend (VSCode)​

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: FastAPI",
      "type": "python",
      "module": "uvicorn",
      "args": ["src.polysuggest.api.main:app", "--reload"]
    }
  ]
}

Frontend​

Use Chrome DevTools (F12) or VSCode debugger.

Common Issues​

Port in use:

lsof -i :8000
kill -9 <PID>

Database connection error:

psql -U postgres -h localhost

Module not found:

pip install -e .

See also: Architecture Guide, CLI Reference