Architect a Cloud Migration with TOGAF

Run a mini TOGAF ADM cycle to plan a cloud migration for a small retailer.

Introduction

30 Second Summary

Every business that moves to the cloud needs an architect with a plan, not just someone who clicks buttons in a console.

In this project, you will run a compressed TOGAF ADM cycle to plan a cloud migration for a fictional small retailer, producing the same professional deliverables a real enterprise architect creates.

What You'll Build

You are the enterprise architect for GreenLeaf Groceries, a small retailer running on aging on-premise servers, and you will produce a complete set of TOGAF ADM artifacts covering the Preliminary Phase through Phase D.

By the end of this project, you'll have:

A portfolio-ready GitHub repository containing Architecture Principles, a Stakeholder Map, an Architecture Vision, a Gap Analysis, and Architecture Decision Records.
Baseline and target ArchiMate models built in Archi that show the current-state business layer and the future-state technology layer.
A navigable Obsidian vault with linked Mermaid C4 diagrams, ADRs, and architecture documents you can reuse as templates for real projects.
A Phase E Opportunities & Solutions roadmap with prioritized work packages and a Gantt timeline, if you take on the Secret Mission.

Are there any prerequisites?

You should have a basic understanding of enterprise architecture concepts and some familiarity with TOGAF terminology. You also need a ChatGPT Plus subscription ($20/month) to authenticate with Codex CLI. Comfort with Markdown files is helpful but not required.

Set Up Your EA Workbench

Before you can run an ADM cycle, you need a workbench. Enterprise architects rely on a combination of modeling tools, documentation tools, and version control to produce and track their deliverables.

In this step, you will install and configure five tools that work together: Cursor IDE for editing Markdown files, Codex CLI for AI-assisted drafting, Obsidian for navigating your architecture knowledge base, Archi for ArchiMate modeling, and Git for version control.

In This Step, Get Ready To:

Install and configure Cursor IDE, Codex CLI, Obsidian, Archi, and Git.
Create a structured project folder and open it as an Obsidian vault.
Install the Modern Mermaid plugin for rendering C4 diagrams in Obsidian.

Install and Configure Your Tools

This project uses five tools that each handle a different part of the EA workflow. You need all five installed before moving on.

Download and install Cursor IDE from cursor.com.
Download and install Obsidian from obsidian.md.
Download and install Archi 5.8.0 from archimatetool.com/download.

What is Archi?

Archi is the most widely used free ArchiMate modeling tool. It supports the full ArchiMate 3.2 specification, runs on Windows, macOS, and Linux, and enforces correct ArchiMate relationship rules through its "magic connector" feature. This means it will guide you toward valid models as you build them.

Now install Codex CLI. This requires Node.js to be installed on your machine already.

Open your terminal and run the following command to install Codex CLI globally.

npm i -g @openai/codex

Run codex in your terminal and sign in with your ChatGPT account when prompted.

codex

What is Codex CLI?

Codex CLI is an open-source terminal tool from OpenAI that lets you prompt an AI agent to read, edit, and run files in your project directory. You will use it throughout this project to scaffold Markdown documents and Mermaid diagrams. It requires a ChatGPT Plus, Pro, Business, Edu, or Enterprise plan to authenticate.

Finally, verify that Git is installed.

Run the following command in your terminal.

git --version

I see a version number

You are good to go. Git is installed and ready.

Command not found

Git is not installed on your machine. Download it from git-scm.com and install it. Then run git --version again to confirm.

Still Having Trouble?

Ask for help installing Git on your operating system.

Pro tip: Windows users

Codex CLI fully supports macOS and Linux. On Windows, it is experimental and requires WSL2. If you are on Windows, run all terminal commands inside a WSL2 Ubuntu session.

Create Your Project Folder and Obsidian Vault

Your project folder will double as both a Git repository and an Obsidian vault. Every Markdown file you create lives in this single folder, which means your architecture documents, diagrams, and decision records are all version-controlled and cross-linked in one place.

Open your terminal and create the project folder.

mkdir greenleaf-ea
cd greenleaf-ea

Create the subfolder structure that maps to your TOGAF ADM phases.

mkdir 00-preliminary 01-phase-a-vision 02-phase-b-business 03-phase-d-technology decisions

Why This Folder Structure?

Each folder corresponds to a phase of the TOGAF ADM cycle you will run. The numbered prefixes keep them in order. The decisions/ folder follows the MADR convention for storing Architecture Decision Records.

