Skip to content
Architecture Catalog

How to Contribute

Development setup

Section titled “Development setup”
Terminal window
git clone https://github.com/ea-toolkit/architecture-catalog.git
cd architecture-catalog
cd catalog-ui
npm install
npm run dev

Open http://localhost:4321 and verify the catalog renders.

Types of contributions

Section titled “Types of contributions”

Registry data

Section titled “Registry data”

Add or improve architecture elements. No code changes needed.

Where: registry-v2/**/*.md

Schema changes

Section titled “Schema changes”

Add new element types, fields, or relationship types.

Where: models/registry-mapping.yaml

UI changes

Section titled “UI changes”

Modify the catalog interface, add pages, or update styles.

Where: catalog-ui/src/

Documentation

Section titled “Documentation”

Improve the docs site or fix typos.

Where: docs-site/src/content/docs/

Workflow

Section titled “Workflow”

Branch naming

Section titled “Branch naming”
feat/description      -- New feature
fix/description       -- Bug fix
docs/description      -- Documentation only
schema/description    -- Schema changes
data/description      -- Registry data additions

Commit messages

Section titled “Commit messages”
feat: add dark mode toggle to catalog UI
fix: resolve slug collision for cross-type duplicates
docs: add deployment guide for Docker
schema: add domain_event element type
data: add 15 physical APIs for Order Management domain

Pull request process

Section titled “Pull request process”
  1. Fork the repository
  2. Create a feature branch from main
  3. Make your changes
  4. Run validation:
    Terminal window
    cd catalog-ui && npm run build
  5. Commit and push
  6. Open a PR against main

Code conventions

Section titled “Code conventions”

TypeScript

Section titled “TypeScript”
  • Strict mode — no any types
  • All type names, field names, and labels come from the mapping YAML — never hardcode them
  • camelCase for functions/variables, PascalCase for types/interfaces
  • kebab-case for page files, PascalCase for React components

YAML

Section titled “YAML”
  • 2 spaces indentation
  • snake_case keys
  • Use # comments to explain non-obvious decisions

Markdown

Section titled “Markdown”
  • YAML frontmatter between --- markers
  • kebab-case filenames
  • Every type folder should have a _template.md

Architecture rules

Section titled “Architecture rules”

Schema-driven UI

Section titled “Schema-driven UI”

The UI must never hardcode element type names, field names, or relationship labels. Everything comes from registry-mapping.yaml.

// Bad
if (element.type === 'software_system') { ... }


// Good
const typeDef = mapping.elements[element.typeKey];
const label = typeDef?.label ?? element.typeKey;

Graceful degradation

Section titled “Graceful degradation”

Missing data should never break the build:

const description = element.fields.description ?? 'No description';

Three-layer separation

Section titled “Three-layer separation”
  • Schema changes should not require UI code changes
  • Data additions should not require schema or UI changes
  • UI changes should not require data format changes

Testing

Section titled “Testing”

The primary test is a successful build:

Terminal window
cd catalog-ui && npm run build

For UI changes, verify these pages render correctly:

  1. Dashboard (/)
  2. Domain overview (/domains/<id>)
  3. Element detail (/catalog/<id>)
  4. Context map (/domains/<id>/context-map)
  5. Discover (/discover)