# devartslab/universal-ai-config architecture

> Architecture diagram of the GitHub repository devartslab/universal-ai-config, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devartslab/universal-ai-config
- Repository: https://github.com/devartslab/universal-ai-config

## Overview

Universal AI Configuration is a Python CLI and library that consolidates AI-agent settings and shared resources across providers. The principal workflow is to initialize a user or project configuration, migrate existing provider data when present, then let provider integrations retrieve merged settings. Configuration merging, project-local overrides, MCP servers, skills, rules, and status/validation are also represented. The README documents additional migration coverage; sampled migration code is partial, so uncertain internal steps and wiring are omitted.

Main entry points: [`universal_ai_config/config.py`](https://github.com/devartslab/universal-ai-config/blob/main/universal_ai_config/config.py) (Unified settings), [`universal_ai_config/cli.py`](https://github.com/devartslab/universal-ai-config/blob/main/universal_ai_config/cli.py) (CLI commands), [`universal_ai_config/migration.py`](https://github.com/devartslab/universal-ai-config/blob/main/universal_ai_config/migration.py) (Provider migrator), [`universal_ai_config/environment.py`](https://github.com/devartslab/universal-ai-config/blob/main/universal_ai_config/environment.py) (Environment paths)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command interface"]
  node_cli["CLI commands<br/>[cli.py]"]
end

subgraph group_config["Configuration"]
  node_env["Environment paths<br/>[environment.py]"]
  node_unified["Unified settings<br/>[config.py]"]
end

subgraph group_migration["Migration"]
  node_migrator["Provider migrator<br/>[migration.py]"]
end

subgraph group_project["Project resources"]
  node_project_config["Project configuration<br/>[project.py]"]
end

node_user(("Engineer"))
node_provider(("Provider integration"))
node_legacy["Legacy provider files"]
node_managed["Managed configuration files"]
node_skills_rules["Skills and rules"]

node_user -->|"runs commands"| node_cli
node_cli -->|"resolves paths"| node_env
node_cli -->|"reads or updates"| node_unified
node_cli -->|"starts migration"| node_migrator
node_cli -->|"initializes project files"| node_managed
node_migrator -->|"discovers and reads"| node_legacy
node_migrator -->|"imports settings"| node_unified
node_migrator -->|"copies resources"| node_skills_rules
node_migrator -->|"uses paths"| node_env
node_unified -->|"resolves storage"| node_env
node_unified -->|"loads and saves"| node_managed
node_provider -->|"requests provider config"| node_unified
node_project_config -->|"finds project"| node_env
node_project_config -->|"reads and writes project files"| node_managed
node_project_config -->|"uses merge and JSON helpers"| node_unified

click node_cli "https://github.com/devartslab/universal-ai-config/blob/main/universal_ai_config/cli.py"
click node_env "https://github.com/devartslab/universal-ai-config/blob/main/universal_ai_config/environment.py"
click node_unified "https://github.com/devartslab/universal-ai-config/blob/main/universal_ai_config/config.py"
click node_project_config "https://github.com/devartslab/universal-ai-config/blob/main/universal_ai_config/project.py"
click node_migrator "https://github.com/devartslab/universal-ai-config/blob/main/universal_ai_config/migration.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli toneBlue
class node_env,node_unified toneAmber
class node_migrator toneMint
class node_project_config toneRose
class node_user,node_provider,node_legacy,node_managed,node_skills_rules toneIndigo
```

## Components

### Command interface

- [CLI commands](https://github.com/devartslab/universal-ai-config/blob/main/universal_ai_config/cli.py): `universal_ai_config/cli.py`

### Configuration

- [Environment paths](https://github.com/devartslab/universal-ai-config/blob/main/universal_ai_config/environment.py): `universal_ai_config/environment.py`
- [Unified settings](https://github.com/devartslab/universal-ai-config/blob/main/universal_ai_config/config.py): `universal_ai_config/config.py`

### Migration

- [Provider migrator](https://github.com/devartslab/universal-ai-config/blob/main/universal_ai_config/migration.py): `universal_ai_config/migration.py`

### Project resources

- [Project configuration](https://github.com/devartslab/universal-ai-config/blob/main/universal_ai_config/project.py): `universal_ai_config/project.py`

### Other components

- **Engineer**
- **Provider integration**
- **Legacy provider files**
- **Managed configuration files**
- **Skills and rules**

## Connections

- Engineer → CLI commands: runs commands
- CLI commands → Environment paths: resolves paths
- CLI commands → Unified settings: reads or updates
- CLI commands → Provider migrator: starts migration
- CLI commands → Managed configuration files: initializes project files
- Provider migrator → Legacy provider files: discovers and reads
- Provider migrator → Unified settings: imports settings
- Provider migrator → Skills and rules: copies resources
- Provider migrator → Environment paths: uses paths
- Unified settings → Environment paths: resolves storage
- Unified settings → Managed configuration files: loads and saves
- Provider integration → Unified settings: requests provider config
- Project configuration → Environment paths: finds project
- Project configuration → Managed configuration files: reads and writes project files
- Project configuration → Unified settings: uses merge and JSON helpers