Initialize a Git repository inside the folder.

git init

Create a .gitignore file to exclude Obsidian workspace files from version control.

echo ".obsidian/workspace.json" >> .gitignore
echo ".obsidian/workspaces.json" >> .gitignore

Why Exclude These Files?

Obsidian stores your window layout and open tabs in workspace.json. These files change constantly as you navigate and are specific to your machine. Excluding them keeps your Git history clean and focused on actual architecture content.

Open Obsidian.
Select Open folder as vault.
Navigate to and select your greenleaf-ea folder.

You should see your five subfolders appear in the Obsidian file explorer on the left side.

Install the Modern Mermaid Plugin in Obsidian

Obsidian has built-in Mermaid rendering, but it ships with an older version. The Modern Mermaid community plugin auto-fetches the latest Mermaid version and adds pan, zoom, and PNG export. You will need these features when you create your C4 System Context diagram later.

Open Settings in Obsidian.
Select Community plugins in the left sidebar.
Click Browse.
Search for Modern Mermaid.
Click Install, then click Enable.

Why Modern Mermaid Instead of the Built-In Renderer?

Obsidian's built-in Mermaid renderer uses version 11.4.1. The Modern Mermaid plugin automatically fetches the latest Mermaid release, which means you get the newest C4 diagram syntax support. It also adds pan and zoom controls for large diagrams and lets you export diagrams as PNG images.

To verify the plugin is working, create a quick test file.

Create a new file in Obsidian called test-mermaid.md in the root of your vault.
Paste the following Mermaid diagram into the file.

```mermaid
graph LR
    A[Store Manager] --> B[POS System]
    B --> C[Inventory]
```

Switch to Reading view in Obsidian to see the rendered diagram.

You should see a simple flowchart with three connected boxes. If the diagram renders, your plugin is working correctly. You can delete this test file afterward.

Make your first commit to save your project setup.

git add .
git commit -m "Initial project setup: folder structure and gitignore"

What Does This Command Do?

The git add . command stages all new and changed files. The git commit -m command saves a snapshot of your project with a descriptive message. You will commit at the end of every step to build a clean version history of your architecture work.

Your workbench is ready. You have a structured project folder, a version-controlled Obsidian vault, and all the tools you need to model, document, and track your architecture decisions. Next up, you will define the Architecture Principles that will govern every decision in your ADM cycle.

Define Architecture Principles

Before you can plan where GreenLeaf Groceries is going, you need guardrails that keep every future decision aligned with the business.

In the TOGAF ADM, the Preliminary Phase is where you define Architecture Principles. These principles act as decision filters for every phase that follows.

You will also create your first Architecture Decision Record (ADR) to document why you chose the TOGAF ADM approach in the first place. Then you will link everything together in Obsidian so your vault starts becoming a navigable knowledge web.

In This Step, Get Ready To:

Draft five architecture principles using Codex CLI.
Create your first ADR using the MADR template.
Link your documents together in Obsidian and commit to Git.

Draft Your Architecture Principles Document

Architecture principles are high-level statements that guide technology and design choices across the entire project. Each principle has four parts: a Name, a Statement, a Rationale explaining why it matters, and Implications describing what the principle means in practice.

Open Cursor and create a new file at 00-preliminary/architecture-principles.md.
Open your terminal, navigate to your greenleaf-ea project folder, and run codex to start a Codex CLI session.
Enter the following prompt to generate your principles.

Write 5 architecture principles for a small grocery retailer migrating from on-premise servers to the cloud. Each principle should have a Name, Statement, Rationale, and Implications section. Use plain English.

Review the output that Codex generates.
Refine any principles that feel too generic. Good principles should be specific enough to GreenLeaf's situation that they could actually resolve a debate during the migration.
Copy the final version into your architecture-principles.md file and save it.

What is an Architecture Principle?

Think of principles as the constitution for your architecture. When two teams disagree on an approach, you point to the principles to settle it. For example, a principle like "Cloud First" means that any new service must be deployed to the cloud unless there is a documented exception.

Pro tip: make principles debatable

A good architecture principle is one that a reasonable person could disagree with. "Security is important" is not a useful principle because nobody would argue against it. "Prefer managed services over self-hosted infrastructure" is useful because it takes a clear position that has real trade-offs.

Create Your First ADR

An Architecture Decision Record captures the context, options, and reasoning behind a significant architecture decision. Your first ADR documents the most fundamental decision of this project: why you chose the TOGAF ADM as your framework.

