Custom Rule-Based Domain and Code Area Configuration (Code Atlas)

Overview

Code Atlas in Cubyts helps organize your codebase into domains and code areas, enabling better impact analysis, ownership clarity, and AI-driven workflows.

Cubyts provides an automatic way to determine domains and code areas, while also allowing customers to define custom rules for greater control and precision.

Configuration types

Code Atlas provides an automatic baseline for domain and code area determination, which can be extended or overridden using custom YAML rules.

Custom Rule-Based Determination (YAML Configuration)

1. Customers can explicitly define domains and code areas using a YAML file

2. Enables alignment with business-specific boundaries and ownership

3. Provides full control over how code is grouped

⚠️ Note

If a file does not match any of the glob patterns defined in the YAML configuration, Cubyts will automatically assign it to domains and code areas using its default logic.

YAML Configuration Requirements

To define custom domains and code areas absolutely controlled by you (based on your definition), you must create a YAML file with a specific structure and location. 

1. File path: .cubyts/areas.yml

2. Branch requirement: The file must be merged into the configured main/default branch configured in your Cubyts Git integration.

3. Important: Cubyts will only pick up the configuration if:

   1. The file is named exactly areas.yml.

   2. It is placed under .cubyts/.

   3. It exists in the configured default branch.

YAML Structure

The YAML file defines:

1. Domains → High-level functional grouping

2. Areas → Subsections within a domain

3. Globs → File path patterns that map code to areas

Structure

domains:

  - label: "<Domain Name>"

    description: "<Optional description>"

    areas:

      - label: "<Area Name>"

        description: "<Optional description>"

        globs:

          - "<file path pattern>"

Sample YAML Configuration

domains:

  - label: "Axios HTTP Client"

    description: "HTTP Proxy Layer for all external access to other systems"

    areas:

      - label: "HTTP endpoint controllers"

        description: "All controllers for the http operations"

        globs:

          - "aint/axioshelper/api/controllers/**"

      - label: "HTTP endpoint models and routes"

        globs:

          - "aint/axioshelper/api/models/**"

          - "aint/axioshelper/api/routes/**"

      - label: "Server, Utils & Configuration"

        globs:

          - "aint/axioshelper/api/**"

  - label: "Third Party Integrations"

    areas:

      - label: "Common API and Utils"

        globs:

          - "aint/common/**"

      - label: "SAP"

        globs:

          - "aint/SAP/**"

      - label: "Atlassian Jira"

        globs:

          - "aint/jira/**"

      - label: "Salesforce Slack"

        globs:

          - "aint/slack/**"

  - label: "Edge Proxy (TCP & HTTP)"

    areas:

      - label: "Protocol Support"

        globs:

          - "UI/3rdparty/edge/proxy/http/**"

          - "UI/3rdparty/edge/proxy/tcp/**"

      - label: "Pre and Post Processing"

        globs:

          - "UI/3rdparty/edge/proxy/processors/**"

      - label: "Server, Utils & Configuration"

        globs:

          - "UI/3rdparty/edge/proxy/**"

How It Works

1. Glob patterns map files to code areas.

2. Code areas are grouped into domains.

3. This structure is used for:

   1. Impact radius analysis.

   2. Code ownership understanding.

   3. AI agent context.

Best Practices

1. Keep domains aligned with business capabilities.

2. Avoid overlapping glob patterns.

3. Use specific paths instead of broad patterns.

4. Add descriptions for better clarity.

5. Review YAML changes via pull requests.

Troubleshooting

When to Use YAML configuration

Summary

1. Cubyts provides automatic domain and area detection by default

2. YAML configuration allows customization and precision

3. Files not covered by YAML rules are still handled automatically

4. Use YAML when accuracy and business alignment are critical 

Footnote: Automatic Determination (Cubyts Logic)

Cubyts can automatically determine domains and code areas without any manual configuration by analyzing repository structure, folder hierarchy, and code semantics. It groups related files into logical domains and areas, enabling quick setup and faster onboarding.

This approach is best suited for initial setup or well-structured repositories where minimal configuration is preferred. However, automatically inferred domains may not always align with business-specific boundaries. For precise control and customization, defining rules via YAML configuration is recommended.