Development Setup

Development Setup

This guide will help you set up your local development environment for contributing to Querri.

Prerequisites

• Docker Desktop (required)
• Git
• Node.js 18+ (for running frontend outside Docker)
• Python 3.11+ (for running backend outside Docker)
• Poetry (for Python dependency management)

Primary Development Workflow

IMPORTANT: Always use Docker for development. The Docker setup includes hot reloading for both frontend and backend services.

First Time Setup

1. Clone the repository

git clone https://github.com/querri/querri-stack.git
cd querri-stack/Querri

2. Get the .env file

Request the .env file from your team lead and place it in the root directory.

3. Set version environment variables

source scripts/set-version-env.sh

4. Build and start the development stack

# First time only - builds all containers
docker compose -f docker-compose.dev.yml up --build

# Subsequent starts
docker compose -f docker-compose.dev.yml up

5. Access the application

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs
• Traefik Dashboard: http://localhost:8080

Daily Development

The Docker stack should remain running. It provides:

• Frontend hot reloading - SvelteKit auto-reloads on file changes
• Backend hot reloading - FastAPI auto-reloads on Python file changes
• Database persistence - MongoDB data persists across restarts
• Complete service mesh - All microservices running together

Stopping the Development Environment

# Press Ctrl+C in terminal, or
docker compose down

Clean Rebuild

Only when explicitly needed:

docker compose -f docker-compose.dev.yml down --volumes
docker compose -f docker-compose.dev.yml up --build

Code Organization

Frontend (/Querri/web-app)

web-app/
├── src/
│   ├── routes/              # SvelteKit pages
│   │   ├── project/         # Project editor
│   │   ├── dashboard/       # Dashboard viewer
│   │   └── settings/        # Settings pages
│   ├── lib/
│   │   ├── components/      # Reusable components
│   │   │   ├── panels/      # Chat, settings panels
│   │   │   ├── ui/          # UI components
│   │   │   └── dataFlow/    # Visual workflow editor
│   │   ├── api/             # API client classes
│   │   ├── stores/          # Svelte stores
│   │   └── utils/           # Utility functions
│   ├── app.css              # Global styles
│   └── app.html             # HTML template
├── static/                  # Static assets
└── package.json

Backend (/Querri/server-api)

server-api/
├── api/
│   ├── routes/              # API endpoints
│   │   ├── projects_routes.py
│   │   ├── steps_routes.py
│   │   ├── chat_routes.py
│   │   └── files_routes.py
│   ├── models/              # Pydantic models
│   ├── services/            # Business logic
│   └── main.py              # FastAPI app
├── querri_core/             # Core data processing
│   ├── steps/               # Step implementations
│   ├── qdf/                 # Querri Data Frame
│   └── connectors/          # Data connectors
├── tests/                   # Test suite
└── pyproject.toml           # Poetry config

Development Patterns

Frontend Development

State Management

Use Svelte stores for shared state:

lib/stores/projects.js

import { writable } from 'svelte/store';

export const projects = writable([]);
export const currentProject = writable(null);

API Integration

Use the API client classes:

import { QProjects } from '$lib/api/projects';

// In your component
const project = await QProjects.get(uuid);
await QProjects.update(uuid, { name: 'New Name' });

Component Lifecycle

<script>
  import { onMount, onDestroy } from 'svelte';

  let data = [];

  onMount(async () => {
    // Load data
    data = await fetchData();
  });

  onDestroy(() => {
    // Cleanup
  });
</script>

Backend Development

Async/Await Pattern

All database operations should be async:

from motor.motor_asyncio import AsyncIOMotorClient

async def get_project(project_id: str):
    db = get_database()
    return await db.projects.find_one({"uuid": project_id})

Dependency Injection

Use FastAPI’s dependency injection:

from fastapi import Depends
from api.deps import get_current_user

@router.get("/projects")
async def list_projects(
    user = Depends(get_current_user)
):
    # user is automatically injected
    return await get_user_projects(user.id)

Error Handling

Use HTTPException for API errors:

from fastapi import HTTPException

if not project:
    raise HTTPException(
        status_code=404,
        detail="Project not found"
    )

Pydantic Models

Define request/response models:

from pydantic import BaseModel

class ProjectCreate(BaseModel):
    name: str
    description: str | None = None

class ProjectResponse(BaseModel):
    uuid: str
    name: str
    owner_id: str

Testing

Frontend Tests

cd web-app

# Unit tests with Vitest
npm run test

# E2E tests with Playwright
npm run test:ui

# E2E against Docker environment
npm run test:docker

Backend Tests

cd server-api

# Run all tests
poetry run pytest

# With coverage
poetry run pytest --cov=api --cov=querri_core

# Specific test file
poetry run pytest tests/test_projects.py

# Type checking
poetry run mypy .

Code Quality

Linting and Formatting

Frontend

cd web-app
npm run lint      # ESLint
npm run format    # Prettier

Backend

cd server-api
poetry run black .           # Format code
poetry run isort .           # Sort imports
poetry run flake8 .          # Linting
poetry run mypy .            # Type checking

Pre-commit Hooks

Install pre-commit hooks to run checks automatically:

# In repository root
pip install pre-commit
pre-commit install

Debugging

Frontend Debugging

Use browser DevTools:

1. Open Chrome/Firefox DevTools
2. Set breakpoints in Sources tab
3. Use console.log() for quick debugging
4. Check Network tab for API calls

Backend Debugging

VS Code

Add to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "FastAPI",
      "type": "python",
      "request": "launch",
      "module": "uvicorn",
      "args": [
        "api.main:app",
        "--reload",
        "--host", "0.0.0.0",
        "--port", "8000"
      ],
      "cwd": "${workspaceFolder}/server-api"
    }
  ]
}

Logging

Use Python logging:

import logging

logger = logging.getLogger(__name__)

logger.info("Processing project", extra={"project_id": uuid})
logger.error("Failed to save", exc_info=True)

Contributing Guidelines

Branch Strategy

• main - Production-ready code
• develop - Integration branch
• feature/* - New features
• bugfix/* - Bug fixes
• hotfix/* - Production hotfixes

Commit Messages

Follow conventional commits:

feat: add dashboard export feature
fix: resolve CORS error on file upload
docs: update installation guide
test: add tests for project sharing
chore: update dependencies

Pull Request Process

1. Create feature branch from develop
2. Make your changes
3. Add tests for new functionality
4. Run linting and tests
5. Create PR against develop
6. Request review from team members
7. Address feedback
8. Merge after approval

Common Issues

Port Already in Use

# Find process using port
lsof -i :5173

# Kill process
kill -9 <PID>

Database Connection Failed

Check MongoDB is running:

docker ps | grep mongo
docker logs querri_mongo_1

Frontend Won’t Build

Clear cache and rebuild:

cd web-app
rm -rf node_modules .svelte-kit
npm install

Backend Import Errors

Reinstall dependencies:

cd server-api
poetry install

Next Steps

• Testing Guide
• Deployment Guide
• Architecture Overview