# i2y/pydantic-rpc architecture

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

- Interactive diagram: https://gitdiagram.com/i2y/pydantic-rpc
- Repository: https://github.com/i2y/pydantic-rpc

## Overview

##### Main Components
- Library Core: The heart of the project is found in the “src/pydantic_rpc” directory. This is where the main functionalities—such as automatic protobuf generation, runtime dynamic code generation, and service handling—reside (e.g. in core.py).
- API/Server Abstractions: The library supports several server models, including:
- Synchronous services via “Server”
- Asynchronous services via “AsyncIOServer”
- ASGI/WSGI integration applications (ASGIApp/WSGIApp)
- Connecpy support for Connect-RPC
- Protobuf Generation Mechanism: This component is responsible for creating .proto files on the fly based on Python method and type signatures. It drives integrations with external tools like grpcio-tools and CLI-based code generation.
- External Dependencies & Libraries: Highlight the use of Pydantic (for model definition/validation), gRPC (for transport), external packages like “pydantic_ai” (used in the examples for connecting to OpenAI-like models), and Connecpy (for Connect-RPC services).
- Example Applications and Tests: Both the “examples” and “tests” directories show how the library is intended to be used in practice. They are critical for illustrating various service patterns (gRPC, async streaming, multiple services, etc.) and thus should be referenced as usage samples that demonstrate how the core components are integrated.

##### Relationships and Interactions
- How the core module accepts Pydantic models (the “Message” classes) and method signatures to generate protobuf definitions on the fly.
- How external components (e.g., gRPC health, server reflection, streaming handlers) interact with the core module.

##### Architectural Patterns & Design Principles
- Dynamic/On-Demand Code Generation: Emphasize that instead of a static definition, the library generates .proto files and stubs at runtime unless the skip generation flag is set.
- Extensibility: The design allows for pluggable server types (synchronous, asynchronous, ASGI, WSGI, ConnectRPC) and custom interceptors (as shown in the multiple services example), indicating a high degree of flexibility.

##### Technologies & Libraries
- Pydantic – used for model definitions and type validation.
- grpcio and grpcio-tools – used to support gRPC communications.
- Connecpy – for Connect-RPC support.
- Standard Python libraries: asyncio (for async operations) and others noted in the examples.
- OpenAI integrations (via pydantic_ai and AsyncOpenAI) as showcased in the examples, to illustrate how external services might be integrated.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input
    U["User Service Definitions (Pydantic Models & Methods)"]:::input

    %% Core Layer
    subgraph "Core Layer"
        A["PydanticRPC Core"]:::core
        B["Dynamic Protobuf Generator"]:::core
    end

    %% Server Adapters
    subgraph "Server Adapters"
        S1["Synchronous Server"]:::server
        S2["Asynchronous Server (AsyncIOServer)"]:::server
        S3["ASGI/WSGI App"]:::server
        S4["ConnecpyASGIApp"]:::server
    end

    %% External Dependencies
    subgraph "External Dependencies"
        DEP1["Pydantic"]:::external
        DEP2["gRPC & grpcio-tools"]:::external
        DEP3["Connecpy"]:::external
        DEP4["OpenAI Integrations (pydantic_ai)"]:::external
    end

    %% Usage and Testing
    subgraph "Usage & Testing"
        E["Example Applications"]:::example
        T["Test Suite"]:::example
    end

    %% Connections
    U -->|"runtime_generation"| B
    B -->|"service_definition"| A

    A -->|"delegates_request"| S1
    A -->|"delegates_request"| S2
    A -->|"delegates_request"| S3
    A -->|"delegates_request"| S4

    DEP1 ---|"validation"| B
    DEP2 ---|"transport"| A
    DEP3 ---|"ConnectRPC_support"| S4
    DEP4 ---|"external_integration"| A

    E -->|"demonstrates_usage"| A
    T -->|"tests_services"| A

    %% Styling Classes
    classDef core fill:#FFEDB8,stroke:#C17C00,stroke-width:2px;
    classDef server fill:#D3E5FF,stroke:#2B67A3,stroke-width:2px;
    classDef external fill:#D4F8D4,stroke:#2E8B57,stroke-width:2px;
    classDef example fill:#FFD4D4,stroke:#A83232,stroke-width:2px;
    classDef input fill:#E0E0E0,stroke:#555,stroke-width:2px;

    %% Click Events
    click A "https://github.com/i2y/pydantic-rpc/blob/main/src/pydantic_rpc/core.py"
    click B "https://github.com/i2y/pydantic-rpc/blob/main/src/pydantic_rpc/core.py"
    click S1 "https://github.com/i2y/pydantic-rpc/blob/main/examples/greeting.py"
    click S2 "https://github.com/i2y/pydantic-rpc/blob/main/examples/asyncio_greeting.py"
    click S3 "https://github.com/i2y/pydantic-rpc/blob/main/examples/greeting_asgi.py"
    click S4 "https://github.com/i2y/pydantic-rpc/blob/main/examples/greeting_connecpy.py"
    click E "https://github.com/i2y/pydantic-rpc/tree/main/examples"
    click T "https://github.com/i2y/pydantic-rpc/tree/main/tests"
```