You will use the MADR (Markdown Any Decision Records) template, version 4.0.0. MADR is dual-licensed under MIT and CC0, and its convention is to store decision files in a decisions/ folder as numbered Markdown files.

Create a new file at decisions/0001-use-togaf-adm-for-migration.md.
Paste the following MADR template and fill in each section.

# Use TOGAF ADM for Cloud Migration Planning

## Status

Accepted

## Context and Problem Statement

GreenLeaf Groceries needs a structured approach to plan their migration from on-premise servers to the cloud. Without a framework, the migration risks scope creep, missed stakeholder concerns, and inconsistent decision-making.

## Decision Drivers

- Industry-standard framework with broad adoption
- Repeatable process that produces consistent deliverables
- Strong stakeholder engagement and governance structure

## Considered Options

1. TOGAF ADM
2. Ad-hoc planning (no formal framework)
3. D3 lightweight framework

## Decision Outcome

Chosen option: TOGAF ADM, because it provides the most comprehensive stakeholder engagement and governance structure for this scale of change.

### Consequences

- Good: Produces well-defined deliverables at each phase.
- Good: Stakeholder concerns are systematically captured.
- Bad: Heavier process overhead than lightweight alternatives.
- Neutral: Requires familiarity with TOGAF terminology.

What does this template do?

The MADR template captures the full decision lifecycle. The Context section explains the problem. Decision Drivers list the criteria you used to evaluate options. Considered Options shows you explored alternatives. Decision Outcome records what you chose and why. This structure means future architects can understand your reasoning without having to ask you.

Review the template and adjust any wording to match your own understanding of the decision.
Save the file.

Link Your Documents in Obsidian and Commit

One of Obsidian's most powerful features is bidirectional wiki-links. When you link one document to another, Obsidian's graph view shows the connection in both directions. This turns your flat folder of Markdown files into a navigable knowledge web.

Open your architecture-principles.md file in Cursor.
Add the following line at the bottom of the file to create a wiki-link to your ADR.

## Related Decisions

- [[0001-use-togaf-adm-for-migration]]

What does this link do?

The [[filename]] syntax is Obsidian's wiki-link format. It creates a clickable link to the target file. Obsidian also creates a backlink on the target file, so your ADR will show that the principles document references it. As your vault grows, these links form a graph that mirrors the relationships between your TOGAF deliverables.

Save the file.
Switch to Obsidian and open both files to verify they render correctly.
Click the wiki-link in the principles document to confirm it navigates to the ADR.
Open the graph view in Obsidian by pressing Cmd+G (macOS) or Ctrl+G (Windows) to see the link between your two documents.
Open your terminal and commit your work.

git add .
git commit -m "Preliminary: architecture principles and first ADR"

Your Preliminary Phase is complete. You have a set of principles that will guide every decision in the migration, and an ADR that documents why you are using the TOGAF ADM in the first place. Next up, you will build the Architecture Vision and map the stakeholders who care about this migration.

Build the Architecture Vision

Your architecture principles are in place. Now it is time to answer the most important question any migration project faces: who cares, and what does the future look like?

Phase A of the TOGAF ADM is where you build the Architecture Vision. This phase produces two key deliverables: a Stakeholder Map that identifies everyone affected by the migration, and a vision statement that paints a clear picture of where GreenLeaf Groceries is headed.

In This Step, Get Ready To:

Create a Stakeholder Map identifying key players, their concerns, and their classification.
Write an Architecture Vision statement connecting business goals to a target architecture.
Link all Phase A documents together in your Obsidian vault.

Create a Stakeholder Map

A cloud migration touches every part of a business. The CEO cares about cost savings. The store manager cares about whether the POS system will go down during the switch. The finance director wants to know how the budget changes. A Stakeholder Map captures all of these people, their concerns, and how much influence they have over the project.

Create a new file at 01-phase-a-vision/stakeholder-map.md in Cursor.
Open your terminal, navigate to your greenleaf-ea project folder, and run codex.
Enter the following prompt to draft your stakeholder map.

codex "Create a TOGAF stakeholder map for a small grocery retailer cloud migration project. Include stakeholder name, role, key concerns, and classification (Key Player, Keep Satisfied, Keep Informed, Minimal Effort). Include at least 5 stakeholders: CEO, Store Manager, IT Manager, Finance Director, and Customers. Format it as a Markdown table. Save it to 01-phase-a-vision/stakeholder-map.md"

