Talking to Your Code: How Modelith Brings Domain Models to Life

Let's be honest — most projects start with good intentions. Someone sketches out the domain model on a whiteboard, everyone nods along, and then... it quietly dies in a Confluence page nobody updates.

The problem isn't the concept of domain modeling. It's that domain models are typically:

• Written once and forgotten
• Maintained separately from code
• Readable only in specific tools
• Hard to validate automatically

Modelith takes a different approach. Instead of treating your domain model as a deliverable you produce and archive, it treats it as a living artifact that lives alongside your code, gets authored through conversation, and is validated automatically in CI.

What Exactly Is a Domain Model?

Before we go further, let's level-set. A domain model is your system's conceptual map — the nouns (entities), their relationships, and the rules that govern them. It's not a database schema or an API spec. It's the canonical, plain-language expression of what your system is.

Think of it as the vocabulary your entire team shares. When everyone reads from the same model, conversations become sharper, onboarding gets faster, and onboarding new services or features becomes less of an archaeological dig through legacy code.

The Modelith Workflow: Describe, Draft, Validate, Render

Here's where things get interesting. With Modelith, you don't write YAML directly. You don't even think about YAML. You describe your domain concepts in plain language to an AI agent (specifically, a Claude Code skill), and the agent drafts the underlying YAML for you.

The flow looks something like this:

1. Describe — You talk about your domain in plain English. "We have customers who can place orders, and orders contain multiple products, but customers can only have three active orders at a time."

2. Author — The Claude Code plugin translates your description into a modelith.yaml file, validating as it goes.

3. Validate — Run modelith lint to check completeness and consistency. This becomes your CI gate.

4. Render — Run modelith render to generate Markdown with Mermaid diagrams. Commit this alongside the YAML.

The rendered Markdown is human-readable without any tooling. The YAML is the machine-readable source of truth. And CI ensures they never drift apart — think of it like a generated-code check, but for your domain model.

Why This Approach Works

Plain language lowers the barrier

Not everyone on your team is comfortable reading JSON Schema or UML diagrams. But everyone can read plain English. By making plain language the entry point, Modelith democratizes domain modeling. Your product manager can contribute. Your QA engineer can review it. Your junior dev can actually understand the big picture.

AI handles the tedious parts

Writing YAML by hand is error-prone and, frankly, tedious. Letting an AI agent handle the translation from your description to valid YAML means you get the cognitive load off your plate while maintaining precision.

CI validation prevents drift

This is the killer feature for teams. Your domain model becomes a first-class citizen in your development workflow. Every PR that changes the domain gets validated automatically. If someone updates the YAML but forgets to regenerate the docs, CI catches it.

The model stays close to the code

When your domain model lives in the same repository as your code, it stays relevant. It gets reviewed in pull requests. It gets updated when features change. It doesn't become stale documentation in some other system nobody remembers to check.

Getting Started

Modelith is designed to be approachable. You don't need to understand the entire schema upfront. Start small:

• Install the Claude Code plugin
• Describe a few core concepts from your domain
• Let the AI draft the YAML
• Run modelith lint to see what's missing
• Iterate

The project includes worked examples (their parking garage example is a good starting point) that walk you through building a real model from scratch.

The Bigger Picture

Modelith represents a broader trend in AI-assisted development: using natural language as the interface layer while keeping machine-readable artifacts underneath. You write what you mean; the tooling ensures consistency and validation.

For teams building complex systems — especially in domains where the vocabulary matters (fintech, healthcare, logistics, anything with significant business rules) — this approach could be transformative. A shared, validated, living domain model means fewer misunderstandings, faster onboarding, and better-designed systems.

The tool is still evolving, but the core idea is solid. Your domain model shouldn't be an afterthought or a relic from project kickoff. It should be a living document that evolves with your code, authored by conversation, and validated automatically.

If you've struggled to keep domain models relevant in your projects, Modelith is worth exploring. Sometimes the best tooling isn't the most powerful — it's the one that makes the right behavior the path of least resistance.

Check out modelith.sh to get started.