---
title: "Development"
description: "Complete developer documentation for contributing to, extending, and deploying TraceRTM"
---

# Development Documentation

Welcome to the TraceRTM development documentation. This section provides comprehensive guidance for developers who want to contribute to, extend, or deploy TraceRTM.

## Overview

TraceRTM is an agent-native requirements traceability management system built with modern technologies:

**Backend Stack:**
- **Python 3.12+** with async/await patterns
- **FastAPI** for high-performance REST API
- **SQLAlchemy 2.0** with async PostgreSQL support
- **Typer** for the command-line interface
- **Textual** for the terminal user interface

**Frontend Stack:**
- **React 19** with TypeScript
- **TanStack Router** for type-safe routing
- **TanStack Query** for server state management
- **Tailwind CSS** for styling

**Infrastructure:**
- **PostgreSQL** for relational data storage
- **Neo4j** (optional) for graph-based traceability
- **Redis** for caching and real-time features
- **Docker** for containerization

## Quick Start for Developers

```bash
# Clone the repository
git clone https://github.com/tracertm/tracertm.git
cd tracertm

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

# Install frontend dependencies
cd frontend/apps/web
npm install

# Start development servers
# Terminal 1: Backend API
uvicorn tracertm.api.main:app --reload

# Terminal 2: Frontend
npm run dev

# Terminal 3: TUI (optional)
rtm tui
```

## Documentation Sections

### [Architecture](/docs/development/architecture)

Deep dive into TraceRTM's system design:

- **System Overview** - High-level architecture and design principles
- **Frontend Architecture** - React components, state management, routing
- **Backend Architecture** - API design, services, repositories
- **Database Schema** - PostgreSQL and Neo4j schemas
- **Infrastructure** - Deployment topology, scaling considerations
- **Security** - Authentication, authorization, data protection

### [Setup](/docs/development/setup)

Get your development environment running:

- **Prerequisites** - Required tools and system requirements
- **Local Development** - Platform-specific setup guides
- **Docker Setup** - Container-based development environment
- **Database Setup** - PostgreSQL and Neo4j configuration
- **Environment Variables** - Configuration reference
- **IDE Setup** - Recommended editor configurations

### [Contributing](/docs/development/contributing)

Guidelines for contributing to TraceRTM:

- **Code Style** - Python and TypeScript style guides
- **Commit Messages** - Conventional commits specification
- **Pull Requests** - PR process and review guidelines
- **Testing** - Unit, integration, and E2E testing
- **Documentation** - Writing and maintaining docs
- **Releases** - Versioning and release process

### [Internals](/docs/development/internals)

How TraceRTM works under the hood:

- **Data Flow** - Request lifecycle and data processing
- **State Management** - Frontend and backend state patterns
- **Caching** - Redis caching strategies
- **Queue System** - Background job processing
- **Search Engine** - Full-text and semantic search
- **Services** - Core business logic implementation

### [Deployment](/docs/development/deployment)

Deploy TraceRTM to production:

- **Docker Deployment** - Container builds and orchestration
- **Kubernetes** - K8s manifests and Helm charts
- **Cloud Platforms** - AWS, GCP, Azure deployment guides
- **Monitoring** - Prometheus, Grafana setup
- **Logging** - Centralized logging with ELK stack
- **Scaling** - Horizontal scaling strategies

## Development Workflow

### Standard Workflow

```bash
# 1. Create feature branch
git checkout -b feature/your-feature

# 2. Make changes and run quality checks
poe quality  # Format, lint, type check

# 3. Run tests
poe test

# 4. Commit with conventional commits
git commit -m "feat(scope): add new feature"

# 5. Push and create PR
git push origin feature/your-feature
```

### Quality Pipeline

```bash
# Run all quality checks
poe all

# Individual checks
poe format          # Format code with ruff
poe lint            # Lint code with ruff
poe type-check      # Type check with mypy
poe test            # Run tests with pytest
poe test-cov        # Tests with coverage report
```

### Development Commands

**Python/Backend:**
```bash
rtm --help                    # CLI help
uvicorn tracertm.api.main:app --reload  # Dev server
pytest tests/                 # Run tests
alembic upgrade head          # Run migrations
```

