# budecosystem/bud-microframe architecture

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

- Interactive diagram: https://gitdiagram.com/budecosystem/bud-microframe
- Repository: https://github.com/budecosystem/bud-microframe

## Overview

##### Project type and purpose
- This is a Python micro-framework library (“budmicroframe”) that helps microservices interact with Dapr crypto components.
- Its purpose is to wrap Dapr’s local crypto component (and other Dapr building blocks) behind a simple API (e.g., DaprServiceCrypto) so service authors can encrypt/decrypt data easily.

##### File structure
- Top-level modules:
- budmicroframe/commons – reusable helpers (config, logging, validators, resiliency, async utilities)
- budmicroframe/shared – high-level Dapr wrappers (dapr_service, dapr_workflow, http_client, psql_service)
- budmicroframe/internal – internal routes and main entrypoint (meta_routes.py, main.py)
- Configuration exists in commons/config.py, and type hints in py.typed.
- setup.py / pyproject.toml define packaging; requirements.txt lists dependencies.

##### README
- Describes steps to: generate keys → create a Dapr component YAML → configure .env → call DaprServiceCrypto.encrypt/decrypt.
- Emphasizes integration with Dapr sidecar and local filesystem for key storage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    App["Microservice Application"]:::external

    %% Library Modules
    subgraph "Commons Utilities"
        direction TB
        Config["config.py"]:::lib
        Logging["logging.py"]:::lib
        Validators["validators.py"]:::lib
        Resiliency["resiliency.py"]:::lib
        AsyncUtils["async_utils.py"]:::lib
        Dependencies["dependencies.py"]:::lib
        Singleton["singleton.py"]:::lib
    end

    subgraph "Shared - Dapr Wrappers"
        direction TB
        DaprServiceCrypto["dapr_service.py"]:::lib
        DaprWorkflow["dapr_workflow.py"]:::lib
        HttpClient["http_client.py"]:::lib
        PsqlService["psql_service.py"]:::lib
    end

    subgraph "Internal Endpoints"
        direction TB
        MetaRoutes["meta_routes.py"]:::lib
        MainEntrypoint["main.py"]:::lib
    end

    subgraph "Configuration & Packaging"
        direction TB
        Typing["py.typed"]:::config
        Setup["setup.py"]:::config
        Pyproject["pyproject.toml"]:::config
        Requirements["requirements.txt"]:::config
    end

    %% Dapr & Components
    Sidecar["Dapr Sidecar"]:::runtime
    CryptoComp["local-crypto Component"]:::component
    FileSystem["File System: crypto-keys/"]:::datastore
    Env[".env Configuration"]:::config
    CryptoYAML["crypto Component YAML"]:::config

    %% Flows
    App -->|"import & call"| DaprServiceCrypto
    DaprServiceCrypto -->|"gRPC/HTTP invoke"| Sidecar
    Sidecar -->|"crypto.invoke"| CryptoComp
    CryptoComp -->|"read/write keys"| FileSystem
    CryptoComp -->|"encrypted/decrypted data"| Sidecar
    Sidecar -->|"response"| DaprServiceCrypto
    DaprServiceCrypto -->|"return result"| App

    Env -->|".env"| DaprServiceCrypto
    CryptoYAML -->|"component config"| Sidecar

    %% Styles
    classDef lib fill:#e0ffe0,stroke:#2d7f2d,color:#1a3b1a;
    classDef external fill:#e0f0ff,stroke:#1f5f9f,color:#123f6f,stroke-dasharray: 2 2;
    classDef runtime fill:#d0e8ff,stroke:#1a5f9f,color:#103f6f,stroke-dasharray: 5 5;
    classDef component fill:#cfefff,stroke:#1a7faf,color:#085f7f;
    classDef datastore fill:#f0f0f0,stroke:#666666,color:#333333;
    classDef config fill:#fff8dc,stroke:#c7a600,color:#8b6508;

    %% Click Events
    click Config "https://github.com/budecosystem/bud-microframe/blob/main/budmicroframe/commons/config.py"
    click Logging "https://github.com/budecosystem/bud-microframe/blob/main/budmicroframe/commons/logging.py"
    click Validators "https://github.com/budecosystem/bud-microframe/blob/main/budmicroframe/commons/validators.py"
    click Resiliency "https://github.com/budecosystem/bud-microframe/blob/main/budmicroframe/commons/resiliency.py"
    click AsyncUtils "https://github.com/budecosystem/bud-microframe/blob/main/budmicroframe/commons/async_utils.py"
    click Dependencies "https://github.com/budecosystem/bud-microframe/blob/main/budmicroframe/commons/dependencies.py"
    click Singleton "https://github.com/budecosystem/bud-microframe/blob/main/budmicroframe/commons/singleton.py"
    click DaprServiceCrypto "https://github.com/budecosystem/bud-microframe/blob/main/budmicroframe/shared/dapr_service.py"
    click DaprWorkflow "https://github.com/budecosystem/bud-microframe/blob/main/budmicroframe/shared/dapr_workflow.py"
    click HttpClient "https://github.com/budecosystem/bud-microframe/blob/main/budmicroframe/shared/http_client.py"
    click PsqlService "https://github.com/budecosystem/bud-microframe/blob/main/budmicroframe/shared/psql_service.py"
    click MetaRoutes "https://github.com/budecosystem/bud-microframe/blob/main/budmicroframe/internal/meta_routes.py"
    click MainEntrypoint "https://github.com/budecosystem/bud-microframe/blob/main/budmicroframe/main.py"
    click Typing "https://github.com/budecosystem/bud-microframe/blob/main/budmicroframe/py.typed"
    click Setup "https://github.com/budecosystem/bud-microframe/blob/main/setup.py"
    click Pyproject "https://github.com/budecosystem/bud-microframe/blob/main/pyproject.toml"
    click Requirements "https://github.com/budecosystem/bud-microframe/blob/main/requirements.txt"
```
