Skip to content

Architecture

Detailed architecture documentation for the Virtufin API gateway.

System Overview

Virtufin API is a gRPC-based API gateway that provides:

  1. Service Discovery - Dynamic discovery via gRPC reflection
  2. Method Invocation - Transparent forwarding to backend services
  3. Event Streaming - gRPC streaming and Dapr pub/sub
  4. State Management - Dapr state store integration
  5. Multi-Protocol Support - native gRPC and gRPC-Web (HTTP serves health checks)

System Architecture

flowchart TB
    subgraph Clients["Clients"]
        CSharp[C# Client]
        Python[Python Client]
        Browser[Browser<br/>gRPC-Web]
    end

    subgraph ProtocolLayer[Protocol Layer]
        Shared[Dual Ports<br/>HTTP:5001 / gRPC:5002]
    end

    subgraph ApplicationLayer["Application Layer"]
        Kestrel[Kestrel Server]
        GatewaySvc[GatewayService]
        PubsubSvc[PubsubService]
        StateSvc[StateService]
    end

    subgraph Infrastructure["Infrastructure"]
        DaprClient[Dapr Client]
        ChannelPool[gRPC Channel Pool]
    end

    subgraph Backend["Backend Services"]
        WM[WorkManager<br/>:5002]
        RT[WorkManager Runtime<br/>workers, e.g. WebSocketFeed]
    end

    subgraph Dapr["Dapr Sidecar"]
        State[Dapr State]
        PubSub[Dapr PubSub]
    end

    Clients --> ProtocolLayer
    ProtocolLayer --> ApplicationLayer
    ApplicationLayer --> Infrastructure
    Infrastructure --> Backend
    Infrastructure --> Dapr

Component Architecture

flowchart LR
    subgraph Clients
        C[C#]
        P[Python]
        B[Browser]
    end

    subgraph Gateway["Virtufin.Api"]
        G[gRPC Gateway]
        E[Event System]
        S[State Service]
    end

    subgraph Backends
        WM[WorkManager]
        RT[WorkManager Runtime<br/>workers, e.g. WebSocketFeed]
    end

    C --> G
    P --> G
    B --> G
    G --> WM
    WM --> RT
    RT -- publish, state, lease --> G
    G <--> S
    S <--> State
    E <--> PubSub

Component Details

Component Architecture

flowchart TB
    subgraph Clients[Clients]
        CSharp[C# Client]
        Python[Python Client]
        Browser[Browser gRPC-Web]
    end

    subgraph ProtocolLayer[Protocol Layer]
        Shared[Dual Ports<br/>HTTP:5001 / gRPC:5002]
    end

    subgraph ApplicationLayer[Application Layer]
        Kestrel[Kestrel Server]
        GatewaySvc[GatewayService gRPC]
        ConfigSvc[ConfigService gRPC]
        GrpcReflSvc[GrpcReflectionService gRPC]
        PubsubSvc[PubsubService]
        StateSvc[StateService]
    end

    subgraph Infrastructure[Infrastructure]
        ChannelPool[GrpcChannelPool]
        DaprClient[DaprClient]
        ConfigLoader[ServicesConfigurationLoader]
    end

    subgraph Backend[Backend Services]
        WM[WorkManager :5002]
        RT[WorkManager Runtime<br/>workers, e.g. WebSocketFeed]
    end

    subgraph Dapr[Dapr Sidecar]
        State[Dapr State]
        PubSub[Dapr PubSub]
    end

    Clients --> ProtocolLayer
    ProtocolLayer --> ApplicationLayer
    ApplicationLayer --> Infrastructure
    Infrastructure --> Backend
    Infrastructure --> Dapr

System Architecture

flowchart TB
    subgraph Clients[Clients]
        CSharp[C# Client]
        Python[Python Client]
        Browser[Browser gRPC-Web]
    end

    subgraph ProtocolLayer[Protocol Layer]
        Shared[Dual Ports<br/>HTTP:5001 / gRPC:5002]
    end

    subgraph ApplicationLayer[Application Layer]
        Kestrel[Kestrel Server]
        GatewaySvc[GatewayService gRPC]
        ConfigSvc[ConfigService gRPC]
        GrpcReflSvc[GrpcReflectionService gRPC]
        PubsubSvc[PubsubService]
        StateSvc[StateService]
    end

    subgraph Infrastructure[Infrastructure]
        ChannelPool[GrpcChannelPool]
        DaprClient[DaprClient]
        ConfigLoader[ServicesConfigurationLoader]
    end

    subgraph Backend[Backend Services]
        WM[WorkManager :5002]
        RT[WorkManager Runtime<br/>workers, e.g. WebSocketFeed]
    end

    subgraph Dapr[Dapr Sidecar]
        State[Dapr State]
        PubSub[Dapr PubSub]
    end

    Clients --> ProtocolLayer
    ProtocolLayer --> ApplicationLayer
    ApplicationLayer --> Infrastructure
    Infrastructure --> Backend
    Infrastructure --> Dapr

gRPC Invocation

sequenceDiagram
    participant Client as C# Client
    participant Kestrel as Kestrel
    participant Gateway as Gateway Service
    participant Pool as GrpcChannel Pool
    participant Backend as Backend Service :5002

    Client->>Kestrel: gRPC
    Kestrel->>Gateway: InvokeRequest
    Gateway->>Pool: GetChannel(service)
    Pool->>Backend: gRPC Call
    Backend-->>Pool: Response
    Pool-->>Gateway: InvokeResponse
    Gateway-->>Kestrel: InvokeResponse
    Kestrel-->>Client: gRPC Response

Event Streaming (Dapr → gRPC)

flowchart LR
    Dapr[Dapr Sidecar] --> PubSub[PubSub Event]
    PubSub --> Registry[TopicDaprSubscriptionRegistry]
    Registry -->|every subscriber| GrpcClient[gRPC Client Subscribe]

Configuration Architecture

flowchart TB
    ConfigFile[services.json] --> Loader[ServicesConfigurationLoader]
    Loader --> ServicesConfig[ServicesConfiguration]
    ServicesConfig --> ChannelPool[GrpcChannelPool]
    ServicesConfig --> Reflection[GrpcReflectionService]
    ServicesConfig --> PubsubSvc[PubSubService]
    ServicesConfig --> State[StateService]
    ServicesConfig --> Config[ConfigService]

GrpcChannelPool

Location: Services/GrpcChannelPool.cs

The GrpcChannelPool maintains a thread-safe pool of gRPC channels, one per backend service.

Key Features: - Lazy channel creation (created on first access) - Channel reuse across invocations - LRU eviction when channel limit is reached - Automatic cleanup on application shutdown - Configuration-driven service endpoints

Flow:

sequenceDiagram
    participant Client
    participant Gateway as GatewayService
    participant Pool as GrpcChannelPool
    participant Cache as Channel Cache
    participant Backend as Backend Service

    Client->>Gateway: Invoke(service, method, data)
    Gateway->>Pool: GetChannel(serviceName)
    Pool->>Cache: Check cached?
    Cache-->>Pool: Not found
    Pool->>Pool: Create new GrpcChannel
    Pool->>Cache: Store in cache
    Cache-->>Pool: Channel
    Pool-->>Gateway: Channel
    Gateway->>Backend: gRPC Call
    Backend-->>Gateway: Response
    Gateway-->>Client: InvokeResponse

Configuration (services.json):

services:
  - name: workmanager
    host: localhost
    port: 5002
    protocol: grpc


GrpcReflectionService

Location: Services/GrpcReflectionService.cs

Provides dynamic service discovery and method invocation using gRPC reflection.

Key Features: - Fetches service descriptors from backend services via reflection - Caches descriptors per service for performance - Uses TypeRegistry for robust JSON↔Protobuf conversion - Handles well-known type descriptors

Class Structure:

Class Purpose
GrpcReflectionService Public API, manages cache instances
ServiceDescriptorCache Per-service cache, loads and parses descriptors
ServiceMethodInfo Method metadata (name, input/output types, streaming)
MethodSchema Schema for request/response types
FieldSchema Individual field definitions
GrpcCallResult Invocation result wrapper

Discovery Flow:

sequenceDiagram
    participant Client as GatewayClient
    participant Cache as ServiceDescriptorCache
    participant Reflection as gRPC Reflection
    participant Backend as Backend Service

    Client->>Cache: GetMethodsAsync(serviceName)
    Cache->>Cache: GetOrCreateCache()
    Cache->>Reflection: ServerReflectionInfo()
    Reflection->>Backend: ServerReflectionInfo()
    Backend-->>Reflection: FileDescriptorProtos
    Reflection-->>Cache: Descriptors
    Cache->>Cache: Parse and Index
    Cache-->>Client: List<MethodInfo>

Invocation Flow:

sequenceDiagram
    participant Client
    participant Gateway as GatewayService
    participant Cache as ServiceDescriptorCache
    participant Channel as gRPC Channel
    participant Backend as Backend Service

    Client->>Gateway: Invoke(request)
    Gateway->>Cache: GetOrCreateCache(service)
    Cache-->>Gateway: Cached descriptors
    Gateway->>Gateway: Create protobuf from JSON
    Gateway->>Channel: AsyncUnaryCall()
    Channel->>Backend: gRPC Request
    Backend-->>Channel: gRPC Response
    Channel-->>Gateway: Response bytes
    Gateway->>Gateway: Parse to JSON
    Gateway-->>Client: GrpcCallResult

Invocation Flow:

flowchart TD
    A[ExecuteCallAsync<br/>service, method, json] --> B[GetOrCreateCache<br/>EnsureLoadedAsync]
    B --> C[Find method by name]
    C --> D[Create protobuf message<br/>from JSON]
    D --> E[Create generic<br/>Method byte array byte array]
    E --> F[channel.CreateCallInvoker<br/>AsyncUnaryCall]
    F --> G[Parse response bytes<br/>to JSON]
    G --> H[Return GrpcCallResult]

GatewayService

Location: Services/GatewayService.cs

The main gRPC service implementing the Gateway protocol.

gRPC Methods:

Method Type Description
Invoke Unary Invoke a method on a backend service
ListServices Unary List all registered services
ListMethods Unary List methods for a service
Subscribe Server Streaming Subscribe to events

Invoke Flow:

flowchart TD
    A[Client calls<br/>Gateway.Invoke<br/>InvokeRequest] --> B[Extract request headers<br/>as metadata]
    B --> C[Call ReflectionService<br/>ExecuteCallAsync]
    C --> D[Map result to<br/>InvokeResponse]
    D --> E[Return to client]

PubsubService

Location: Services/PubsubService.cs

Implements the Pubsub gRPC service: PublishEvent, PublishEvents, Subscribe, ListTopics and ChangePublicationFence. Cancelling Subscribe unsubscribes. Subscriptions are filtered by topic only — there is no scope hierarchy, no service filter, and no event-type filter. A subscriber that needs finer granularity inspects cloudevent.type itself.

Subscribe creates one bounded Channel (1024 events) per call, shared across all topics named in that call, and multiplexes every topic's events into the single response stream. A consumer that falls further behind than the bound is reaped by the health sweeper.

Response headers are flushed before any event is written. Request-reply clients depend on this to know the subscription is live before they publish — without it, a client waits for metadata that cannot arrive until it publishes, and won't publish until metadata arrives.

TopicDaprSubscriptionRegistry

Location: Services/TopicDaprSubscriptionRegistry.cs

The in-process fan-out broker. Holds one shared Dapr streaming subscription per topic per process and the set of subscribers (each Subscribe call's channel) on it; the set is the reference count. Dapr pub/sub is competing-consumer: a subscription per caller would make daprd load-balance each event across callers instead of delivering it to all of them, so callers share one and the registry writes every message to every subscriber.

The subscription opens with the first subscriber and closes with the last. It runs on its own token, so the subscriber that opened it may leave first. If it ends on its own (the sidecar stream faulted), every subscriber's stream ends with Unavailable and the next Subscribe opens a fresh one.

sequenceDiagram
    participant Client
    participant Pubsub as PubsubService
    participant Registry as TopicDaprSubscriptionRegistry
    participant Dapr as Dapr Sidecar

    Client->>Pubsub: Subscribe(topics)
    Pubsub->>Registry: AcquireAsync(topic, channel)
    alt first subscriber for this topic
        Registry->>Dapr: SubscribeAsync(pubsub, topic, handler)
    else topic already subscribed
        Registry->>Registry: add subscriber
    end
    Pubsub->>Client: flush response headers

    Dapr->>Registry: TopicMessage
    Registry->>Client: SubscribeResponse (to every subscriber)

    Client->>Pubsub: cancel call
    Pubsub->>Registry: dispose handle (remove subscriber)
    Registry->>Dapr: dispose subscription when the last subscriber leaves

SubscriptionHealthSweeperHostedService

Location: Services/SubscriptionHealthSweeperHostedService.cs

Every minute, writes a heartbeat to each subscriber's channel and evicts the subscribers whose channel stays full or closed; the last one leaving closes the Dapr subscription.

DaprAppCallbackService

Location: Services/DaprAppCallbackService.cs

Receives Dapr Scheduler job callbacks and publishes an empty CloudEvent to the job's target_topic. Bound on both Dapr's alpha and stable AppCallback routes — DaprStableAppCallbackMethodProvider adds the stable one, which the .NET SDK does not generate. Because subscriptions are created programmatically rather than declared, the ListTopicSubscriptions callback deliberately returns an empty list.

Data Flow Diagrams

gRPC Invocation

sequenceDiagram
    participant Client as C# Client
    participant Kestrel as Kestrel
    participant Gateway as Gateway Service
    participant Pool as GrpcChannel Pool
    participant Backend as Backend Service :5002

    Client->>Kestrel: gRPC
    Kestrel->>Gateway: InvokeRequest
    Gateway->>Pool: GetChannel(service)
    Pool->>Backend: gRPC Call
    Backend-->>Pool: Response
    Pool-->>Gateway: InvokeResponse
    Gateway-->>Kestrel: InvokeResponse
    Kestrel-->>Client: gRPC Response

Event Streaming (Dapr → gRPC)

flowchart LR
    Dapr[Dapr Sidecar] -->|Pub/Sub| Registry[TopicDaprSubscriptionRegistry]
    Registry -->|every subscriber| GrpcClient[gRPC Client Subscribe]

Configuration Architecture

flowchart TB
    ConfigFile[services.json] --> Loader[ServicesConfigurationLoader]
    Loader --> ServicesConfig[ServicesConfiguration]
    ServicesConfig --> ChannelPool[GrpcChannelPool]
    ServicesConfig --> Gateway[GatewayService]
    ServicesConfig --> Reflection[AggregatedReflectionService]
    ServicesConfig --> State["StateService<br/>(store name only)"]
    ServicesConfig --> Config[ConfigService]

Health Checks

Check Name Healthy when On /ready
DaprHealthCheck dapr Dapr sidecar is reachable yes
GrpcChannelPoolHealthCheck grpc-channel-pool Channel pool has channels for the configured services yes
GatewayCircuitBreakerHealthCheck dapr-circuit-breaker The gateway circuit breaker is not open no
ApiAuthHealthCheck api-auth API-key auth is configured as expected yes

/health and /healthz are the liveness probe: they run no check and answer as long as the process does, because no failing dependency is fixed by restarting the gateway (a restart drops every subscription). /ready is the readiness probe and runs the checks marked above. The circuit breaker is left out: it opens when a backend fails, and an open breaker already fails calls at once with a clear error; taking the gateway out of its Service on top of that turned a backend that was slow to start into "connection refused" for every caller (2026-11-14).

A gRPC health service is also mapped at grpc.health.v1.Health and reports all four checks (the TUI watches it); the API-key interceptor exempts it from authentication.