User Guide

This guide is designed for database administrators, software engineers, and system architects who use the Universal Object Mapping (UOM) Assistant to migrate frameworks to any framework, currently tailored towards database schemas and queries from ASP.NET ORMs (Entity Framework Core, NHibernate, Dapper) to target Java Spring ORM/ODM/OGM (Spring Data MongoDB, Spring Data Neo4j) architectures. Translation is currently one-way (.NET → Java Spring Data); the reverse direction is on the roadmap. See Design Decisions for why.

​

Video preview

This video shows migration from ASP.NET Core to Spring Boot ecosystem specifically translating Database Layer i.e Entity Framework Core 10 to Spring Data MongoDB 5.0. The app is made to be used in an IDE of your choice. The developer experience runs inside specialized isolated sandbox containers created on demand via configurable Dockerfiles (think Codex Cloud Agents, Claude Cloud Agents, Gemini Jules, or self-hosted OpenHands, etc.). The translations are configurable inside the UI, currently tailored towards migrating .NET ORMs to Spring Data ODM (Spring Data MongoDB) and OGM (Spring Data Neo4j) frameworks.

---

​

0. What This Tool Does (in plain terms)

Imagine you have an application written in C#/.NET that talks to a SQL database, and you want to move that data layer to Java with MongoDB or Neo4j. Normally a developer would rewrite every entity class and every query by hand — slow and easy to get subtly wrong. The UOM Assistant does this for you. You paste your .NET schema and/or query code, pick where you want it translated to, and the assistant:

1. Reads your code and figures out the frameworks and versions involved.
2. Looks at your real databases to understand how the data is shaped.
3. Writes the equivalent Java code.
4. Compiles and runs both the original and the translated code against real databases, and checks that they return the same data.
5. Hands you the result — or, if it cannot verify the result after a few tries, asks you to step in instead of giving you something unproven.

---

​

1. Getting Started: The Translation Workspace

When you open the web application at https://uom-demo.vercel.app, you are presented with the main translation workspace.

​

1.1 The Navigation Sidebar

• New Thread: Click the New Thread button at the top of the sidebar to spin up a clean translation session. Each thread represents a separate migration pipeline execution with its own LangGraph checkpoint history.
• Thread List: Lists your active and past migration sessions. You can click on any thread to reload its conversational state and inspect its generated artifacts.
• Thread Actions: Hover over any thread in the list and click the ... menu to Archive, or Delete the session.
• Connect Your IDE: Choose your preferred IDE (VS Code or Cursor) to connect with the specific sandbox environment (.NET, or Java based) and see generated code files, and compilation results in your IDE terminal. Read the README.md inside the sandbox for more instructions.
• Settings: Click the Settings gear to access again Onboarding, configure database connections, LLM configurations and Daytona Sandboxes.
• Theme Toggle: Switch between Light Mode and Dark Mode.

​

1.2 Conversation Thread Suggestion Cards

For new sessions, the chat workspace displays four pre-configured translation suggestion cards. Clicking any card loads the corresponding source code inputs into the composer (the input box at the bottom of the screen) and kickstarts a translation run when you click Send. The four default cards are:

1. EF Core to Spring Data MongoDB: Translates Entity Framework Core 10 schema, queries, and configurations to target Spring Data MongoDB 5.0 document models and MongoTemplate (Criteria/Query) queries.
2. EF Core to Spring Data Neo4j: Translates Entity Framework Core 10 schema, queries, and configurations to Spring Data Neo4j 8.0 nodes and relationship classes with Neo4jTemplate + Cypher-DSL queries.
3. Dapper to Spring Data MongoDB: Translates Dapper SQL schema, queries, and configurations into Spring Data MongoDB document models and MongoTemplate (Criteria/Query) queries.
4. NHibernate to Spring Data MongoDB: Translates NHibernate schema, queries, and configurations (Mapping-by-Code mappings) to target Spring Data MongoDB.

See Design Decisions for the rationale behind these specific framework choices and translation directions.

---

---

​

2. Onboarding & Configuration Panel

Before running your first translation, configure the settings modal (click the Settings gear in the sidebar footer).

​

2.1 Configuration Tabs & Settings Persistence

The settings modal is divided into four tabs:

