Last updated October 27, 2026

On this page

Organization Settings

Organization settings define the vocabulary and visual style every board in your organization shares. Manage them from Settings.

Configure your organization

For a new organization:

Define your core element archetypes (Service, Database, API Gateway, etc.)
Create context tags for cross-cutting concerns (team ownership, compliance scope, lifecycle status)
Add field templates for custom metadata you want to track on nodes
Upload icons for your archetypes (or use the built-in icon library)
Configure insight skills if you plan to run automated analysis

Settings categories

Element archetypes

An archetype defines one type of board element. Each archetype sets:

Property	What it does
Name	The identifier used across the platform (e.g., "Service", "Database", "API Gateway")
Description	What this archetype represents
Visual primitive	The shape type: node, container, region, or edge
Icon	The custom icon board elements display
Color / styling	The default appearance on a board
Containment rules	Which archetypes this one can contain (e.g., a "System" can contain "Services")

The code plugin references archetypes by name. Manage the catalogue and proposals in Archetypes.

Context tags

Context tags are organization-wide labels you filter and group by, such as "team-payments", "deprecated", or "pci-scope".

Load Default Tags adds seven. owner:team names the team that owns a system, and six are for work items: change:breaking, change:needs-adr, change:quick-win, risk:tech-debt, risk:security-review and blocked:external. Every other tag is yours to create.

Important

Changed 26 October 2026: the provided set is seven tags, and archetypes add no tags to the nodes and edges made from them.

A tag named domain:<name>, such as domain:billing, is a domain: the business area a node belongs to, filed under the domain category. The code plugin creates domain tags as it tags your boards, and it creates no other tags. Tables, endpoints and channels group by the domain of the node that uses them on the Aspects screen, and renaming a domain tag renames it everywhere.

Icon library

Custom icons are SVGs organized by provider and version. Upload them in Settings, and every board can use them.

Playbooks

Playbooks are the guided tracks your organization runs, both the provided ones and your own. Fork a provided playbook to make it yours, compose a new one with New playbook, or turn off Enabled on one nobody should start. Forking, composing, enabling or disabling, and deleting need Pro.

The Sidebar switch on each row picks the playbooks, up to five, that everyone in the organization sees in the sidebar. Only an owner or admin can change it. See Playbooks.

Change rules

Change rules are the questions every change period answers about what changed, one list for every repo in the organization. Four are provided: Structure, Schema, API contract and Infrastructure.

Owners and admins add rules with New rule, customize or switch off the provided ones, and mark a rule Critical so a Changed answer raises a flag. At most eight rules are on at once. /changes reads the list on each run. See Change rules.

Insight skills

An insight skill defines a reusable analysis:

Property	Description
Name / slug	Display name and unique identifier
Category	Analysis type (e.g., performance, security, cost)
Instructions	The prompt template that guides the analysis
References	Supporting documents a run can consult
Colour	The theme color that identifies the skill

You manage insight skills at the organization level and can run them from any board. External plugins can also discover and use them through the Boards API.

Advanced config

Containment rules

The UI and pushes from the code plugin both enforce an archetype's containment rules and reject invalid nesting.

The visual primitive sets how an element renders:

Primitive	Behavior
Node	Standard element with fixed size, icon, and label
Container	Expandable group that can hold child nodes
Region	Background zone for visual grouping without strict containment
Edge	Connection between nodes, with an optional label

Icon storage backends (self-hosted)

In a self-hosted deployment, you store icons on the local filesystem or in S3. The ICON_STORAGE_BACKEND environment variable selects the backend.

Local filesystem (default, good for development):

BASH

# Defaults to public/icons relative to the server root
ICON_STORAGE_PATH=public/icons

AWS S3 (recommended for production / ECS deployments):

BASH

ICON_STORAGE_BACKEND=s3
AWS_BUCKET_NAME=your-bucket-name
AWS_REGION=us-east-1
# When running in ECS, credentials are auto-discovered from the task IAM role.
# Explicit keys are only needed for local dev with S3:
# AWS_ACCESS_KEY_ID=...
# AWS_SECRET_ACCESS_KEY=...

Icons are stored under {provider}/{version}/{filename} (e.g., aws/2024-01/s3.svg). In production they're served with long-lived CDN caching headers.

Note

Start with a few core archetypes and tags, and add more later.

What's next

Enterprise SSO

Set up single sign-on with your identity provider and require it org-wide.

Permissions & Access

Control who can view and edit boards, internally and when published.

Integrations Reference

Every connector, whose account it uses, and who can set it up.

Boards Guide

Learn how boards and layers organize your architectural views.