Getting Started

This guide takes you from a clean machine to a running UOM stack — databases, MCP adapters, sandboxes, the LangGraph orchestrator, and the Next.js frontend. For what the system does and why it is built this way, see the Introduction and Design Decisions.

UOM is a monorepo. The commands below assume you are at the repository root unless a cd is shown. Source: github.com/corovcam/Universal-Object-Mapping.

1. Development Requirements

Your host environment must satisfy the following:

Requirement	Version / Notes
Docker	Docker Engine 25+ with Docker Compose V2 (runs the relational/NoSQL backends, MCP adapters, and Next.js).
Python	3.11+ (3.13 recommended; 3.14+ currently causes issues), managed via uv.
Node.js	v24, managed with pnpm workspaces (Next.js App Router).
OS	Linux or WSL recommended for optimal Docker performance and Daytona sandbox compatibility.
Daytona	A local Daytona server daemon to manage isolated SDK sandbox containers.
LLM provider	An OpenAI-compatible endpoint — Metacentrum e-INFRA CZ vLLM (e.g. Kimi K2.6, GLM-5, DeepSeek V4 Pro), any comparable OpenAI-compatible API, or a local Ollama instance (e.g. `qwen3-coder-next`).

2. Quick Start

Step 1 — Configure environment variables

Copy the env templates at the workspace root, in frontend/uom-translator-ui, and in services/orchestrator, then fill in your LLM provider keys and base URLs:

cp .env.example .env.dev          # development
cp .env.example .env              # production
cp .env.example .env.development  # frontend (development)
cp .env.example .env.production   # frontend (production)

Step 2 — Spin up the container stack

Boot the databases, MCP adapters, relational migrator, Daytona stack, and orchestrator backend:

./scripts/init-project.sh

Ensure all healthchecks pass. To reset, run ./scripts/destroy-containers.sh, fix the issue, and retry.

Step 3 — Configure the databases (ETL)

To validate query translations against real data, the target MongoDB and Neo4j databases must hold a logically equivalent copy of the relational source. This is a one-time, semi-automatic ETL step.

MongoDB
Neo4j

Open the MongoDB Relational Migrator dashboard at http://localhost:8091, connect to the SQL Server source, and map the WideWorldImporters dataset into MongoDB. A pre-configured mapping lives in services/etl/mongodb/UOM WideWorldImporters.relmig (import it in the UI). Or run the script:

./services/etl/mongodb/run_mongodb_etl.sh

Use the Neo4j ETL Tool (UI available only in Neo4j Desktop v1.6 and older) or the Neo4j ETL CLI to map relational tables to graph nodes and foreign keys to relationships:

./services/etl/neo4j/run-neo4j-etl.sh

Step 4 — Create a Daytona API key

So the orchestrator can provision sandboxes:

Open the Daytona dashboard at http://localhost:3000. Authenticate with the defaults: user dev@daytona.io, password password.
Go to API Keys → Create Key. Name it default, set Permissions to Full Access.
Copy the key into DAYTONA_API_KEY in both .env.dev and .env under services/orchestrator.
Rebuild the orchestrator service.

See the Daytona API Keys docs for details.

Step 5 — Start the LangGraph server

In a separate terminal:

cd services/orchestrator
direnv allow   # if you use direnv; otherwise load env vars manually
uv sync --all-extras && ./scripts/load_env.sh && ./scripts/init_daytona_snapshots.sh   # or `make dev`
langgraph dev --allow-blocking   # or `make dev`

The server listens on http://localhost:2024 and opens the LangGraph/LangSmith Agent Studio dashboard automatically.

For development, enable LLM request mocking to avoid rate limits and speed up iteration:

make record_requests

This records LLM requests/responses to a local fixtures directory; point your .env.dev endpoint accordingly. See Observability for tracing setup.

Step 6 — Launch the Next.js frontend

In a third terminal:

cd frontend/uom-translator-ui
pnpm install
pnpm dev:frontend

Open http://localhost:3001 (port 3001 because the Daytona API already occupies 3000) and start translating. New to the UI? Follow the User Guide.

3. Production Deployment

Configure all production env files (domains, IPs, networking) and run:

./scripts/init-project-prod.sh

For the full production topology — Docker Compose profiles, environment configuration, sandbox timeouts, and init/destroy scripts — see DevOps & Deployment.

4. Where to Go Next

User Guide

Run your first translation in the web UI.

Architecture

Understand the LangGraph state machine.

Contribution Guide

Add a new framework or extend the backend.

Observability

Wire up LangSmith, Logfire, and OpenTelemetry tracing.

Introduction

User Docs

Developer Docs

1. Development Requirements

2. Quick Start

Step 1 — Configure environment variables

Step 2 — Spin up the container stack

Step 3 — Configure the databases (ETL)

Step 4 — Create a Daytona API key

Step 5 — Start the LangGraph server

Step 6 — Launch the Next.js frontend

3. Production Deployment

4. Where to Go Next

User Guide

Architecture

Contribution Guide

Observability

​1. Development Requirements

​2. Quick Start

​Step 1 — Configure environment variables

​Step 2 — Spin up the container stack

​Step 3 — Configure the databases (ETL)

​Step 4 — Create a Daytona API key

​Step 5 — Start the LangGraph server

​Step 6 — Launch the Next.js frontend

​3. Production Deployment

​4. Where to Go Next

User Guide

Architecture

Contribution Guide

Observability

1. Development Requirements

2. Quick Start

Step 1 — Configure environment variables

Step 2 — Spin up the container stack

Step 3 — Configure the databases (ETL)

Step 4 — Create a Daytona API key

Step 5 — Start the LangGraph server

Step 6 — Launch the Next.js frontend

3. Production Deployment

4. Where to Go Next