Skip to content

Development

This section covers everything you need to contribute to AXIS -- from local setup and coding standards to testing workflows and UI design patterns.

Quick Reference

Start Development Servers

make dev

This starts both servers concurrently:

Lint and Format

make lint          # Check only
make lint-fix      # Auto-fix
make format        # Format only
make typecheck     # Type checking

cd backend
ruff check app --fix
ruff format app
mypy app --ignore-missing-imports

cd frontend
npm run format          # Prettier
npm run lint            # ESLint
npx tsc --noEmit        # TypeScript

Run Tests

make test              # All tests
make test-backend      # pytest
make test-frontend     # Vitest
make test-e2e          # Playwright

Clean Caches

make clean

Removes .ruff_cache, .mypy_cache, .pytest_cache, __pycache__, .next, and node_modules/.cache.

Section Overview

  • Setup

    Environment setup, IDE configuration, pre-commit hooks, and env files.

    Setup guide

  • Code Conventions

    File naming, import order, type hints, router/service patterns, and component structure for both backend and frontend.

    Conventions

  • Adding Features

    Step-by-step walkthroughs for adding routers, services, pages, stores, and environment variables.

    Feature guide

  • Testing

    pytest for the backend, Vitest for unit tests, Playwright for E2E, and Makefile targets.

    Testing guide

  • Design System

    Color palette, component patterns, spacing conventions, and Plotly chart defaults.

    Design system

Monorepo Layout

axis/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI entry, router mounting
│   │   ├── config.py            # Pydantic Settings
│   │   ├── routers/             # API route handlers
│   │   ├── services/            # Business logic
│   │   ├── models/              # Pydantic schemas
│   │   └── copilot/             # AI copilot agent + tools
│   ├── config/                  # YAML config templates (.yaml.example)
│   ├── tests/                   # pytest test suite
│   ├── requirements.txt
│   └── .env                     # Backend environment variables
│
├── frontend/
│   ├── src/
│   │   ├── app/                 # Next.js App Router pages
│   │   ├── components/          # React components (by feature)
│   │   ├── stores/              # Zustand state stores
│   │   ├── lib/                 # API client, hooks, utilities
│   │   └── types/               # TypeScript type definitions
│   ├── e2e/                     # Playwright E2E tests
│   ├── .env.local               # Frontend environment variables
│   └── package.json
│
├── custom/                      # Site-specific config + assets (gitignored)
├── docs/                        # MkDocs documentation (this site)
├── Makefile                     # Monorepo task runner
└── .pre-commit-config.yaml      # Git hook configuration