# grpc/grpc-dart architecture

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

- Interactive diagram: https://gitdiagram.com/grpc/grpc-dart
- Repository: https://github.com/grpc/grpc-dart

## Overview

##### Project type and purpose
- This is an open-source Dart library implementing gRPC (remote procedure calls over HTTP/2).
- It provides both client-side and server-side APIs, plus transport adapters for Dart native, Flutter, and grpc-web.

##### File structure
- Top-level directories:
- lib/       → the published library code (split into client, server, shared, auth, generated protos).
- example/   → sample apps (helloworld, grpc-web, googleapis, etc.) demonstrating usage.
- interop/   → interop tests against other gRPC implementations.
- test/      → unit and integration tests for client, server, shared components.
- tool/      → helper scripts (code-generation, test runners).
- .github/   → CI/workflow definitions.
- Within lib/src: clear separation of concerns:
- client/        gRPC client API (Channel, Call, Interceptor, transports).
- server/        gRPC server API (Server, Handler, Service, Keepalive).
- shared/        codecs, streams, status, message framing, timeouts.
- auth/          authentication helpers (RSA, IO).
- generated/     compiled .proto → .pb.dart files.
- protos/        source .proto definitions shipped for downstream code gen.

##### README for additional insights
- Confirms support for Dart native and Flutter, plus grpc-web.
- Directs to examples demonstrating quick-start and advanced use.
- Mentions HTTP/2, mobile-first design, and integration with protoc code generation.

##### Be detailed but focused
- Every major folder as a component or subcomponent.
- Don’t obscure the big picture: show client ↔ server over HTTP/2, with shared core and extension points clearly delineated.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Client["Client Library"]:::client
        APIExportsClient["Top-level API Export\n(lib/grpc.dart)"]:::client
        InterceptorC["Client Interceptor Infrastructure"]:::client
        subgraph "Transport Adapters"
            direction TB
            HTTP2["HTTP/2 Transport"]:::client
            XHR["XHR Transport"]:::client
            WS["WebStreams Transport"]:::client
            CORS["CORS Support"]:::client
        end
    end

    %% Shared Core
    subgraph "Shared Core & Auth"
        direction TB
        Shared["Shared Core\n(codecs, framing,\ntimeouts)"]:::shared
        Auth["Authentication Module"]:::shared
        ProtosGen["Generated Protos"]:::shared
        ProtosSrc["Protobuf Definitions"]:::shared
    end

    %% Server Layer
    subgraph "Server Layer"
        direction TB
        Server["Server Library"]:::server
        APIExportsServer["Top-level API Export\n(service_api.dart)"]:::server
        InterceptorS["Server Interceptor Infrastructure"]:::server
    end

    %% External
    External["External gRPC Service"]:::external

    %% Dependencies and Data Flow
    Client -->|uses| APIExportsClient
    Client -->|depends on| Shared
    Client -->|plugs into| InterceptorC
    InterceptorC -->|auth & logging| Auth
    InterceptorC -->|selects at runtime| HTTP2
    InterceptorC -->|selects at runtime| XHR
    InterceptorC -->|selects at runtime| WS
    InterceptorC -->|supports| CORS
    HTTP2 -->|sends HTTP/2 RPC| External
    XHR -->|sends gRPC-Web RPC| External
    WS -->|sends gRPC-Web RPC| External

    Server -->|depends on| Shared
    Server -->|plugs into| InterceptorS
    InterceptorS -->|auth & logging| Auth
    Server -->|exposes RPC over HTTP/2| External

    %% Code Generation Workflow
    ProtosSrc -.->|.proto files| ProtosGen
    ProtosGen -->|provides stubs to| Client
    ProtosGen -->|provides stubs to| Server

    %% Click Events
    click Client "https://github.com/grpc/grpc-dart/tree/master/lib/src/client"
    click Server "https://github.com/grpc/grpc-dart/tree/master/lib/src/server"
    click Shared "https://github.com/grpc/grpc-dart/tree/master/lib/src/shared"
    click Auth "https://github.com/grpc/grpc-dart/tree/master/lib/src/auth"
    click HTTP2 "https://github.com/grpc/grpc-dart/blob/master/lib/src/client/transport/http2_transport.dart"
    click XHR "https://github.com/grpc/grpc-dart/blob/master/lib/src/client/transport/xhr_transport.dart"
    click WS "https://github.com/grpc/grpc-dart/blob/master/lib/src/client/transport/web_streams.dart"
    click CORS "https://github.com/grpc/grpc-dart/blob/master/lib/src/client/transport/cors.dart"
    click ProtosGen "https://github.com/grpc/grpc-dart/tree/master/lib/src/generated"
    click ProtosSrc "https://github.com/grpc/grpc-dart/tree/master/lib/src/protos"
    click APIExportsClient "https://github.com/grpc/grpc-dart/blob/master/lib/grpc.dart"
    click APIExportsServer "https://github.com/grpc/grpc-dart/blob/master/lib/service_api.dart"
    click InterceptorC "https://github.com/grpc/grpc-dart/blob/master/lib/src/client/interceptor.dart"
    click InterceptorS "https://github.com/grpc/grpc-dart/blob/master/lib/src/server/interceptor.dart"

    %% Styles
    classDef client fill:#cce5ff,stroke:#0066cc,color:#003366
    classDef server fill:#d4edda,stroke:#28a745,color:#155724
    classDef shared fill:#e2e3e5,stroke:#6c757d,color:#383d41
    classDef external fill:#fff3cd,stroke:#ffc107,color:#856404
```