What Is a Stakeholder Classification?

TOGAF uses a power/interest grid to classify stakeholders into four categories. Key Players have high power and high interest (like the CEO). Keep Satisfied stakeholders have high power but low day-to-day interest (like the Finance Director). Keep Informed stakeholders have low power but high interest (like Store Managers). Minimal Effort stakeholders have low power and low interest (like end customers).

Review the generated output in Codex CLI and refine it to match GreenLeaf's scenario.
Add a wiki-link back to your principles document at the bottom of the file.

## Related Documents

- [[architecture-principles]]

What Does This Link Do?

The [[architecture-principles]] syntax is an Obsidian wiki-link. It creates a clickable connection between your stakeholder map and your principles document. Over the course of this project, these links build a navigable knowledge web that mirrors how real architecture documents reference each other.

Write the Architecture Vision Statement

The Architecture Vision is the single most important document in Phase A. It tells every stakeholder what the future looks like and why it is worth pursuing. Without it, the migration is just a technical exercise with no business anchor.

Create a new file at 01-phase-a-vision/architecture-vision.md in Cursor.
Use Codex CLI to draft the vision document with the following prompt.

codex "Write a TOGAF Architecture Vision document for GreenLeaf Groceries cloud migration. Include these sections:
1. Problem Statement: GreenLeaf runs on aging on-premise servers that are expensive to maintain, unreliable, and cannot scale for online ordering.
2. Business Goals: Reduce IT costs by 30%, enable online ordering within 6 months, improve system uptime to 99.9%.
3. Scope: Technology and business architecture for core retail operations.
4. Vision Statement: A high-level description of the target state where GreenLeaf runs on managed cloud services with an integrated online ordering channel.
Format as Markdown. Save to 01-phase-a-vision/architecture-vision.md"

Pro tip: refine the AI output

Codex CLI gives you a solid starting point, but the real learning happens when you refine it. Read through each section and ask yourself: does this accurately describe GreenLeaf's situation? Would a CEO find this compelling? Adjust the language to feel like something you would present to a real stakeholder.

Review the generated document and refine the language to be clear and business-focused.
Verify that all four sections (Problem Statement, Business Goals, Scope, Vision Statement) are present.

Link, Verify, and Commit

Your Phase A documents need to reference each other and connect back to the Preliminary Phase. This cross-linking is what turns a collection of files into a proper architecture knowledge base.

Add a Related Documents section at the bottom of architecture-vision.md with links to the stakeholder map, principles document, and first ADR.

## Related Documents

- [[stakeholder-map]]
- [[architecture-principles]]
- [[0001-use-togaf-adm-for-migration]]

Open Obsidian and switch to the Graph View by clicking the graph icon in the left sidebar.
Verify that you can see nodes for your principles, stakeholder map, vision, and ADR documents, all connected by the wiki-links you added.

What Should I See?

Your graph view should show at least four nodes connected by lines. The architecture-vision node should have the most connections since it links to the stakeholder map, principles, and the first ADR. This visual web is exactly how professional architects navigate large architecture repositories.

Commit your Phase A work.

git add .
git commit -m "Phase A: stakeholder map and architecture vision"

What Does This Command Do?

This stages all new and modified files in your project folder, then creates a Git commit with a descriptive message. Each commit captures a snapshot of your architecture repository at a specific phase of the ADM cycle.

You now have a complete Phase A package: a stakeholder map that identifies who matters and an architecture vision that describes where GreenLeaf is going. Next up, you will model the current state of the business in ArchiMate to establish the baseline that your migration will transform.

Model the Baseline Business Architecture

Before you can plan where GreenLeaf Groceries is going, you need a clear picture of where it is today. Phase B of the TOGAF ADM focuses on modeling the current-state business architecture. In this step, you will build a baseline ArchiMate model in Archi that captures how GreenLeaf operates right now, then document that current state in a narrative your stakeholders can read.

In This Step, Get Ready To:

Create a baseline business layer model with actors, processes, and services in Archi.
Arrange those elements into a readable baseline view.
Write a baseline narrative document that describes GreenLeaf's current operations.

Create a Baseline Business Layer Model in Archi

The ArchiMate Business Layer captures who does what in an organization and what services those activities produce. You will use three core element types: Business Actors (the people and organizations that perform work), Business Processes (the sequences of behavior they carry out), and Business Services (the capabilities those processes expose to the outside world).

