Structure & Organization

Why Domain-Driven Structure?

Organizing your design content by Domain (e.g., identity, payments) rather than by file type is crucial for effective AI-assisted development. This approach creates clear Context Boundaries, allowing you to feed an AI agent the complete "truth" about a specific domain—its business logic (Markdown), API contracts (OpenAPI), and events (AsyncAPI)—without distracting noise.

For a deeper dive into this philosophy, read Harmonizing AI Code Generation with Centralized System Design (opens in a new tab).

Directory Structure

The content directory follows a strict separation between Global Architecture and Bounded Contexts (Domains).

1. Root Configuration

xeocontext.config.json: [MANDATORY] The central navigation and metadata map for the viewer.

2. The "Global" Directory (/global) Defines the laws of the system and cross-cutting concerns.

Gateway (/global/gateway): Contains the Master Root files (openapi.yaml, asyncapi.yaml). These files aggregate endpoints and channels from all domains to provide a unified "System View".
ADRs (/global/adrs): Architecture Decision Records explaining why decisions were made.
Standards (/global/standards): Naming conventions, error handling, etc.

3. Domain Modules (/domains) Each folder represents a specific business capability (e.g., identity, payments).

Co-location: Markdown, OpenAPI, and AsyncAPI specs reside together.
Fragmented Architecture: Actual definitions (Schemas, Paths) should live in components/ subfolders and be aggregated by the domain's root openapi.yaml.

/content
├── xeocontext.config.json        # [MANDATORY] Main configuration
├── global/                       # [MANDATORY] Cross-cutting architecture
│   ├── gateway/                  # Unified System API (Master Roots)
│   │   ├── openapi.yaml          # Imports from all domains
│   │   └── asyncapi.yaml
│   ├── adrs/                     # Architecture Decision Records
│   └── standards/                # Global Standards
└── domains/                      # [MANDATORY] Business Logic
    ├── {domain-name}/            # e.g., identity, payments
    │   ├── readme.md             # Domain overview
    │   ├── openapi.yaml          # Domain-specific API Root
    │   ├── asyncapi.yaml         # Domain-specific Event Root
    │   └── components/           # Reusable schemas & paths
    │       ├── schemas/
    │       └── paths/

Content Validation

It is recommended to validate your spec files before committing changes to ensure the viewer renders them correctly.

OpenAPI Validation

You can use Redocly CLI (opens in a new tab) to lint and bundle your OpenAPI definitions.

# Lint the main gateway file (and all its references)
pnpm --package=@redocly/cli dlx redocly lint content/global/gateway/openapi.yaml
 
# Lint a specific domain file
pnpm --package=@redocly/cli dlx redocly lint content/domains/identity/components/paths/auth_login.yaml

AsyncAPI Validation

You can use AsyncAPI CLI (opens in a new tab) to validate your AsyncAPI definitions.

# Validate the main gateway file
pnpm dlx @asyncapi/cli validate content/global/gateway/asyncapi.yaml

Setup & Installation Configuration