# cogu/autosar architecture

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

- Interactive diagram: https://gitdiagram.com/cogu/autosar
- Repository: https://github.com/cogu/autosar

## Overview

##### Project type and purpose
- This is a **Python library**/toolkit (not a standalone application) for **generating** and **parsing** AUTOSAR XML (ARXML) files.
- Primary use case: allow Python scripts to build AUTOSAR XML documents (via `autosar.xml.Workspace`) and, to a lesser extent, read existing ARXML into Python objects.
- Secondary use case: generate RTE headers from an intermediate model (`autosar.generator`).

##### Top-level architecture layers
A. **Presentation / Client Layer** (User code & examples)
B. **Core Library Layer** (the “autosar” package)
1. XML API (`autosar.xml`)
2. Intermediate Model (`autosar.model`)
3. Code Generator (`autosar.generator`)
C. **Infrastructure Layer** (third‐party dependencies, file system, tests, examples)

##### Main components and their responsibilities
- **User Code / Examples / Scripts**
- scripts in `/examples` call into `autosar.xml.Workspace` and convenience methods in `autosar.xml.element`.
- run via the CLI wrappers (`run_examples.sh` / `.cmd`).
- **autosar.xml** (XML handling)
- **Reader**: `reader.py` parses ARXML into Python objects.
- **Writer**: `writer.py` serializes objects to an ARXML document.
- **Document & Element factories**: builds XML trees.
- **Workspace**: orchestrates packages, documents, template config, API layers (simple vs advanced).
- **autosar.model** (Intermediate representation)
- Mirrors key AUTOSAR meta-model elements (`element.py`, `enumeration.py`, `implementation.py`).
- Provides a decoupled model for RTE generation.
- **autosar.generator** (RTE Type Header Generation)
- Generates C‐header files or other artifacts from the intermediate model (`type_generator.py`).
- **Infrastructure / Utilities**
- **Third-party libraries**: `lxml`, `tomli`, `cfile`.
- **Build & Test**: `pyproject.toml`, `requirements.txt`, GitHub Actions (python‐package.yml), linters (`.pylintrc`, flake8 config).
- **Documentation**: `/doc/markdown`, README, CHANGELOG, LICENSE.
- **Unit Tests**: `/tests` covering xml, model, generator.

##### Interactions & Data Flows
- **User Code → Workspace**: create package maps, elements → add to workspace
- **Workspace → XML Writer**: builds ARXML
- **XML Reader → Workspace → Model**: parsed XML flows into the intermediate model
- **Model → Generator**: model passed to RTE generator for header output
- **Workspace → File System**: read/write ARXML and config files (`.toml`)
- **Workspace → Template Engine** (advanced API)
- **CI/CD & Linters** run on the entire codebase

##### Important patterns & design principles
- **Layered architecture**: clear separation of XML I/O, in-memory model, and code generation
- **Modular design**: each XML element type lives in its own module
- **Convenience factories**: `make_…` and `create_…` methods for user simplicity
- **Simple vs Advanced API** in `Workspace`—highlight as two parallel sub-flows
- **Type hints & Enums**: modern Python 3.10+ usage

## Diagram (Mermaid)

