# zephyrproject-rtos/west architecture

> Architecture diagram of the GitHub repository zephyrproject-rtos/west, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zephyrproject-rtos/west
- Repository: https://github.com/zephyrproject-rtos/west

## Overview

##### Project type and purpose
- West is a Python-based CLI meta-tool for managing multiple Git repositories according to a YAML “manifest” file.
- It’s not a web service or GUI; it’s a single binary (console) application that orchestrates Git operations, parses manifests, and provides an extensible command framework.

##### File structure
- Top-level:
- Configuration & metadata: pyproject.toml, README.rst, LICENSE, tox.ini, CI workflows under .github, docker-testing
- Source code under src/west:
– __main__.py: CLI entrypoint
– commands.py: top-level sub-command dispatcher
– app/: core implementation (config.py, main.py, project.py, manifest/schema)
– util.py, log.py, configuration.py, version.py
– manifest.py & manifest-schema.yml: manifest parsing & validation
– west-commands-schema.yml: extension/plugin schema
- Tests under tests/ using pytest via tox.
- docker-testing: containerized environment for distro-specific testing.

##### README for additional insights
- Lists major commands: init, update, extensible sub-commands.
- Emphasizes plugin/extension support (“add new commands without modifying its source code”).
- Describes workflows: pip install, tox test, docker testing.