**Frontend:**
```bash
npm run dev                   # Development server
npm run build                 # Production build
npm run test                  # Run tests
npm run lint                  # Lint code
```

**Docker:**
```bash
docker compose up -d          # Start all services
docker compose logs -f api    # View API logs
docker compose down           # Stop services
```

## Architecture Diagram

```
┌────────────────────────────────────────────────────────────────┐
│                        Client Layer                             │
├────────────────────────────────────────────────────────────────┤
│  Web UI (React)  │  CLI (Typer)  │  TUI (Textual)  │  SDK      │
└────────┬─────────┴───────┬───────┴────────┬────────┴─────┬─────┘
         │                 │                 │              │
         ▼                 ▼                 ▼              ▼
┌────────────────────────────────────────────────────────────────┐
│                      API Gateway (FastAPI)                      │
├────────────────────────────────────────────────────────────────┤
│  REST Endpoints  │  WebSocket  │  Auth Middleware  │  CORS     │
└────────┬─────────┴──────┬──────┴─────────┬────────┴─────┬─────┘
         │                │                 │              │
         ▼                ▼                 ▼              ▼
┌────────────────────────────────────────────────────────────────┐
│                      Service Layer                              │
├────────────────────────────────────────────────────────────────┤
│  Project  │  Item  │  Link  │  Sync  │  Graph  │  Search       │
│  Service  │ Service│ Service│ Service│ Service │  Service      │
└────────┬──┴────┬───┴────┬───┴────┬───┴────┬────┴──────┬───────┘
         │       │        │        │        │           │
         ▼       ▼        ▼        ▼        ▼           ▼
┌────────────────────────────────────────────────────────────────┐
│                    Repository Layer                             │
├────────────────────────────────────────────────────────────────┤
│  ProjectRepo  │  ItemRepo  │  LinkRepo  │  AgentRepo  │  ...   │
└───────┬───────┴──────┬─────┴──────┬─────┴──────┬──────┴────────┘
        │              │            │            │
        ▼              ▼            ▼            ▼
┌───────────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐
│  PostgreSQL   │ │  Neo4j   │ │  Redis  │ │  Storage │
│  (Primary)    │ │  (Graph) │ │ (Cache) │ │  (Files) │
└───────────────┘ └──────────┘ └─────────┘ └──────────┘
```

## Key Design Principles

### 1. Agent-Native Architecture

TraceRTM is designed for AI agent collaboration:

- **Optimistic locking** prevents concurrent modification conflicts
- **Event sourcing** maintains complete change history
- **Distributed locking** coordinates multi-agent operations
- **Conflict resolution** handles merge scenarios

### 2. Layered Architecture

Clean separation of concerns:

- **API Layer** - HTTP handling, validation, serialization
- **Service Layer** - Business logic, orchestration
- **Repository Layer** - Data access, query building
- **Model Layer** - Domain models, validation rules

### 3. Async-First

Non-blocking operations throughout:

```python
# All database operations are async
async def get_project(project_id: str) -> Project:
    async with get_session() as session:
        return await project_repo.get(session, project_id)
```

### 4. Type Safety

Full type coverage with runtime validation:

```python
# Pydantic models for API schemas
class ItemCreate(BaseModel):
    title: str = Field(..., min_length=1, max_length=500)
    item_type: ItemType
    description: str | None = None

# SQLAlchemy models for database
class Item(Base):
    __tablename__ = "items"
    id: Mapped[str] = mapped_column(primary_key=True)
    title: Mapped[str] = mapped_column(String(500))
```

## Getting Help

- **Issues**: [GitHub Issues](https://github.com/tracertm/tracertm/issues)
- **Discussions**: [GitHub Discussions](https://github.com/tracertm/tracertm/discussions)
- **Discord**: [TraceRTM Community](https://discord.gg/tracertm)

## Related Resources

- [API Reference](/api) - Complete API documentation
- [User Guides](/docs/wiki/guides) - Usage guides and tutorials
- [Changelog](/docs/changelog) - Version history and release notes

