Development Setup¶

# Check versions
git --version
python --version
node --version
npm --version
docker --version  # optional

# Clone your fork
git clone https://github.com/YOUR_USERNAME/opencomplai.git
cd opencomplai

# Add upstream remote
git remote add upstream https://github.com/Checkref-co/opencomplai.git

# Verify remotes
git remote -v
# origin: your fork
# upstream: original repo

# Create venv
python -m venv venv

# Activate venv
# Linux/Mac:
source venv/bin/activate

# Windows:
venv\Scripts\activate

# Upgrade pip
pip install --upgrade pip

# Install dev dependencies
pip install -e ".[dev]"

# This installs:
# - opencomplai package (editable)
# - pytest (testing)
# - black (formatting)
# - mypy (type checking)
# - ruff (linting)

# Create .env file
cat > .env << 'EOF'
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/opencomplai

# Redis
REDIS_URL=redis://localhost:6379

# API
API_KEY=sk_test_xyz123...
API_SECRET=secret_xyz...
DEBUG=true

# Email (optional)
EMAIL_PROVIDER=console  # or sendgrid
EOF

# Make sure .env is in .gitignore
echo ".env" >> .gitignore

# Start PostgreSQL
docker run --name opencomplai-db \
  -e POSTGRES_USER=opencomplai \
  -e POSTGRES_PASSWORD=dev123 \
  -e POSTGRES_DB=opencomplai \
  -p 5432:5432 \
  -d postgres:14

# Start Redis
docker run --name opencomplai-redis \
  -p 6379:6379 \
  -d redis:7

# Verify connections
psql -h localhost -U opencomplai -d opencomplai
redis-cli ping

# macOS (Homebrew)
brew install postgresql redis
brew services start postgresql
brew services start redis

# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib redis-server
sudo systemctl start postgresql
sudo systemctl start redis-server

# Windows
# Download from https://www.postgresql.org/download/windows/
# Download from https://github.com/microsoftarchive/redis/releases

# Apply database migrations
python -m alembic upgrade head

# Or using Flask
flask db upgrade

# Run tests
pytest

# Run specific test
pytest tests/test_documents.py

# Run with coverage
pytest --cov

# Run linters
black --check .
mypy .
ruff check .

# Auto-format code
black .

# Using FastAPI
uvicorn src.main:app --reload

# Using Flask
flask run

# Server should be at http://localhost:8000

# Navigate to frontend directory (if separate)
cd packages/web

# Install npm packages
npm install

# Create .env.local
cat > .env.local << 'EOF'
REACT_APP_API_URL=http://localhost:8000
REACT_APP_ENV=development
EOF

# Run tests
npm test

# Run linters
npm run lint

# Format code
npm run format

# Build for production
npm run build

# Start development server
npm start

# Server should be at http://localhost:3000

# Install pre-commit tool
pip install pre-commit

# Or using Homebrew
brew install pre-commit

# Create .pre-commit-config.yaml in repo root
cat > .pre-commit-config.yaml << 'EOF'
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

  - repo: https://github.com/psf/black
    rev: 23.3.0
    hooks:
      - id: black

  - repo: https://github.com/charliermarsh/ruff
    rev: v0.0.260
    hooks:
      - id: ruff
        args: [--fix]

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.0.1
    hooks:
      - id: mypy
EOF

# Install pre-commit hooks
pre-commit install

# Run hooks manually
pre-commit run --all-files

# Run backend tests
cd <backend-dir>
pytest

# Start server
uvicorn main:app --reload
# Visit http://localhost:8000/docs for API docs

# Run frontend tests
cd packages/web
npm test

# Start dev server
npm start
# Visit http://localhost:3000

# Connect to database
psql -h localhost -U opencomplai -d opencomplai

# Run a query
SELECT COUNT(*) FROM documents;

# Test Redis connection
redis-cli ping
# Should output: PONG

opencomplai/
├── docs/                    ← Documentation (MkDocs)
│   ├── mkdocs.yml
│   └── src/
│       ├── api/
│       ├── guides/
│       ├── examples/
│       ├── architecture/
│       └── ...
├── packages/
│   ├── core/                ← Core Python library
│   │   ├── src/opencomplai/
│   │   ├── tests/
│   │   └── setup.py
│   ├── sdk-python/          ← Python SDK
│   │   ├── src/
│   │   ├── tests/
│   │   └── setup.py
│   ├── sdk-js/              ← JavaScript SDK
│   │   ├── src/
│   │   ├── tests/
│   │   └── package.json
│   ├── web/                 ← Frontend React app
│   │   ├── src/
│   │   ├── tests/
│   │   └── package.json
│   ├── api/                 ← API server
│   │   ├── src/
│   │   ├── tests/
│   │   └── requirements.txt
│   └── cli/                 ← CLI tool
├── .github/
│   └── workflows/           ← GitHub Actions
├── scripts/                 ← Utility scripts
├── .env.example             ← Environment template
├── .gitignore
├── README.md
└── CONTRIBUTING.md

# Python
pip list --outdated
pip install --upgrade PACKAGE_NAME
pip install -r requirements.txt --upgrade

# JavaScript
npm outdated
npm update
npm install PACKAGE_NAME@latest

# Update from upstream
git fetch upstream
git rebase upstream/main

# Create feature branch
git checkout -b feature/my-feature

# Make changes
# ... edit files ...

# Test
pytest        # Python
npm test      # JavaScript

# Commit
git add .
git commit -m "feat: my feature"

# Push
git push origin feature/my-feature

# Create PR on GitHub

# Python debugging
import pdb; pdb.set_trace()  # Set breakpoint
python -m pdb script.py      # Run under debugger

# JavaScript debugging
debugger;                     # Set breakpoint
node --inspect script.js     # Run with inspector

# Python tests with coverage
pytest --cov --cov-report=html

# JavaScript tests
npm test -- --coverage

# All tests together (if configured)
npm run test:all

# Reinstall editable package
pip install -e ".[dev]"

# Verify installation
python -c "import opencomplai; print(opencomplai.__version__)"

# Check PostgreSQL running
ps aux | grep postgres

# Check connection string
echo $DATABASE_URL

# Test connection
psql $DATABASE_URL

# If using Docker
docker ps | grep postgres
docker logs opencomplai-db

# Find process using port
lsof -i :8000    # Linux/Mac
netstat -ano | findstr :8000  # Windows

# Kill process
kill -9 PID

# Run hooks manually to see errors
pre-commit run --all-files

# Skip hooks temporarily
git commit --no-verify

# Or fix issues and re-commit
git add .
git commit -m "fix: linting issues"

# Run test with verbose output
pytest -v

# Run specific test
pytest tests/test_file.py::test_function

# Show print statements
pytest -s

# Stop on first failure
pytest -x

- Python
- Pylance
- Black Formatter
- isort
- ES7+ React/Redux/React-Native snippets
- ESLint
- Prettier

{
  "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": false,
  "python.linting.flake8Enabled": false,
  "python.linting.mypyEnabled": true,
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": true
    }
  },
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  }
}