Archetypes

An archetype is the type of a board element. It gives a node meaning beyond its shape — "API Gateway", "PostgreSQL Database", "Message Queue" — and carries the styling, structure rules, and governance standards that keep every board consistent. Pick the right archetype and your map stays legible and structurally valid as it grows; see Nodes & Edges for how nodes and edges use them.

Archetypes earn their keep four ways:

• Consistency — every "Service" looks and behaves the same across boards.
• Structure — containment rules decide what can nest inside what, so the graph stays valid.
• Governance — standards and context tags turn a diagram into something queryable.
• Grounding — Cdx Code and chat reference your archetypes, so generated elements land on a type you defined instead of a guess.

The built-in library

Every workspace starts with a shared library you don't have to build. Archetypes are grouped by where they come from:

Built-in archetypes are shared across every organization and read-only. In Settings → Element Archetypes, Load Default Archetypes pulls the current library into your catalogue.

Anatomy of an archetype

The visual primitive decides how an element renders and whether it can contain others:

Manage the catalogue

Open Settings → Element Archetypes. The Catalogue tab lists every archetype available to your org — search it, or filter by group, visual primitive, and catalogue type.

Expand

Create a custom archetype with Create Archetype. The form is organized into four tabs:

• Basic — name (it auto-fills the slug), description, visual primitive, and default tags.
• Fields — the field templates this type expects.
• Styles — shape, icon, fill, stroke, effects, corners, and font.
• Advanced — standards (AI guidance) and containment rules (what this archetype can contain).

Custom archetypes are scoped to your organization. Built-in archetypes are shared and read-only — editing one is copy-on-write: the platform creates an org-owned copy with your changes and leaves the shared original intact. Delete only affects archetypes your org owns.

Tip

Start with a handful of archetypes that match how your team actually talks about the system. Over-configuring upfront usually leaves half of them unused.

Containment rules

Containment rules are what make a board a structure instead of a pile of boxes. Each archetype lists which archetypes it can hold — a Domain contains Systems, a System contains Services, a Region holds availability zones. When an element is placed on a board or pushed through the Boards API, nesting that breaks the rules is rejected, so the graph can't drift into something invalid.

This is the backbone of drill-down: a container archetype that holds child nodes is exactly what lets you click into a system and descend into its services. See Workboards → Layers.

Standards and governance

Each archetype can carry standards — short guidelines like "RESTful Design" or "Microservices Architecture" that the AI follows when it generates or updates an element of that type. Standards shape what Cdx Code and chat produce so new elements match your conventions.

Pair archetypes (what a node is) with context tags (where it belongs — domain, team, compliance tier) and your landscape becomes queryable: "every Gateway in the identity domain", "Services with no owning team". The Architect's guide walks through this governance pattern.

Review archetype proposals

You don't have to anticipate every type. When Cdx Code runs /analyze-archetypes, it scans for component patterns that don't fit your catalogue and submits proposals instead of inventing types silently. They land in the Proposals tab for an admin to review.

Expand

A proposal is one of two kinds:

• New — a type the catalogue is missing. Approving it adds an org-scoped archetype you can then refine in the Catalogue tab.
• Improvement — a change to an existing type. Rename and redescribe apply on approval; split and merge are handled manually, since they move nodes between types.

Approving merges the proposal into your catalogue; rejecting keeps a note on why. Either way the plugin gets a settled vocabulary to map against — which is why /analyze-archetypes is a precondition for /analyze.

Archetypes and the plugin

Each node stores its archetype by name, so plugins must use names that exist in your catalogue. Cdx Code fetches them through the Boards API:

GET /code-plugin/archetypes

Keep the catalogue settled first (review pending proposals), and every /analyze → /sync lands components on the right types. See the ContextDX Plugins for the two-phase /analyze-archetypes → /analyze workflow.

Related docs

• Nodes & Edges — how nodes and edges reference archetypes
• Workboards — board types and the layer model containment enables
• Organization Settings — context tags, field templates, icons, and roles alongside archetypes
• ContextDX Plugins — the /analyze-archetypes proposal workflow
• Boards API — fetching valid archetype names for plugins
• For Architects — governing a landscape with archetypes and tags