##### Main components & interactions
a. CLI Layer
- Entrypoint (src/west/__main__.py) invokes commands.py
- Command dispatcher routes to built-in or extension commands
b. Core Application Layer (src/west/app)
- Configuration Manager (config.py): loads pyproject, CLI args, manifest defaults
- Manifest Processor (manifest.py + schema): parses, validates YAML manifest; builds internal manifest model
- Project Manager (project.py): given manifest model, computes repository list, local paths, remote URLs
- Main Orchestrator (main.py): coordinates init, update, other operations; calls Git subprocesses
c. Utility Layer
- Logging (log.py): sets up console/file logging
- Generic helpers (util.py): filesystem, subprocess, path manipulation
- Version (version.py): package version metadata
d. Extension/Plugin Layer
- west-commands-schema.yml defines how external commands hook into commands.py
- CLI dispatcher dynamically loads plugin entry points
e. External Systems
- Remote Git servers (manifest remotes)
- Local file system for clone/update
- CI/CD (tox, GitHub Actions, Docker)
f. Testing Infrastructure
- pytest tests under tests/
- docker-testing directory for distro-specific container tests
- CI workflows (.github/workflows/*.yml) invoke lint, test, security scans

##### Architectural patterns
- Modular CLI with plugin architecture (extension points via entry points and schema)
- Clear separation: CLI dispatch -> core services -> utilities -> external
- Model-View-Controller analogy:
- Controller = command dispatcher
- Model = manifest & project representations
- View = console output via logging

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    User["User Console (stdin/stdout)"]:::ui
    subgraph "CLI Layer"
        CLIEntrypoint["__main__.py\n(CLI Entrypoint)"]:::ui
        Dispatcher["commands.py\n(Command Dispatcher)"]:::ui
    end

    %% Core Application Layer
    subgraph "Core Application Layer"
        ConfigMgr["config.py\n(Configuration Manager)"]:::core
        ManifestProc["manifest.py\n(Manifest Processor)"]:::core
        ManifestSchema["manifest-schema.yml\n(Manifest Schema)"]:::core
        ProjectMgr["project.py\n(Project Manager)"]:::core
        Orchestrator["main.py\n(Main Orchestrator)"]:::core
    end

    %% Utility Layer
    subgraph "Utility Layer"
        Logging["log.py\n(Logging)"]:::util
        UtilHelpers["util.py\n(Utility Helpers)"]:::util
        VersionMeta["version.py\n(Version Metadata)"]:::util
    end

    %% Plugin Layer
    subgraph "Plugin/Extension Layer"
        PluginSchema["west-commands-schema.yml\n(Plugin Schema)"]:::plugin
        PluginLoader["Plugin Loader"]:::plugin
    end

    %% External Dependencies
    subgraph "External Systems"
        GitRemotes["Remote Git Servers"]:::external
        FileSystem["Local File System"]:::external
    end

    %% Testing / CI
    subgraph "Testing & CI/CD"
        CIWorkflows[".github/workflows/\n(CI/CD Workflows)"]:::test
        PytestTests["tests/\n(Pytest Tests)"]:::test
        DockerTests["docker-testing/\n(Docker Tests)"]:::test
    end

    %% Main Flow
    User -->|invoke| CLIEntrypoint
    CLIEntrypoint -->|calls| Dispatcher
    Dispatcher -->|load config| ConfigMgr
    ConfigMgr -->|load manifest| ManifestProc
    ManifestProc -->|validate with schema| ManifestSchema
    ManifestProc -->|produce model| ProjectMgr
    ProjectMgr -->|compute repos| Orchestrator
    Orchestrator -->|git clone/update| GitRemotes
    Orchestrator -->|read/write| FileSystem

    %% Plugin Flow
    Dispatcher -.->|load plugins| PluginLoader
    PluginLoader -->|validate with schema| PluginSchema

    %% Utilities Usage
    ConfigMgr -.-> Logging
    ManifestProc -.-> Logging
    ProjectMgr -.-> Logging
    Orchestrator -.-> Logging

    ConfigMgr -.-> UtilHelpers
    ManifestProc -.-> UtilHelpers
    ProjectMgr -.-> UtilHelpers
    Orchestrator -.-> UtilHelpers

    CLIEntrypoint -.-> VersionMeta

    %% Testing & CI triggers
    CIWorkflows -->|run tests| PytestTests
    CIWorkflows -->|docker tests| DockerTests
    PytestTests -->|invoke CLI| CLIEntrypoint
    DockerTests -->|invoke CLI| CLIEntrypoint

    %% Click Events
    click CLIEntrypoint "https://github.com/zephyrproject-rtos/west/blob/main/src/west/__main__.py"
    click Dispatcher "https://github.com/zephyrproject-rtos/west/blob/main/src/west/commands.py"
    click ConfigMgr "https://github.com/zephyrproject-rtos/west/blob/main/src/west/app/config.py"
    click ManifestProc "https://github.com/zephyrproject-rtos/west/blob/main/src/west/manifest.py"
    click ManifestSchema "https://github.com/zephyrproject-rtos/west/blob/main/src/west/manifest-schema.yml"
    click ProjectMgr "https://github.com/zephyrproject-rtos/west/blob/main/src/west/app/project.py"
    click Orchestrator "https://github.com/zephyrproject-rtos/west/blob/main/src/west/app/main.py"
    click Logging "https://github.com/zephyrproject-rtos/west/blob/main/src/west/log.py"
    click UtilHelpers "https://github.com/zephyrproject-rtos/west/blob/main/src/west/util.py"
    click VersionMeta "https://github.com/zephyrproject-rtos/west/blob/main/src/west/version.py"
    click PluginSchema "https://github.com/zephyrproject-rtos/west/blob/main/src/west/west-commands-schema.yml"
    click CIWorkflows "https://github.com/zephyrproject-rtos/west/tree/main/.github/workflows/"
    click PytestTests "https://github.com/zephyrproject-rtos/west/tree/main/tests/"
    click DockerTests "https://github.com/zephyrproject-rtos/west/tree/main/docker-testing/"

    %% Styles
    classDef ui fill:#E0F7FA,stroke:#006064,color:#006064;
    classDef core fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20;
    classDef util fill:#ECEFF1,stroke:#37474F,color:#37474F;
    classDef plugin fill:#FFF3E0,stroke:#E65100,color:#E65100;
    classDef external fill:#FFF8E1,stroke:#FF6F00,color:#FF6F00;
    classDef test fill:#F3E5F5,stroke:#4A148C,color:#4A148C;
```
