# jpmorganchase/py-adapter architecture

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

- Interactive diagram: https://gitdiagram.com/jpmorganchase/py-adapter
- Repository: https://github.com/jpmorganchase/py-adapter

## Overview

##### Project Type and Purpose
- This is an **open-source Python library** (packaged on PyPI) whose purpose is **“round-trip serialization/deserialization of any Python object to/from any serialization format (Avro, JSON, CSV, etc.)”**.
- Core feature: a plugin architecture under `src/py_adapter/plugin/` that allows adding new formats without touching core logic.

##### File Structure
Top-level layout:
- `src/py_adapter/` – the library code
– `_schema.py` – internal schema handling
– `plugin/` – built-in adapters: `_avro.py`, `_json.py`, `_csv.py`
– `__init__.py`, `py.typed`
- `tests/` – pytest test suites and sample Avro schemas (`.avsc`)
- `docs/` – Sphinx documentation
- Configuration files: `pyproject.toml`, `tox.ini`, GitHub Actions workflows
- CI/CD & packaging under `.github/workflows/`

##### README
- Confirms Python packaging (`pip install py-adapter`)
- Emphasizes plugin extensibility (“any serialization format”)
- Points to developer workflow with Tox and pre-commit

##### Main Components
a. **Core Adapter Engine** (`py_adapter`)
b. **Plugin Interface / Registry** – the mechanism by which plugins register themselves with the core
c. **Built-in Plugins**
- Avro Adapter (`_avro.py`)
- JSON Adapter (`_json.py`)
- CSV Adapter (`_csv.py`)
d. **External Format Libraries**
- Apache Avro library (for schema parsing, binary encoding)
- Python `json` stdlib
- Python `csv` stdlib
e. **User Code** – Python objects being serialized/deserialized
g. **Documentation System** (Sphinx)

##### Relationships & Data Flows
- User passes a Python object to **Core Adapter Engine**.
- Core Engine invokes **Plugin Registry** to select target format plugin.
- Plugin calls into respective **External Format Library** to perform conversion to bytes/text.
- Deserialization flows in reverse order.
- Tests exercise the Core → Plugin → Library chain; docs generate from code and doc sources.

##### Architectural Patterns & Principles
- **Plugin Pattern**: loosely-coupled adapters, discoverable via a registry.
- **Separation of Concerns**: core orchestration vs. format-specific logic.
- **Single Responsibility**: each plugin handles one format only.
- **Open/Closed Principle**: new formats can be added without modifying core code.

- Annotations: point out critical files (e.g., `_schema.py` for schema introspection).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Code
    User["User Code\n(Python Objects)"]:::external

    %% Core Layer
    subgraph "Core Layer"
        direction TB
        Core["py_adapter\n(Core Engine)"]:::core
        Schema["_schema.py\n(Schema Handling)"]:::core
        Registry["plugin/__init__.py\n(Plugin Registry)"]:::core
    end

    %% Plugin Layer
    subgraph "Built-in Plugins"
        direction TB
        Avro["_avro.py\n(Avro Adapter)"]:::plugin
        JSON["_json.py\n(JSON Adapter)"]:::plugin
        CSV["_csv.py\n(CSV Adapter)"]:::plugin
    end

    %% External Libraries
    subgraph "External Format Libraries"
        direction TB
        AvroLib["Apache Avro\nLibrary"]:::external
        JSONLib["Python json\nstdlib"]:::external
        CSVLib["Python csv\nstdlib"]:::external
    end

    %% Tooling & Config
    subgraph "Tooling & Configuration"
        direction TB
        TypeStub["py.typed\n(Type Stub Marker)"]:::tool
        Tests["tests/\n(Test Harness)"]:::tool
        Docs["docs/\n(Documentation)"]:::tool
        CICD[".github/workflows/\n(CI/CD Workflows)"]:::tool
        Packaging["pyproject.toml\n(Packaging Config)"]:::tool
        Linting[".flake8\n.pre-commit-config.yaml\ntox.ini\n(Linting & Pre-commit)"]:::tool
    end

    %% Data Flows
    User -->|"serialize()"| Core
    Core -->|"uses"| Registry
    Registry --> Avro
    Registry --> JSON
    Registry --> CSV
    Avro -->|"encode/decode"| AvroLib
    JSON -->|"encode/decode"| JSONLib
    CSV -->|"encode/decode"| CSVLib
    Core -->|"introspects"| Schema
    Tests --> Core
    Docs --> Core
    CICD --> Core
    Packaging --> Core
    Linting --> Core
    TypeStub --> Core

    %% Click Events
    click Core "https://github.com/jpmorganchase/py-adapter/blob/main/src/py_adapter/__init__.py"
    click Schema "https://github.com/jpmorganchase/py-adapter/blob/main/src/py_adapter/_schema.py"
    click Registry "https://github.com/jpmorganchase/py-adapter/blob/main/src/py_adapter/plugin/__init__.py"
    click Avro "https://github.com/jpmorganchase/py-adapter/blob/main/src/py_adapter/plugin/_avro.py"
    click JSON "https://github.com/jpmorganchase/py-adapter/blob/main/src/py_adapter/plugin/_json.py"
    click CSV "https://github.com/jpmorganchase/py-adapter/blob/main/src/py_adapter/plugin/_csv.py"
    click TypeStub "https://github.com/jpmorganchase/py-adapter/blob/main/src/py_adapter/py.typed"
    click Tests "https://github.com/jpmorganchase/py-adapter/tree/main/tests/"
    click Docs "https://github.com/jpmorganchase/py-adapter/tree/main/docs/"
    click CICD "https://github.com/jpmorganchase/py-adapter/tree/main/.github/workflows/"
    click Packaging "https://github.com/jpmorganchase/py-adapter/blob/main/pyproject.toml"
    click Linting "https://github.com/jpmorganchase/py-adapter/blob/main/.flake8"

    %% Styles
    classDef core fill:#8dd3c7,stroke:#333,stroke-width:1px
    classDef plugin fill:#bebada,stroke:#333,stroke-width:1px
    classDef external fill:#fb8072,stroke:#333,stroke-width:1px
    classDef tool fill:#80b1d3,stroke:#333,stroke-width:1px
```
