Skip to content

Development

This page covers how to set up a local development environment and contribute to XTM One.

Prerequisites

  • Python 3.14+
  • Node.js 20+ with Yarn
  • Docker and Docker Compose (for dependencies)
  • Git

Local setup

# Clone the repository
git clone https://github.com/XTM-One-Platform/xtm-one.git && cd xtm-one

# Copy environment file
cp .env.sample .env

# Start dependencies (PostgreSQL + pgvector, Redis, MinIO)
docker compose -f docker-compose.dev.yml up -d

# Run the full stack (backend + worker + frontend)
./dev.sh        # Linux/macOS
.\dev.ps1       # Windows

The dev script installs dependencies, runs migrations, and starts all services with hot reload.

Project structure

xtm-one/
├── backend/           → Python / FastAPI (see backend/AGENTS.md)
├── frontend/          → React 19 / TypeScript (see frontend/AGENTS.md)
├── docs/              → Product documentation (MkDocs)
├── apps/              → Platform app packages
└── docker-compose.yml → Production stack

Running checks

# Backend lint
cd backend && ruff check app/

# Frontend lint and type check
cd frontend && yarn check

# Backend tests
cd backend && SECRET_KEY=test python -m pytest -m "not integration" -q

Migrations

Schema changes must use Alembic migrations. Never use inline SQL.

cd backend
alembic revision --autogenerate -m "description of change"

The platform auto-migrates on startup — no manual alembic upgrade needed in production.

Commit conventions

All commits follow Conventional Commits:

type(scope?): description (#issue)

Types: feat, fix, chore, docs, style, refactor, perf, test, build, ci, revert.

Next step

For product documentation guidelines, see docs/AGENTS.md. For backend and frontend specifics, see backend/AGENTS.md and frontend/AGENTS.md.