```mermaid
graph TB
    %% Presentation / Client Layer
    subgraph "Presentation / Client Layer"
        direction TB
        UserScripts["User Code / Examples / Scripts"]:::user
        RunSh["run_examples.sh"]:::user
        RunCmd["run_examples.cmd"]:::user
    end

    %% Core Library Layer
    subgraph "Core Library Layer"
        direction TB
        subgraph "XML API" 
            direction TB
            XMLReader["XML Reader\n(parse())"]:::core
            XMLWriter["XML Writer\n(serialize())"]:::core
            DocumentFactory["Document Factory"]:::core
            ElementFactory["Element Factory"]:::core
            BaseUtils["Base & Utilities"]:::core
            Workspace["Workspace\n(simple & advanced API)"]:::user
        end
        subgraph "Intermediate Model"
            direction TB
            ModelElement["Model Element"]:::core
            ModelEnum["Model Enumeration"]:::core
            ModelImpl["Model Implementation"]:::core
        end
        subgraph "Code Generator"
            direction TB
            Generator["RTE Header Generator\n(generate_headers())"]:::core
        end
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        ThirdParty["Third-Party Libs\n(lxml, tomli, cfile)"]:::external
        FileSystem["File System & Templates"]:::infra
        BuildConfig["Build & CI Config"]:::infra
        Docs["Documentation"]:::infra
        TestsXML["XML Unit Tests"]:::infra
        TestsModel["Model Unit Tests"]:::infra
        TestsGen["Generator Unit Tests"]:::infra
    end

    %% Data Stores / Outputs
    ARXMLIn["ARXML Input\n(document)"]:::infra
    ARXMLOut["ARXML Output\n(document)"]:::infra
    CHeader["C-Header Output\n(file)"]:::infra

    %% Interactions & Data Flows
    UserScripts -->|"use API"| Workspace
    RunSh -->|"invoke examples"| UserScripts
    RunCmd -->|"invoke examples"| UserScripts

    Workspace -->|"serialize()"| XMLWriter
    XMLWriter -->|"writes"| ARXMLOut
    ARXMLOut --> FileSystem

    XMLReader -->|"parse()"| Workspace
    ARXMLIn --> XMLReader
    Workspace -->|"to model"| ModelElement
    ModelElement --> ModelEnum
    ModelEnum --> ModelImpl

    ModelImpl -->|"generate_headers()"| Generator
    Generator -->|"writes"| CHeader
    CHeader --> FileSystem

    Workspace -->|"read/write"| FileSystem
    Workspace -.->|"template flow"| BaseUtils

    ThirdParty --> Workspace
    ThirdParty --> XMLReader
    ThirdParty --> XMLWriter
    ThirdParty --> Generator

    BuildConfig -->|CI/CD| TestsXML
    BuildConfig -->|CI/CD| TestsModel
    BuildConfig -->|CI/CD| TestsGen

    TestsXML --> XMLReader
    TestsModel --> ModelElement
    TestsGen --> Generator

    Docs -->Workspace
    Docs --> ModelElement

    %% Click Events
    click UserScripts "https://github.com/cogu/autosar/tree/master/examples/"
    click RunSh "https://github.com/cogu/autosar/blob/master/run_examples.sh"
    click RunCmd "https://github.com/cogu/autosar/blob/master/run_examples.cmd"
    click XMLReader "https://github.com/cogu/autosar/blob/master/src/autosar/xml/reader.py"
    click XMLWriter "https://github.com/cogu/autosar/blob/master/src/autosar/xml/writer.py"
    click DocumentFactory "https://github.com/cogu/autosar/blob/master/src/autosar/xml/document.py"
    click ElementFactory "https://github.com/cogu/autosar/blob/master/src/autosar/xml/element.py"
    click BaseUtils "https://github.com/cogu/autosar/blob/master/src/autosar/xml/base.py"
    click Workspace "https://github.com/cogu/autosar/blob/master/src/autosar/xml/workspace.py"
    click ModelElement "https://github.com/cogu/autosar/blob/master/src/autosar/model/element.py"
    click ModelEnum "https://github.com/cogu/autosar/blob/master/src/autosar/model/enumeration.py"
    click ModelImpl "https://github.com/cogu/autosar/blob/master/src/autosar/model/implementation.py"
    click Generator "https://github.com/cogu/autosar/blob/master/src/autosar/generator/type_generator.py"
    click ThirdParty "https://github.com/cogu/autosar/blob/master/requirements.txt"
    click BuildConfig "https://github.com/cogu/autosar/blob/master/pyproject.toml"
    click BuildConfig "https://github.com/cogu/autosar/blob/master/.github/workflows/python-package.yml"
    click Docs "https://github.com/cogu/autosar/tree/master/doc/markdown/"
    click TestsXML "https://github.com/cogu/autosar/tree/master/tests/xml/"
    click TestsModel "https://github.com/cogu/autosar/tree/master/tests/model/"
    click TestsGen "https://github.com/cogu/autosar/tree/master/tests/generator/"
    click BaseUtils "https://github.com/cogu/autosar/blob/master/src/autosar/xml/template.py"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,color:#000;
    classDef user fill:#98FB98,stroke:#000,color:#000;
    classDef external fill:#FFA500,stroke:#000,color:#000;
    classDef infra fill:#D3D3D3,stroke:#000,color:#000;
```
