Skip to content

Development Setup

This page covers the full development environment setup: installing tools, configuring your IDE, enabling pre-commit hooks, and creating environment files.

Prerequisites

Tool Version Purpose
Python 3.12+ Backend runtime
Node.js 20+ Frontend runtime
npm (bundled) Frontend package manager
pip (bundled) Backend package manager
make any Monorepo task runner
pre-commit 3.5+ Git hook manager

Verify versions

python --version   # 3.12.x
node --version     # v20.x.x
make --version
pre-commit --version

Install Dependencies

One-command install

From the repository root:

make install

This runs three steps:

  1. Installs pre-commit hooks
  2. pip install -e ".[dev,graph]" in backend/ (all runtime, dev, and graph deps from pyproject.toml)
  3. npm install in frontend/

Manual install

cd backend
pip install -e .               # runtime only
pip install -e ".[dev]"        # + linters & tests
pip install -e ".[dev,graph]"  # full development with graph features

cd frontend
npm install

pip install pre-commit
pre-commit install

Pre-commit Hooks

AXIS uses pre-commit to run quality checks on every commit. The hooks are defined in .pre-commit-config.yaml at the repo root.

What runs on commit

Hook Scope What it does
trailing-whitespace All files Strips trailing whitespace
end-of-file-fixer All files Ensures files end with a newline
check-yaml YAML files Validates YAML syntax
check-json JSON files Validates JSON syntax
check-added-large-files All files Blocks files over 500KB
check-merge-conflict All files Detects merge conflict markers
detect-private-key All files Blocks accidental key commits
ruff backend/ Lint + auto-fix Python
ruff-format backend/ Format Python
prettier frontend/ Format JS/TS/CSS/JSON/MD
eslint frontend/ Lint TypeScript

Run hooks manually

# Run on staged files
pre-commit run

# Run on all files
pre-commit run --all-files

# Or via Makefile
make pre-commit-all

Skip hooks (escape hatch)

In rare cases where you need to bypass hooks temporarily:

git commit --no-verify -m "WIP: work in progress"

Warning

Only skip hooks for temporary WIP commits. CI will still enforce all checks.

Environment Files

AXIS uses .env files for configuration. These are git-ignored and must be created manually.

Backend: backend/.env

backend/.env
# Server (required)
HOST=127.0.0.1
PORT=8500
DEBUG=true
FRONTEND_URL=http://localhost:3500

# AI / Copilot (optional)
OPENAI_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
LLM_MODEL_NAME=gpt-4

# Database (optional -- only needed for DB features)
human_signals_db_host=localhost
human_signals_db_port=5432
human_signals_db_name=human_signals
human_signals_db_user=postgres
human_signals_db_password=secret

# Graph DB (optional -- only needed for Knowledge Graph)
graph_db_host=localhost
graph_db_port=6379
graph_db_name=axis
graph_db_password=

Frontend: frontend/.env.local

frontend/.env.local
NEXT_PUBLIC_API_URL=http://localhost:8500

Frontend env var rules

Only NEXT_PUBLIC_* variables are exposed to the browser. Never place secrets in this file.

Keep secrets out of version control

The .gitignore already excludes .env files, but never paste API keys into tracked files.

IDE Configuration

Create or merge into .vscode/extensions.json:

.vscode/extensions.json
{
  "recommendations": [
    "ms-python.python",
    "charliermarsh.ruff",
    "ms-python.mypy-type-checker",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "ms-playwright.playwright",
    "yzhang.markdown-all-in-one"
  ]
}

Workspace Settings

Create or merge into .vscode/settings.json:

.vscode/settings.json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit",
    "source.organizeImports": "never"
  },

  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.codeActionsOnSave": {
      "source.fixAll.ruff": "explicit",
      "source.organizeImports.ruff": "explicit"
    }
  },

  "python.analysis.typeCheckingMode": "basic",
  "ruff.lint.args": ["--config=backend/pyproject.toml"],

  "typescript.preferences.importModuleSpecifier": "non-relative",
  "typescript.tsdk": "frontend/node_modules/typescript/lib",

  "tailwindCSS.experimental.classRegex": [
    ["cn\\(([^)]*)\\)", "'([^']*)'"]
  ],

  "files.exclude": {
    "**/__pycache__": true,
    "**/.pytest_cache": true,
    "**/.ruff_cache": true,
    "**/.mypy_cache": true,
    "**/node_modules": true,
    "**/.next": true
  }
}

Other Editors

The key requirements for any editor:

  • Python: Ruff for linting/formatting, mypy for type checking
  • TypeScript: ESLint with next/core-web-vitals config, Prettier for formatting
  • Path alias: Configure @/ to resolve to frontend/src/
  • Tailwind: IntelliSense for class name autocomplete

Start Development

Once everything is installed, start both servers:

make dev

Or start them individually:

make dev-backend
# or: cd backend && uvicorn app.main:app --reload --port 8500

make dev-frontend
# or: cd frontend && npm run dev

Verify the services are running:

Before Every Commit

Run the full check suite to catch issues before CI:

# Backend
cd backend && ruff check app --fix && ruff format app

# Frontend
cd frontend && npm run format && npm run lint && npx tsc --noEmit

make lint-fix
make typecheck
make test

Next Steps