1. General Tab:
   • Ollama Host: Configure your local Ollama address (defaults to http://localhost:11434).
   • Select Model: Select which LLM will act as the translation generator and evaluator. We recommend the Metacentrum einfra/kimi-k2.6 or einfra/deepseek-v4-pro-thinking for complex schemas.
   • OpenAI API URL & Key: If using remote vLLM clusters (like e-INFRA CZ), supply your API endpoint credentials here.
2. Databases Tab:
   • SQL Server Connection: Connection string for the source relational SQL Server database (defaults to WideWorldImporters).
   • MongoDB Connection: Connection URI for the target MongoDB instance.
   • Neo4j URI & Password: Credentials for the target Neo4j Graph database.
3. Sandboxes Tab:
   • Daytona API URL: The endpoint of the Daytona container orchestration daemon.
   • Daytona API Key: Authorization token to provision containers.
   • Region Target: Binds sandbox containers to your preferred cloud host region (e.g. US or EU).
   • Compilation Timeout: Hard timeout in seconds for compilation commands.
4. Setup & Guides Tab:
   • Links to setup guides and documentation files.

Once saved, the configuration is serialized as a JSON string and persisted in localStorage under the "uom_translator_config" key. It also sets uom_config_onboarded to "true" to prevent the modal from opening automatically on subsequent visits.

---

​

3. Running a Translation Pipeline

To execute a migration, paste your C# source schema and query code in the composer input box and click Send.

​

3.1 Translation Run - Submitting Input

​

3.2 Translation Run - DB Schema Inspection Tool Calls (left) and Schema Inspection Summary (right)

​

3.3 Translation Run - Daytona Sandbox Code Compilation & Validation (left) and DeepDiff Equivalence Evaluation (right)

​

3.5 Translation Run - Completed Run with Final Output

​

3.6 Stepper Nodes & Execution Progress

During execution, a progress banner and/or specific graph prompts (hidden in accordions) is shown at the top/bottom of the current message, which indicates the current active pipeline step:

• Extracting Input: The assistant is parsing your framework types, versions, and code blocks.
• Inspecting Database Schema: The assistant is querying your source SQL Server and target MongoDB/Neo4j DBMS via MCP to gather database metadata.
• Translating Code: The LLM is generating the equivalent target classes and queries.
• Validating Schema / Query: The assistant is spinning up Daytona containers to compile, run your generated C# and Java code harnesses concurrently.
• Evaluating Translation: The assistant is running DeepDiff comparison checks between JSON-serialized entities from relational MS SQL Server outputs and NoSQL (MongoDB, Neo4j) query executions by their respective frameworks: ASP.NET Entity Framework Core and Spring Data MongoDB/Spring Data Neo4j. A translation is only accepted when the data matches; see Why You Can Trust the Translation and Validators & Equivalence.

---

​

4. Troubleshooting & Manual Interventions

When validation compilation fails or the semantic equivalence check identifies differences after 3 attempts, the orchestrator suspends the graph execution.

​

4.1 The Manual Intervention Control Card

When execution is suspended, a warning card titled “Agent Execution Suspended” is displayed in the chat thread, along with the orchestrator’s review instruction. The card contains the following sections:

1. Translation Explanation: The assistant’s natural-language summary of the generated translation (the explanation_message).
2. Query Equivalence DeepDiff: Shows the JSON diff output from the DeepDiff evaluation (e.g. { "values_changed": { "root['orders'][0].price": { "new": 10.5 } } }), when present.
3. Decision Assessment: Provides buttons to either Accept & Save the current output or Reject & Correct with targeted feedback for the assistant to re-run the translation loop with corrections.

The card is restored automatically if you reload the page or reopen the conversation from the thread list, so a suspended migration is never lost.

​

4.2 Actioning Suspended Gates

1. Accepting Output: If you determine the compilation failure is a false positive (e.g. a minor mock mapping mismatch) or want to write the corrections yourself, select Accept & Save and click Submit. The frontend resumes the graph with a decision object:
   { "resume": { "decision": "accept", "feedback": "" } }
   
   The orchestrator will output the final code and exit the loop.
2. Rejecting & Correcting:
   • Select Reject & Correct.
   • A text area labeled Targeted Agent Correction Pointers will appear.
   • Type clear debugging instructions for the assistant (e.g. “Line 24 in order entity has a missing getter” or “Ensure Neo4j query uses relationship DIRECTION of Outgoing”).
   • Click Submit. The frontend resumes the graph with your feedback as a decision object:
     { "resume": { "decision": "reject", "feedback": "The OrderItem class was not generated..." } }
     
     The assistant will ingest your hints, reset the retry counter, and execute a corrected translation loop.

---

​

5. Context and Prompt Engineering for Reliable Translations

The UOM Orchestrator relies heavily on structured context injection and prompt engineering to ensure reliable, compile-error-free translations. You can read more about the dynamic prompt construction strategies in the Prompt Engineering and Context Engineering documents, which detail how LLM prompts are dynamically constructed, selected, and injected with framework configurations and few-shot templates to achieve high translation accuracy between different ORM, ODM, and OGM frameworks.