Open Archi and select File, then New, then Empty Model.
In the Models tree on the left, right-click the model name and select Rename.
Name the model GreenLeaf Groceries - Baseline.

Now add the Business Actor elements. These represent the people and organizations involved in GreenLeaf's day-to-day operations.

In the Models tree, expand Business.
Right-click Business and select New, then Business Actor.
Create five Business Actors with these names: Store Manager, Cashier, Stock Clerk, Supplier, and Customer.

Next, add the Business Process elements. These represent the key activities GreenLeaf performs.

Right-click Business again and select New, then Business Process.
Create four Business Processes: Process Sale, Manage Inventory, Order from Supplier, and Manage Staff Schedule.

Finally, add the Business Service elements. These are the capabilities that GreenLeaf's processes expose.

Create two Business Services: Point of Sale Service and Inventory Tracking Service.

Now connect the elements using ArchiMate relationships. Archi's "magic connector" helps you pick valid relationship types.

Use Assignment relationships to connect actors to the processes they perform. For example, assign Cashier to Process Sale, and assign Stock Clerk to Manage Inventory.
Use Realization relationships to connect processes to the services they produce. For example, Process Sale realizes Point of Sale Service.
Use Serving relationships to show which services are consumed by external actors. For example, Point of Sale Service serves Customer.

What Are Assignment, Realization, and Serving?

These are three of the most common ArchiMate relationship types. Assignment links an active element (like an actor) to the behavior it performs. Realization links behavior to the service it produces. Serving shows that a service is used by another element.

Together they form a chain: Actor is assigned to Process, Process realizes Service, Service serves Consumer. This chain is the backbone of every ArchiMate business layer model.

Create a Baseline View

Elements and relationships live in the model tree, but a view is how you arrange them visually on a canvas. Think of it as a diagram that tells a story about a specific part of the model.

In the Models tree, right-click Views and select New, then ArchiMate View.
Name the view Baseline Business Architecture.
Drag your Business Actor elements from the tree onto the top of the canvas.
Drag your Business Process elements into the middle row.
Drag your Business Service elements to the bottom row.

When you drag elements that already have relationships defined in the model tree, Archi automatically draws the connection lines on the canvas. You should see assignment arrows from actors down to processes, realization arrows from processes down to services, and serving arrows from services to consuming actors.

Arrange the elements so the diagram reads top-to-bottom: actors at the top, processes in the middle, services at the bottom.
Save the model by selecting File, then Save As.
Save the file as greenleaf-baseline.archimate inside your greenleaf-ea project folder.

Pro tip: use Archi's magic connector

If you need to add a relationship directly on the canvas, select the Magic Connector tool from the palette (the wand icon). Click a source element, then click a target element. Archi shows you only the relationship types that are valid between those two element types according to the ArchiMate specification. This prevents you from creating invalid models.

Document the Baseline Narrative

An ArchiMate model captures structure, but stakeholders also need a written description they can read without opening a modeling tool. The baseline narrative tells the story of how GreenLeaf operates today in plain language.

Open Cursor and create a new file at 02-phase-b-business/baseline-narrative.md.

Write 3-4 paragraphs describing GreenLeaf's current state. Cover these key points:

GreenLeaf operates 3 stores, each with standalone POS systems that do not share data.
Inventory tracking is done manually via spreadsheets.
Supplier ordering happens over the phone with no digital integration.
There is no online sales channel.

You can use Codex CLI to help draft the narrative. Navigate to your project folder in the terminal, run codex, and prompt it with something like:

codex

Once inside the Codex CLI session, enter this prompt:

Write a 3-4 paragraph baseline narrative for GreenLeaf Groceries, a small retailer with 3 stores. They use standalone POS systems per store, manual spreadsheet inventory tracking, phone-based supplier ordering, and have no online sales channel. Write in third person, professional tone, suitable for an architecture document.

Why Write a Narrative When You Have a Model?

Models are precise but require training to read. Narratives are accessible to every stakeholder, from the CEO to the store manager. In a real TOGAF engagement, you would include both in your Architecture Definition Document so that technical and non-technical audiences can understand the current state.

Review the Codex output and refine it to match the details above.
Save the file.
Add wiki-links to your principles and vision documents at the bottom of the narrative. For example:

## Related Documents

- [[architecture-principles]]
- [[architecture-vision]]

What does this code do?

The double-bracket syntax [[filename]] creates a wiki-link in Obsidian. When you click it, Obsidian navigates directly to that file. These links also appear in Obsidian's graph view, giving you a visual map of how all your architecture documents connect.

