# dennis6p/adaptive-cards-py architecture

> Architecture diagram of the GitHub repository dennis6p/adaptive-cards-py, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dennis6p/adaptive-cards-py
- Repository: https://github.com/dennis6p/adaptive-cards-py

## Overview

##### Project Type and Purpose
- The project is a Python library providing a thin wrapper for creating, updating, validating, and sending Adaptive Cards (primarily for MS Teams).
- Its primary goals are to simplify the creation of adaptive cards with strong type-checking (using Python’s typing and Pydantic), enforce schema validations, and integrate with external services (like MS Teams via a dedicated client).
- The README clearly outlines the features, usage, library structure, and real-world examples, making it clear that this is a full-featured library aimed at both card creation and card validation.

##### File Structure
- Top-Level Directories:
- “src”: Contains the core library code under src/adaptive_cards – this is where the main modules live:
- “card.py”: Likely the central “AdaptiveCard” builder.
- “elements.py”, “containers.py”, “actions.py”, “inputs.py”: Individual modules representing different card components.
- “card_types.py”: Contains custom types for card attributes.
- “validation.py”: Implements card validation logic.
- “schemas/”: Stores various JSON schemas (versions 1.0 to 1.6) for validating cards.
- “utils.py”: Likely houses shared utilities.
- “examples”: Provides example scripts that show how to create, update, and validate cards as well as send them using a Teams client.
- “tests”: Contains unit tests to verify key functionality (creating a card, validating structure, and client behavior).
- Other supportive files like “pyproject.toml”, “ruff.toml”, “build.sh”, and GitHub workflows help with configuration, building, linting, and deployment.

##### README for Additional Insights
- The README gives a comprehensive overview of the library usage including:
- How to build a simple or complex Adaptive Card.
- Details on updating card components and validating against a schema.
- Integration with external services via a Teams client.
- It highlights the architectural separation (distinct modules for elements, containers, actions, and inputs), and stresses type-checking and validation using Pydantic and JSON Schema.

##### Final Advice
- Be as detailed as necessary – list all components (even if it means breaking down the card’s internal modules individually).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Card Composition Layer"
        ACB["AdaptiveCard Builder"]:::core
        ELM["Elements Module"]:::composition
        CNT["Containers Module"]:::composition
        ACT["Actions Module"]:::composition
        INP["Inputs Module"]:::composition
        CTD["Card Types Definition"]:::composition
    end

    subgraph "Validation Layer"
        VAL["Validation Module"]:::validation
        SCH["Schemas Directory"]:::schema
    end

    subgraph "External Integration"
        TC["TeamsClient"]:::integration
    end

    subgraph "Supporting Components"
        UT["Supporting Utilities"]:::support
        EXP["Examples"]:::support
        TST["Tests"]:::support
    end

    %% Component Interactions
    ELM -->|"add_item"| ACB
    CNT -->|"add_item"| ACB
    ACT -->|"add_item"| ACB
    INP -->|"add_item"| ACB
    CTD -->|"defines_types"| ACB

    ACB -->|"validate_card"| VAL
    VAL -->|"uses_schema"| SCH
    VAL -->|"returns_card"| ACB

    ACB -->|"send_card"| TC

    UT --- ACB
    UT --- VAL
    UT --- TC

    EXP -->|"demonstrates"| ACB
    TST -->|"verifies"| ACB

    ACB -->|"update_item"| ACB

    %% Click Events
    click ACB "https://github.com/dennis6p/adaptive-cards-py/blob/main/src/adaptive_cards/card.py"
    click ELM "https://github.com/dennis6p/adaptive-cards-py/blob/main/src/adaptive_cards/elements.py"
    click CNT "https://github.com/dennis6p/adaptive-cards-py/blob/main/src/adaptive_cards/containers.py"
    click ACT "https://github.com/dennis6p/adaptive-cards-py/blob/main/src/adaptive_cards/actions.py"
    click INP "https://github.com/dennis6p/adaptive-cards-py/blob/main/src/adaptive_cards/inputs.py"
    click CTD "https://github.com/dennis6p/adaptive-cards-py/blob/main/src/adaptive_cards/card_types.py"
    click VAL "https://github.com/dennis6p/adaptive-cards-py/blob/main/src/adaptive_cards/validation.py"
    click SCH "https://github.com/dennis6p/adaptive-cards-py/tree/main/src/adaptive_cards/schemas"
    click TC "https://github.com/dennis6p/adaptive-cards-py/blob/main/src/adaptive_cards/client.py"
    click UT "https://github.com/dennis6p/adaptive-cards-py/blob/main/src/adaptive_cards/utils.py"

    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:2px;
    classDef composition fill:#ccf,stroke:#333,stroke-width:2px;
    classDef validation fill:#cfc,stroke:#333,stroke-width:2px;
    classDef schema fill:#fcf,stroke:#333,stroke-width:2px;
    classDef integration fill:#cff,stroke:#333,stroke-width:2px;
    classDef support fill:#ffc,stroke:#333,stroke-width:2px;
```
