Core Concepts

Documentation Index

Fetch the complete documentation index at: https://docs.modelcode.ai/llms.txt

Use this file to discover all available pages before exploring further.

Morph structures the modernization process as a series of well-defined stages, guiding teams from initial project setup all the way to delivering production-ready pull requests. This page explains the key terms used throughout each phase of that journey.

​

Table of Contents

• tl;dr
• Core Concepts
• Project
• Repositories and Roles
• Build Environment
• Project Spec
• Milestones
• Tasks
• Rules
• Functional Testing
• Project Knowledge
• Wiki
• Visual Diagrams
• Glossary

​

tl;dr

Morph turns your migration into a step-by-step pipeline:

1. Create a Project (pick your repo(s) and assign roles)
2. Configure the Build Environment (lifecycle commands, env vars, validation)
3. Define your Project Spec (what should change & how)
4. Review and approve the Project Spec
5. Generate a Roadmap of Milestones
6. Execute each Milestone. During execution, Morph dynamically generates Tasks so progress is transparent and each deliverable is verifiable.
7. Once milestone tasks are completed and verified, Morph produces a production-ready PR for that milestone.

Each concept builds on the previous one, so decisions stay traceable from high-level goals down to individual code changes.

​

Core Concepts

​

Project

A Project is the top-level container for a modernization effort. It defines:

• Which repositories are in scope and their roles in the migration
• Which branch strategy to use for generated code (feature branch)
• The operational boundary for the Project Spec, milestones, and rules

In practice, a project is where Morph keeps the full migration context from initial setup to final PR delivery. Some common use cases:

• Modernizing a legacy Flask-based application to FastAPI
• Rewrite C++ CLI using Rust
• Java application version upgrade
• Migrating a backend and its shared library together

​

Repositories and Roles

A project can contain one or more repositories. Each repository has a defined role in the migration: When creating a project, you select repositories and set an origin branch for each. The project also has a shared feature branch (prefixed with morph-) where generated code is committed. The Project Overview — part of the Project Spec flow — captures the full picture: which repos you start with, which repos you end with, and each repo’s modernization role.

​

Build Environment

The Build Environment defines how your project builds, runs, and tests. This is configured during onboarding and is required before Morph can validate and execute migrations. There are two options:

• Cloud — Morph provides a cloud-based build environment for projects with publicly accessible dependencies. Lifecycle configuration is auto-discovered.
• Self-hosted Daemon — A lightweight binary you run on your own infrastructure, necessary when your project depends on private registries, internal APIs, or on-premise services

Each project has a Lifecycle Setup — a configuration containing:

• Scripts — Ordered shell scripts that install dependencies, build, run, health check, and test the application
• Environment variables — Variables your application needs at build or runtime, with optional encryption for secrets
• Lifecycle document — A markdown overview describing the application architecture and how scripts fit together
• Validation — An end-to-end run that executes each script in sequence to confirm everything works

For cloud projects, Morph maintains separate lifecycle configurations for the origin (source) and target (destination) sides of the migration. The origin is discovered during onboarding; the target is discovered automatically during the foundation milestone.

​

Project Spec

The Project Spec is the source-of-truth document for what “done” means. It captures migration requirements before implementation begins. You review and approve it in the Project Knowledge drawer on the Roadmap (under Modernization → Project Knowledge): select Project Spec in the tree and use Knowledge chat. The drawer opens automatically the first time the spec is ready. Typical contents include:

• Target stack
• High-level migration plan
• Key design decisions
• Project overview (repos at start, repos at end, and their roles)
• Testing strategy

The Project Spec must be approved before Morph generates the roadmap. Once approved, it cannot be edited.

​

Milestone

A Milestone is a coherent, reviewable chunk of migration work. Milestones sequence the project into manageable steps with explicit scope, risks, and dependencies.

• Functionally meaningful (not arbitrary file splits)
• Small enough to review safely
• Ordered so each one unlocks the next

Each completed milestone produces a Pull Request for your review.

​

Task

A Task is the smallest executable unit inside a milestone. Tasks translate milestone intent into specific implementation actions. Tasks usually map to one of:

• File/module creation or migration
• Endpoint or data-model implementation
• Test implementation
• Refactor/fix work

​

Rules

Rules are custom instructions that apply across all milestones. They encode your team’s coding standards, library preferences, and patterns so that Morph follows them consistently throughout the migration. Rules can be added, edited, or removed at any point during the migration.

​

Functional Testing

Functional Testing verifies that migrated code behaves identically to the original by comparing real outputs side by side. Morph automatically generates, runs, and validates these tests as part of the milestone lifecycle — no manual test authoring required. Functional testing supports multi-repo projects and covers three types of applications:

• API testing — Compares HTTP responses (status codes, response bodies) between origin and target for each endpoint
• CLI testing — Compares exit codes and stdout/stderr output between origin and target for each command
• UI testing — Captures screenshots and video recordings of the target application’s frontend, with optional side-by-side comparison against the origin

Results are surfaced per-milestone (as a test summary on each milestone card) and in a project-level Functional Testing dashboard with dedicated API/CLI and UI tabs.

​

Project Knowledge

Project Knowledge is the in-app drawer on the Roadmap where structured context lives together: Project Spec, milestones, wikis, and rules, plus Knowledge chat. Agents read this context during work and write updates back (often as new or revised wiki pages). Approving the Project Spec is one important use of this drawer; everything else you can do there — imports, rules, diffs, milestone text — is covered in Project Knowledge. Project Knowledge serves two purposes:

• Agent-to-agent knowledge transfer — When one agent discovers a pattern or makes an architectural decision, it writes that knowledge back. Later agents read it and stay consistent.
• User-to-agent guidance — You can add documentation, coding standards, or design decisions at any time. The content you provide is broken down into structured wiki pages and rules that agents can consume efficiently.

​

Wiki

A Wiki page is a piece of project knowledge stored with your project (shown under Wikis in Project Knowledge). Wikis capture architecture decisions, design patterns, integration notes, and other context that agents reference during execution. Unlike rules, wikis are treated as informational context rather than hard requirements.

​

Visual Diagrams

​

Concept Relationship Diagram

​

Glossary