Now commit your progress.

Open your terminal and navigate to the greenleaf-ea folder.
Run the following commands to stage and commit your changes.

git add .
git commit -m "Phase B: baseline business architecture model and narrative"

What should I see?

Your commit should include at least two new files: greenleaf-baseline.archimate and 02-phase-b-business/baseline-narrative.md. If you open Obsidian's graph view, you should now see the baseline narrative linked to both the architecture principles and the architecture vision documents.

Archi Not Saving to Your Project Folder?

Archi defaults to its own workspace directory. Make sure you use File then Save As and explicitly navigate to your greenleaf-ea folder. If you already saved it elsewhere, use Save As again to move it. Help me troubleshoot my Archi file location.

You now have a complete picture of how GreenLeaf operates today. Next up, you will model where GreenLeaf needs to go by building the target technology architecture and analyzing the gaps between baseline and target.

Model the Target Technology Architecture and Analyze Gaps

You have a clear picture of how GreenLeaf operates today. Now it is time to design where the business is headed. In TOGAF Phase D, you define the target Technology Architecture and then compare it against the baseline to find every gap that needs closing.

In This Step, Get Ready To:

Build a target Technology Layer model in Archi showing the cloud-based future state.
Write a gap analysis comparing the baseline to the target architecture.
Create a Mermaid C4 System Context diagram and a second ADR.

Create a Target Technology Layer Model in Archi

The baseline model you built in Phase B shows the business layer. Phase D shifts focus to the ArchiMate Technology Layer. This layer describes the computational and physical resources that will support GreenLeaf's future-state business services.

Open your greenleaf-baseline.archimate model in Archi.
In the Models tree on the left, expand the Technology & Physical section.
Right-click Technology & Physical and select New to add the following Node elements: Cloud Application Server, Cloud Database Server, and CDN Node.
Add the following System Software elements: Container Runtime and Managed Database Service.
Add the following Technology Service elements: Web Hosting Service, API Gateway Service, and Database Service.

What Are Nodes, System Software, and Technology Services?

In ArchiMate 3.2, a Node is a computational or physical resource that hosts software. System Software is the software environment running on a node (like a container runtime or managed database engine). A Technology Service is the explicitly defined behavior that a node exposes to the rest of the architecture.

Now create a view that brings these elements together.

Right-click Views in the model tree and select New ArchiMate View.
Name the view Target Technology Architecture.
Drag all the Technology Layer elements you just created onto the canvas.
Also drag the Business Services from your baseline model (Point of Sale Service, Inventory Tracking Service) onto the canvas.
Use Archi's magic connector to draw Serving relationships from your Technology Services up to the Business Services.
Draw Realization relationships from Nodes to their Technology Services (for example, Cloud Application Server realizes Web Hosting Service).
Save the model.

Pro tip: magic connector

Archi's magic connector automatically filters the relationship types that are valid between two elements according to the ArchiMate specification. If you try to connect two elements that cannot be related, Archi will not offer the relationship. This teaches you correct modeling practice as you build.

What should I see?

Your view should show Nodes at the bottom, System Software and Technology Services in the middle, and Business Services at the top. Realization arrows point upward from Nodes to Technology Services. Serving arrows connect Technology Services to Business Services. This layered layout shows how cloud infrastructure supports the business.

Write the Gap Analysis

A gap analysis compares your baseline architecture to your target architecture and identifies every change that needs to happen. Each gap becomes a work item that the project team must address.

Create a new file at 03-phase-d-technology/gap-analysis.md in Cursor.

Structure the document with three sections: Baseline State, Target State, and Gaps. Use Codex CLI to help generate the initial gap table.

Open your terminal and navigate to your project folder.
Run codex to start a Codex CLI session.
Enter the following prompt:

Read my baseline narrative at 02-phase-b-business/baseline-narrative.md. Then create a gap analysis document at 03-phase-d-technology/gap-analysis.md with three sections: Baseline State (on-premise servers, no cloud, no online channel), Target State (cloud-hosted, managed services, online ordering enabled), and Gaps. Format the Gaps section as a Markdown table with columns: Gap ID, Description, Baseline Element, Target Element, Action Required. Include at least 5 gaps.

What does this prompt do?

Codex CLI can read files in your project directory. By pointing it to your baseline narrative, it generates a gap analysis that is grounded in the actual current state you documented. You still need to review and refine the output to make sure each gap is accurate and actionable.

