# sanketdhole/torana-java architecture

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

- Interactive diagram: https://gitdiagram.com/sanketdhole/torana-java
- Repository: https://github.com/sanketdhole/torana-java

## Overview

Torana is a reactive enterprise AI gateway: it normalizes client protocols into a shared request, applies tracing and security controls, selects a route, runs a configured pipeline, invokes backend connectors, and returns a protocol-encoded response. The graph preserves the README’s major protocol, policy, resilience, and connector capabilities. Runtime flow is based on the documented lifecycle; sampled source confirms pipeline orchestration and gRPC dispatch, but most filter wiring and unsampled integrations are not shown.

Main entry points: [`torana-pipeline/src/main/java/com/phaselume/torana/pipeline/executor/PipelineExecutor.java`](https://github.com/sanketdhole/torana-java/blob/main/torana-pipeline/src/main/java/com/phaselume/torana/pipeline/executor/PipelineExecutor.java) (Pipeline executor), [`torana-pipeline/src/main/java/com/phaselume/torana/pipeline/step`](https://github.com/sanketdhole/torana-java/tree/main/torana-pipeline/src/main/java/com/phaselume/torana/pipeline/step) (Pipeline steps), [`torana-observability/src/main/java/com/phaselume/torana/observability/tracing/RequestTracingFilter.java`](https://github.com/sanketdhole/torana-java/blob/main/torana-observability/src/main/java/com/phaselume/torana/observability/tracing/RequestTracingFilter.java) (Request tracing), [`torana-protocol-mcp/src/main/java/com/phaselume/torana/protocol/mcp/McpProtocolAdapter.java`](https://github.com/sanketdhole/torana-java/blob/main/torana-protocol-mcp/src/main/java/com/phaselume/torana/protocol/mcp/McpProtocolAdapter.java) (Protocol adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Protocol ingress"]
  node_protocols["Protocol adapters"]
  node_grpc["gRPC service"]
  node_rest["REST adapter"]
  node_ws["WebSocket adapter"]
end

subgraph group_controls["Request controls"]
  node_tracing["Request tracing"]
  node_authn["Authentication"]
  node_routing["Route matching"]
  node_rate["Rate limiting"]
  node_redis[("Redis")]
  node_authz["OPA authorization"]
  node_opa["OPA service"]
end

subgraph group_execution["Pipeline execution"]
  node_pipeline["Pipeline executor"]
  node_registry[("Pipeline registry")]
  node_steps["Pipeline steps"]
end

subgraph group_backends["Backend integrations"]
  node_connectors["Backend connectors"]
  node_llm["LiteLLM connector"]
end

subgraph group_operations["Resilience and audit"]
  node_resilience["Resilience decorators"]
  node_audit["Audit sinks"]
end

node_client(("Client / agent"))
node_systems["Enterprise services"]

node_client -->|"sends protocol request"| node_protocols
node_client -->|"calls gRPC"| node_grpc
node_client -->|"sends HTTP request"| node_rest
node_client -->|"opens session"| node_ws
node_grpc -->|"dispatches request"| node_pipeline
node_protocols -->|"normalizes request"| node_tracing
node_rest -->|"normalizes request"| node_tracing
node_ws -->|"normalizes request"| node_tracing
node_tracing -->|"propagates context"| node_authn
node_authn -->|"authenticates request"| node_routing
node_routing -->|"selects route"| node_rate
node_rate -->|"checks limits"| node_redis
node_rate -->|"passes request"| node_authz
node_authz -->|"evaluates policy"| node_opa
node_authz -->|"authorizes request"| node_pipeline
node_pipeline -->|"loads pipeline"| node_registry
node_pipeline -->|"executes steps"| node_steps
node_steps -->|"invokes backend"| node_connectors
node_steps -->|"calls model"| node_llm
node_connectors -->|"forwards operations"| node_systems
node_llm -->|"sends completions"| node_systems
node_pipeline -->|"applies fallback"| node_resilience
node_steps -->|"records events"| node_audit
node_protocols -->|"encodes response"| node_client
node_grpc -->|"streams response"| node_client
node_rest -->|"returns response"| node_client
node_ws -->|"streams response"| node_client

click node_protocols "https://github.com/sanketdhole/torana-java/blob/main/torana-protocol-mcp/src/main/java/com/phaselume/torana/protocol/mcp/McpProtocolAdapter.java"
click node_grpc "https://github.com/sanketdhole/torana-java/blob/main/torana-protocol-grpc/src/main/java/com/phaselume/torana/protocol/grpc/server/AgentGatewayGrpcService.java"
click node_rest "https://github.com/sanketdhole/torana-java/blob/main/torana-protocol-rest/src/main/java/com/phaselume/torana/protocol/rest/RestProtocolAdapter.java"
click node_ws "https://github.com/sanketdhole/torana-java/blob/main/torana-protocol-websocket/src/main/java/com/phaselume/torana/protocol/websocket/WebSocketProtocolAdapter.java"
click node_tracing "https://github.com/sanketdhole/torana-java/blob/main/torana-observability/src/main/java/com/phaselume/torana/observability/tracing/RequestTracingFilter.java"
click node_authn "https://github.com/sanketdhole/torana-java/blob/main/torana-security-authn/src/main/java/com/phaselume/torana/security/authn/filter/ToranaAuthenticationWebFilter.java"
click node_routing "https://github.com/sanketdhole/torana-java/blob/main/torana-routing/src/main/java/com/phaselume/torana/routing/filter/RoutingWebFilter.java"
click node_rate "https://github.com/sanketdhole/torana-java/blob/main/torana-ratelimit-redis/src/main/java/com/phaselume/torana/ratelimit/filter/RateLimitWebFilter.java"
click node_authz "https://github.com/sanketdhole/torana-java/blob/main/torana-security-authz-opa/src/main/java/com/phaselume/torana/security/authz/opa/engine/OpaAuthorizationEngine.java"
click node_pipeline "https://github.com/sanketdhole/torana-java/blob/main/torana-pipeline/src/main/java/com/phaselume/torana/pipeline/executor/PipelineExecutor.java"
click node_registry "https://github.com/sanketdhole/torana-java/blob/main/torana-pipeline/src/main/java/com/phaselume/torana/pipeline/registry/PipelineRegistry.java"
click node_steps "https://github.com/sanketdhole/torana-java/tree/main/torana-pipeline/src/main/java/com/phaselume/torana/pipeline/step"
click node_connectors "https://github.com/sanketdhole/torana-java/blob/main/torana-connector-http/src/main/java/com/phaselume/torana/connector/http/HttpBackendConnector.java"
click node_llm "https://github.com/sanketdhole/torana-java/blob/main/torana-connector-litellm/src/main/java/com/phaselume/torana/connector/litellm/LiteLLMConnector.java"
click node_resilience "https://github.com/sanketdhole/torana-java/blob/main/torana-resilience/src/main/java/com/phaselume/torana/resilience/decorator/Resilience4jResilienceDecorator.java"
click node_audit "https://github.com/sanketdhole/torana-java/blob/main/torana-observability/src/main/java/com/phaselume/torana/observability/audit/sink/CompositeAuditSink.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_protocols,node_grpc,node_rest,node_ws,node_client toneBlue
class node_tracing,node_authn,node_routing,node_rate,node_redis,node_authz,node_opa toneAmber
class node_pipeline,node_registry,node_steps toneMint
class node_connectors,node_llm toneRose
class node_resilience,node_audit,node_systems toneIndigo
```

## Components

### Protocol ingress

- [Protocol adapters](https://github.com/sanketdhole/torana-java/blob/main/torana-protocol-mcp/src/main/java/com/phaselume/torana/protocol/mcp/McpProtocolAdapter.java): `torana-protocol-mcp/src/main/java/com/phaselume/torana/protocol/mcp/McpProtocolAdapter.java`
- [gRPC service](https://github.com/sanketdhole/torana-java/blob/main/torana-protocol-grpc/src/main/java/com/phaselume/torana/protocol/grpc/server/AgentGatewayGrpcService.java): `torana-protocol-grpc/src/main/java/com/phaselume/torana/protocol/grpc/server/AgentGatewayGrpcService.java`
- [REST adapter](https://github.com/sanketdhole/torana-java/blob/main/torana-protocol-rest/src/main/java/com/phaselume/torana/protocol/rest/RestProtocolAdapter.java): `torana-protocol-rest/src/main/java/com/phaselume/torana/protocol/rest/RestProtocolAdapter.java`
- [WebSocket adapter](https://github.com/sanketdhole/torana-java/blob/main/torana-protocol-websocket/src/main/java/com/phaselume/torana/protocol/websocket/WebSocketProtocolAdapter.java): `torana-protocol-websocket/src/main/java/com/phaselume/torana/protocol/websocket/WebSocketProtocolAdapter.java`

### Request controls

- [Request tracing](https://github.com/sanketdhole/torana-java/blob/main/torana-observability/src/main/java/com/phaselume/torana/observability/tracing/RequestTracingFilter.java): `torana-observability/src/main/java/com/phaselume/torana/observability/tracing/RequestTracingFilter.java`
- [Authentication](https://github.com/sanketdhole/torana-java/blob/main/torana-security-authn/src/main/java/com/phaselume/torana/security/authn/filter/ToranaAuthenticationWebFilter.java): `torana-security-authn/src/main/java/com/phaselume/torana/security/authn/filter/ToranaAuthenticationWebFilter.java`
- [Route matching](https://github.com/sanketdhole/torana-java/blob/main/torana-routing/src/main/java/com/phaselume/torana/routing/filter/RoutingWebFilter.java): `torana-routing/src/main/java/com/phaselume/torana/routing/filter/RoutingWebFilter.java`
- [Rate limiting](https://github.com/sanketdhole/torana-java/blob/main/torana-ratelimit-redis/src/main/java/com/phaselume/torana/ratelimit/filter/RateLimitWebFilter.java): `torana-ratelimit-redis/src/main/java/com/phaselume/torana/ratelimit/filter/RateLimitWebFilter.java`
- **Redis**
- [OPA authorization](https://github.com/sanketdhole/torana-java/blob/main/torana-security-authz-opa/src/main/java/com/phaselume/torana/security/authz/opa/engine/OpaAuthorizationEngine.java): `torana-security-authz-opa/src/main/java/com/phaselume/torana/security/authz/opa/engine/OpaAuthorizationEngine.java`
- **OPA service**

### Pipeline execution

- [Pipeline executor](https://github.com/sanketdhole/torana-java/blob/main/torana-pipeline/src/main/java/com/phaselume/torana/pipeline/executor/PipelineExecutor.java): `torana-pipeline/src/main/java/com/phaselume/torana/pipeline/executor/PipelineExecutor.java`
- [Pipeline registry](https://github.com/sanketdhole/torana-java/blob/main/torana-pipeline/src/main/java/com/phaselume/torana/pipeline/registry/PipelineRegistry.java): `torana-pipeline/src/main/java/com/phaselume/torana/pipeline/registry/PipelineRegistry.java`
- [Pipeline steps](https://github.com/sanketdhole/torana-java/tree/main/torana-pipeline/src/main/java/com/phaselume/torana/pipeline/step): `torana-pipeline/src/main/java/com/phaselume/torana/pipeline/step`

### Backend integrations

- [Backend connectors](https://github.com/sanketdhole/torana-java/blob/main/torana-connector-http/src/main/java/com/phaselume/torana/connector/http/HttpBackendConnector.java): `torana-connector-http/src/main/java/com/phaselume/torana/connector/http/HttpBackendConnector.java`
- [LiteLLM connector](https://github.com/sanketdhole/torana-java/blob/main/torana-connector-litellm/src/main/java/com/phaselume/torana/connector/litellm/LiteLLMConnector.java): `torana-connector-litellm/src/main/java/com/phaselume/torana/connector/litellm/LiteLLMConnector.java`

### Resilience and audit

- [Resilience decorators](https://github.com/sanketdhole/torana-java/blob/main/torana-resilience/src/main/java/com/phaselume/torana/resilience/decorator/Resilience4jResilienceDecorator.java): `torana-resilience/src/main/java/com/phaselume/torana/resilience/decorator/Resilience4jResilienceDecorator.java`
- [Audit sinks](https://github.com/sanketdhole/torana-java/blob/main/torana-observability/src/main/java/com/phaselume/torana/observability/audit/sink/CompositeAuditSink.java): `torana-observability/src/main/java/com/phaselume/torana/observability/audit/sink/CompositeAuditSink.java`

### Other components

- **Client / agent**
- **Enterprise services**

## Connections

- Client / agent → Protocol adapters: sends protocol request
- Client / agent → gRPC service: calls gRPC
- Client / agent → REST adapter: sends HTTP request
- Client / agent → WebSocket adapter: opens session
- gRPC service → Pipeline executor: dispatches request
- Protocol adapters → Request tracing: normalizes request
- REST adapter → Request tracing: normalizes request
- WebSocket adapter → Request tracing: normalizes request
- Request tracing → Authentication: propagates context
- Authentication → Route matching: authenticates request
- Route matching → Rate limiting: selects route
- Rate limiting → Redis: checks limits
- Rate limiting → OPA authorization: passes request
- OPA authorization → OPA service: evaluates policy
- OPA authorization → Pipeline executor: authorizes request
- Pipeline executor → Pipeline registry: loads pipeline
- Pipeline executor → Pipeline steps: executes steps
- Pipeline steps → Backend connectors: invokes backend
- Pipeline steps → LiteLLM connector: calls model
- Backend connectors → Enterprise services: forwards operations
- LiteLLM connector → Enterprise services: sends completions
- Pipeline executor → Resilience decorators: applies fallback
- Pipeline steps → Audit sinks: records events
- Protocol adapters → Client / agent: encodes response
- gRPC service → Client / agent: streams response
- REST adapter → Client / agent: returns response
- WebSocket adapter → Client / agent: streams response