Models Overview

A semantic model is the heart of every Semantius platform. It describes your domain as data: the entities you care about, the attributes that define them, the relationships between them, and the rules that govern who can access what. Models are built and evolved through agent skills and consumed by AI clients through MCP connectors.

What a Model Contains

• Entities: the concepts in your domain (customers, orders, projects, devices).
• Fields: the attributes of each entity, with human-readable labels, descriptions, and UI hints.
• Relationships: how entities reference or own each other. Use reference for cross-entity links and parent for ownership and composition.
• RBAC: roles, permissions, and the access policies that govern reads and writes.

The model is data, not code. It can be inspected, edited, versioned, and manipulated by agents.

Under the Hood

A semantic model is a single self-contained markdown file. Front-matter at the top carries identity (system_slug, system_name, domain) and discovery tags. The body lays out an overview, an entity summary table, a Mermaid entity-relationship diagram, per-entity field tables, a relationship summary, and an enumerations section.

Because it is just markdown, a model is:

• Versioned in the same Git repository as the rest of your code.
• Reviewed in pull requests, with diffs your team can read and reason about.
• Discussed by humans and agents in the same vocabulary, since both audiences read the same file.
• Portable between environments: the same file deploys to dev, staging, and production.

For a concrete example, see the SaaS Expense Tracker model. It is fairly detailed (a real model usually has dozens of fields and a non-trivial relationship graph), but in day-to-day work you rarely open the file by hand: the Create, Customize, Deploy, and Optimize skills do the reading, writing, and diffing for you.

The Model Lifecycle

Semantius treats a model as a living artifact, not a one-shot ship. Four agent skills span its full lifecycle, and each gets its own page:

• Create a custom model from scratch by interviewing your domain.
• Templates are curated, ready-to-use models you can deploy as-is or customize first.
• Deploy a model to a live Semantius instance, with safe diffing and conflict resolution.
• Optimize by reverse-engineering a live module back into a markdown spec you can audit and improve.

Together they form a closed loop: design, deploy, customize in the platform, pull back down, refine, redeploy.