Review the generated file in Cursor.
Verify that each gap has a clear baseline element (what exists today) and a target element (what should exist after migration).
Refine the descriptions so they are specific to GreenLeaf's situation.
Add wiki-links to your principles and vision documents at the bottom of the file.

Your gap table should look something like this:

| Gap ID | Description | Baseline Element | Target Element | Action Required |
|--------|-------------|------------------|----------------|-----------------|
| GAP-01 | No cloud hosting | On-premise server | Cloud Application Server | Migrate workloads to cloud |
| GAP-02 | No online sales channel | None | Web Hosting Service | Build online ordering platform |
| GAP-03 | Manual inventory tracking | Spreadsheets | Managed Database Service | Implement cloud-based inventory system |
| GAP-04 | No content delivery | None | CDN Node | Set up CDN for web assets |
| GAP-05 | No API layer | Direct database access | API Gateway Service | Build API gateway for integrations |

Pro tip: gap quality

A good gap has a concrete action. "Migrate workloads to cloud" is better than "Move to cloud." Each gap should be specific enough that a project manager could turn it into a work package.

Create a C4 System Context Diagram and a Second ADR

A C4 System Context diagram shows your system from the outside. It answers the question: who uses the system, and what external systems does it depend on? You will write this diagram as code using Mermaid's C4 syntax directly inside a Markdown file.

Why Mermaid C4 Instead of Structurizr?

Structurizr Lite has been archived and reached end of life. Its replacement (Structurizr vNext) requires Docker or Java 21+. Mermaid C4 diagrams require zero installation. They render natively in Obsidian, GitHub, and most Markdown viewers. The trade-off is less polished layout, but for a learning project the simplicity is worth it.

Create a new file at 03-phase-d-technology/system-context.md in Cursor.
Add a heading and a Mermaid code block with the following C4 diagram:

# System Context Diagram

```mermaid
C4Context
    title GreenLeaf Retail Platform - System Context

    Person(customer, "Customer", "Browses products and places orders online or in-store")
    Person(storeManager, "Store Manager", "Manages inventory, staff, and daily operations")

    System(retailPlatform, "GreenLeaf Retail Platform", "Core retail system handling POS, inventory, and online ordering")

    System_Ext(paymentGw, "Payment Gateway", "Processes credit card and digital payments")
    System_Ext(supplierPortal, "Supplier Portal", "Supplier ordering and delivery tracking")
    System_Ext(cloudProvider, "Cloud Infrastructure Provider", "Hosts compute, storage, and networking services")

    Rel(customer, retailPlatform, "Browses, orders, pays")
    Rel(storeManager, retailPlatform, "Manages inventory and operations")
    Rel(retailPlatform, paymentGw, "Sends payment requests")
    Rel(retailPlatform, supplierPortal, "Places supplier orders")
    Rel(retailPlatform, cloudProvider, "Deployed on")
```

What does this diagram show?

The C4Context block defines a System Context diagram. Person() elements are the humans who interact with the system. System() is your central system. System_Ext() elements are external systems you depend on. Rel() draws a relationship between any two elements.

Open the file in Obsidian to verify the diagram renders with the Modern Mermaid plugin.

What should I see?

You should see a rendered diagram with two person shapes (Customer, Store Manager), one blue box for the GreenLeaf Retail Platform, and three gray boxes for the external systems. Arrows connect the people and systems with labeled relationships. If you see raw text instead, make sure the Modern Mermaid plugin is enabled in Obsidian's community plugin settings.

Diagram Not Rendering?

Mermaid C4 diagrams are marked as experimental, so syntax errors can be tricky to spot. Make sure there are no extra blank lines inside the C4Context block. Check that every Rel() call has exactly three arguments. Ask for help debugging your Mermaid diagram.

Now document the decision to use managed cloud services with a second ADR.

Create a new file at decisions/0002-use-managed-cloud-services.md.
Copy the MADR v4.0.0 minimal template into the file.
Fill in the Context and Problem Statement: GreenLeaf needs to decide whether to run self-managed infrastructure in the cloud or use managed services.
Fill in the Decision Drivers: small IT team (2 people), limited cloud expertise, need for high availability, budget constraints.
Fill in the Considered Options: managed cloud services (e.g., managed databases, container platforms), self-hosted infrastructure on cloud VMs, hybrid approach.
Fill in the Decision Outcome: managed cloud services, because GreenLeaf's small IT team cannot take on the operational burden of self-managed infrastructure.

