# manojuio/grpc-edge-proxy architecture

> Architecture diagram of the GitHub repository manojuio/grpc-edge-proxy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/manojuio/grpc-edge-proxy
- Repository: https://github.com/manojuio/grpc-edge-proxy

## Overview

1. **What this repo is**
- `grpc-edge-proxy` is a Node.js edge gateway that translates incoming HTTP/JSON requests into outbound gRPC calls, then translates gRPC responses back to HTTP/JSON.
- The architecture is centered on protocol translation and backend request routing, not on business logic or storage.

2. **Main runtime boundary**
- The public entry point is the HTTP ingress layer in `src/ingress-http/server.js`.
- That layer is the only client-facing boundary; everything after it is internal translation and gRPC egress.

3. **Application composition**
- `src/app.js` is the bootstrap/wiring point.
- It initializes schema loading, request dispatching, and the HTTP server, so the app is assembled from three internal subsystems: ingress, translation core, and gRPC egress.

4. **Ingress subsystem: HTTP to internal request handling**
- `src/ingress-http/server.js` is the HTTP server.
- Its role is to accept requests, parse JSON bodies and request metadata, and hand the request off to the translation layer.
- Based on the README, this layer is implemented with Express and listens on port 8000.

5. **Translation core: schema awareness and serialization**
- `src/translation-core/schema-loader.js` loads `.proto` files from `protos/` and builds the service/method schema registry.
- `src/translation-core/serializer.js` performs the format conversion between HTTP-friendly JSON and protobuf binary data.
- This is the main protocol boundary in the system: the proxy depends on schema metadata to know which gRPC service, method, and message types to use.

6. **Egress subsystem: routing to gRPC backends**
- `src/egress-grpc/dispatcher.js` chooses the target gRPC method and performs the invocation logic.
- `src/egress-grpc/client-pool.js` manages reusable gRPC client connections so the proxy avoids creating a new backend connection per request.
- Together these form the outbound call path from translated request to backend gRPC service.

7. **Protocol definitions**
- `protos/user.proto` is the canonical example schema in the repo.
- The proxy is schema-driven: service and message definitions in `.proto` files determine how HTTP requests map to gRPC RPCs and payload shapes.

8. **End-to-end data flow**
- Request enters via HTTP.
- The ingress layer passes request details into schema lookup and serialization.
- The dispatcher uses the schema and pooled client to call the matching gRPC method.
- The backend returns protobuf data, which is decoded back to JSON.
- The HTTP server returns the translated response to the client.

9. **Testing and local backend simulation**
- `mock-server.js` is a separate mock gRPC backend used for development and testing.
- It sits on the other side of the egress boundary and lets you validate routing, serialization, and client pooling without a real production backend.

10. **Infrastructure and dependency choices that shape the architecture**
- The implementation is Node.js/CommonJS.
- Express handles ingress HTTP traffic.
- `@grpc/grpc-js`, `@grpc/proto-loader`, and `protobufjs` support dynamic proto loading and gRPC/protobuf interoperability.
- There is no database, message queue, or persistent state layer in the repo; the proxy is stateless aside from in-memory client pooling and loaded schema metadata.