Why Write ADRs?

Architecture Decision Records capture the context, options, and reasoning behind key decisions. Six months from now, when someone asks "why did we choose managed services?", the ADR provides the answer. Without ADRs, this knowledge lives only in people's heads and disappears when they leave the project.

Finally, commit everything and link your documents together.

Open your gap analysis and system context files in Obsidian.
Add wiki-links to connect the gap analysis to the system context diagram: [[system-context]].
Add a wiki-link from the system context file back to the gap analysis: [[gap-analysis]].
Add a link from the ADR to the gap analysis: [[gap-analysis]].
Open Obsidian's graph view to verify all your documents are connected.
Commit your changes:

git add .
git commit -m "Phase D: target technology model, gap analysis, C4 diagram, and ADR-0002"

You now have a complete set of TOGAF ADM artifacts spanning Preliminary through Phase D. Your Archi models show where GreenLeaf is today and where it needs to go. Your gap analysis identifies every change required. Your ADRs explain why you made the choices you did. Next up, push everything to GitHub and wrap up your portfolio piece.

Secret mission

Add a Phase E Opportunities & Solutions Roadmap

You have mapped the gaps between GreenLeaf's current state and its cloud future. But a gap analysis without a plan is just a wish list. In this secret mission, you will step into Phase E of the ADM cycle and build a prioritized roadmap that turns your gaps into actionable work packages with timelines, dependencies, and a Gantt chart.

Before you go

Clean Up Your Resources

No paid cloud resources were created in this project. All tools used are free or included in your existing ChatGPT Plus subscription. Your Archi models, Markdown files, and Mermaid diagrams are all local files in your project folder, so there are no ongoing costs.

Decide whether to keep your resources as they are, share them publicly, or archive them for later.

Resources you used:

Local project folder greenleaf-ea with all Markdown files, Mermaid diagrams, and the Archi model.
Obsidian vault pointing to the greenleaf-ea folder.
Archi model file greenleaf-baseline.archimate.
Local Git repository inside the project folder.
GitHub repository (if you pushed during the Secret Mission).
Codex CLI installed globally via npm.
Modern Mermaid community plugin installed in Obsidian.

Keep everything running

No action needed. Choose this if you plan to keep building on this project, extend it with additional ADM phases, or use it as a reference for real architecture work.

Your Obsidian vault, Archi models, and Git repo are all local files. They cost nothing to keep.
Consider pushing to a public GitHub repository to use as a portfolio piece.
You can reuse the folder structure and templates for future TOGAF projects by copying the vault.

Pause - I'll come back to this later

Everything in this project is stored as local files. There are no running processes or cloud services to pause. Your project is already in a paused state by default.

Make sure all your changes are committed by running git status in the project folder.
If you have uncommitted changes, run git add . && git commit -m "WIP: saving progress".
Push to GitHub as a private repo if you want a remote backup.
To resume later, open the greenleaf-ea folder as a vault in Obsidian and open the Archi model file.

Delete - I don't want to use this again

Remove all project resources and installed tools. You can always recreate the project by following this guide again.

Delete the greenleaf-ea folder from your computer.
If you pushed to GitHub, delete the repository from your GitHub account under Settings, then General, then scroll to Danger Zone.
Uninstall Codex CLI by running npm uninstall -g @openai/codex in your terminal.
Uninstall Archi, Obsidian, and Cursor if you no longer need them for other projects.
Remove the Modern Mermaid plugin from Obsidian before uninstalling by going to Settings, then Community Plugins, and clicking Uninstall next to Modern Mermaid.

Mission accomplished

That's a Wrap!

You just ran a complete TOGAF ADM mini-cycle from scratch. That is the same process enterprise architects follow at organizations worldwide to plan and govern major technology changes.

Here is what you learned:

Defined Architecture Principles and documented key decisions using Architecture Decision Records, then built a navigable Obsidian vault linking every artifact together into a professional knowledge base.
Created a Stakeholder Map and Architecture Vision in Phase A that connected business goals to a concrete target architecture for GreenLeaf Groceries.
Built baseline and target ArchiMate models in Archi covering the Business and Technology layers, then performed a Gap Analysis and created a Mermaid C4 System Context diagram to visualize the future state.
Built a Phase E Opportunities & Solutions roadmap with prioritized work packages and a Mermaid Gantt timeline to plan the phased migration.

Ready to quiz yourself?