Main entry points: [`src/egress-grpc/dispatcher.js`](https://github.com/manojuio/grpc-edge-proxy/blob/main/src/egress-grpc/dispatcher.js) (Dispatcher), [`src/ingress-http/server.js`](https://github.com/manojuio/grpc-edge-proxy/blob/main/src/ingress-http/server.js) (HTTP server), [`src/translation-core/schema-loader.js`](https://github.com/manojuio/grpc-edge-proxy/blob/main/src/translation-core/schema-loader.js) (Schema loader), [`src/app.js`](https://github.com/manojuio/grpc-edge-proxy/blob/main/src/app.js) (App bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_ingress["Ingress"]
  node_node_http_server["HTTP server<br/>express ingress<br/>[server.js]"]
end

subgraph group_grp_core["Translation Core"]
  node_node_app["App bootstrap<br/>entrypoint<br/>[app.js]"]
  node_node_schema_loader["Schema loader<br/>proto registry<br/>[schema-loader.js]"]
  node_node_serializer["Serializer<br/>codec<br/>[serializer.js]"]
end

subgraph group_grp_egress["gRPC Egress"]
  node_node_dispatcher["Dispatcher<br/>rpc router<br/>[dispatcher.js]"]
  node_node_client_pool[("Client pool<br/>grpc clients<br/>[client-pool.js]")]
end

subgraph group_grp_protocols["Protocols"]
  node_node_user_proto["user proto<br/>service schema<br/>[user.proto]"]
end

subgraph group_grp_dev["Dev Backend"]
  node_node_mock_server["Mock server<br/>test backend<br/>[mock-server.js]"]
end

node_node_app -->|"starts"| node_node_http_server
node_node_app -->|"loads"| node_node_schema_loader
node_node_app -->|"wires"| node_node_dispatcher
node_node_http_server -->|"uses"| node_node_schema_loader
node_node_http_server -->|"parses"| node_node_serializer
node_node_http_server -->|"hands off"| node_node_dispatcher
node_node_schema_loader -->|"reads"| node_node_user_proto
node_node_dispatcher -->|"resolves"| node_node_schema_loader
node_node_dispatcher -->|"encodes/decodes"| node_node_serializer
node_node_dispatcher -->|"borrows"| node_node_client_pool
node_node_dispatcher -.->|"invokes"| node_node_mock_server
node_node_client_pool -.->|"connects to"| node_node_mock_server
node_node_serializer -->|"returns"| node_node_http_server

click node_node_app "https://github.com/manojuio/grpc-edge-proxy/blob/main/src/app.js"
click node_node_http_server "https://github.com/manojuio/grpc-edge-proxy/blob/main/src/ingress-http/server.js"
click node_node_schema_loader "https://github.com/manojuio/grpc-edge-proxy/blob/main/src/translation-core/schema-loader.js"
click node_node_serializer "https://github.com/manojuio/grpc-edge-proxy/blob/main/src/translation-core/serializer.js"
click node_node_dispatcher "https://github.com/manojuio/grpc-edge-proxy/blob/main/src/egress-grpc/dispatcher.js"
click node_node_client_pool "https://github.com/manojuio/grpc-edge-proxy/blob/main/src/egress-grpc/client-pool.js"
click node_node_mock_server "https://github.com/manojuio/grpc-edge-proxy/blob/main/mock-server.js"
click node_node_user_proto "https://github.com/manojuio/grpc-edge-proxy/blob/main/protos/user.proto"

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_node_http_server toneBlue
class node_node_app,node_node_schema_loader,node_node_serializer toneAmber
class node_node_dispatcher,node_node_client_pool toneMint
class node_node_user_proto toneRose
class node_node_mock_server toneIndigo
```

## Components

### Ingress

HTTP boundary that accepts client requests and hands them to the proxy pipeline

- [HTTP server](https://github.com/manojuio/grpc-edge-proxy/blob/main/src/ingress-http/server.js): express ingress · Accepts JSON HTTP requests and forwards them into the proxy flow · `src/ingress-http/server.js`

### Translation Core

Schema loading and payload conversion for HTTP-to-gRPC translation

- [App bootstrap](https://github.com/manojuio/grpc-edge-proxy/blob/main/src/app.js): entrypoint · Wires ingress, schema loading, and dispatch into one runtime · `src/app.js`
- [Schema loader](https://github.com/manojuio/grpc-edge-proxy/blob/main/src/translation-core/schema-loader.js): proto registry · Loads .proto files and builds service/method metadata · `src/translation-core/schema-loader.js`
- [Serializer](https://github.com/manojuio/grpc-edge-proxy/blob/main/src/translation-core/serializer.js): codec · Converts between JSON payloads and protobuf messages · `src/translation-core/serializer.js`

### gRPC Egress

Backend routing and reusable client management for outbound RPCs

- [Dispatcher](https://github.com/manojuio/grpc-edge-proxy/blob/main/src/egress-grpc/dispatcher.js): rpc router · Selects the target gRPC method and drives invocation · `src/egress-grpc/dispatcher.js`
- [Client pool](https://github.com/manojuio/grpc-edge-proxy/blob/main/src/egress-grpc/client-pool.js): grpc clients · Reuses backend gRPC connections across requests · `src/egress-grpc/client-pool.js`

### Protocols

Proto definitions that drive schema-aware request mapping

- [user proto](https://github.com/manojuio/grpc-edge-proxy/blob/main/protos/user.proto): service schema · Example protocol definition that drives request-to-RPC mapping · `protos/user.proto`

### Dev Backend

Mock gRPC server for local validation

- [Mock server](https://github.com/manojuio/grpc-edge-proxy/blob/main/mock-server.js): test backend · Local gRPC backend used to exercise translation and routing · `mock-server.js`

## Connections

- App bootstrap → HTTP server: starts · Bootstraps the client-facing HTTP boundary
- App bootstrap → Schema loader: loads · Initializes schema metadata at startup
- App bootstrap → Dispatcher: wires · Connects request translation to outbound routing
- HTTP server → Schema loader: uses · Looks up schema details for inbound requests
- HTTP server → Serializer: parses · Turns HTTP JSON bodies into internal message payloads
- HTTP server → Dispatcher: hands off · Forwards request context into the translation pipeline
- Schema loader → user proto: reads · Builds registry data from proto definitions
- Dispatcher → Schema loader: resolves · Finds the target service, method, and message types
- Dispatcher → Serializer: encodes/decodes · Converts request and response payloads across the protocol boundary
- Dispatcher → Client pool: borrows · Acquires reusable backend clients for invocation
- Dispatcher → Mock server: invokes · Routes calls to a gRPC backend during local development
- Client pool → Mock server: connects to · Maintains backend connections for outbound RPCs
- Serializer → HTTP server: returns · Feeds translated response data back to the HTTP layer
