Architecture

System Overview

┌─────────────────┐      ┌───────────────┐      ┌──────────────┐
│   Developer /   │      │   Registry    │      │   Routerd    │
│   CI Pipeline   │      │   (S3/R2)     │      │   (Runtime)  │
│   (DevKit CLI)  │      └───────┬───────┘      └──────▲───────┘
└────────┬────────┘              │                     │
         │                       │                     │
         │  1. Read schemas      │                     │
         │  2. Compose supergraph│                     │
         │  3. Validate & diff   │                     │
         │  4. Publish snapshot ─┼───▶ Store bundle    │
         │  5. Push bundle ──────┼─────────────────────┘
         │  6. Activate          │
         └───────────────────────┘
                    │
                    │  (if breaking changes)
                    ▼
         ┌──────────────────┐
         │  Platform API    │
         │  (Governance)    │
         │  - Proposals     │
         │  - Approvals     │
         │  - Audit trail   │
         └──────────────────┘

DevKit communicates with three backend systems:

---

Bundle Delivery

DevKit CLI                              Router
    │                                     │
    │  POST /control/v1/bundles           │
    │  Content-Type: application/gzip     │
    │  Body: bundle.tar.gz               │
    ├────────────────────────────────────▶│
    │                                     │  Extract & validate
    │                                     │  Parse supergraph.graphql
    │  POST /control/v1/activate/{id}     │  Read subgraphs.json
    ├────────────────────────────────────▶│
    │                                     │  Activate schema
    │         200 OK                      │  Hot-reload routing
    │◀────────────────────────────────────┤
    │                                     │

---

Multi-Protocol Routing

                        ┌──────────────────────────┐
     GraphQL Query      │     HyperRoute Router     │
    ─────────────▶      │                            │
                        │  supergraph.graphql        │
                        │  ├─ @rest directives       │
                        │  └─ @grpc directives       │
                        │                            │
                        │  subgraphs.json            │
                        │  ├─ type: "graphql"        │
                        │  ├─ type: "rest"           │
                        │  └─ type: "grpc"           │
                        └──────┬──────┬──────┬───────┘
                               │      │      │
                    ┌──────────┘      │      └──────────┐
                    ▼                 ▼                  ▼
             ┌────────────┐  ┌──────────────┐   ┌────────────┐
             │  GraphQL   │  │  REST/HTTP   │   │   gRPC     │
             │  POST      │  │  GET /users  │   │  GetProduct│
             │  /graphql  │  │  POST /users │   │  ListItems │
             └────────────┘  └──────────────┘   └────────────┘

---

Router Control API

Base URL: The router's control plane (e.g., http://localhost:4000).

Upload Bundle

POST {router_url}/control/v1/bundles
Content-Type: application/gzip
Body: <raw gzip binary>

Response (200):

{
  "bundle_id": "bundle-09692dfe-ae57-5581-b158-77404c59deab",
  "status": "uploaded"
}

Activate Bundle

POST {router_url}/control/v1/activate/{bundle_id}

Response (200):

{
  "bundle_id": "bundle-09692dfe-ae57-5581-b158-77404c59deab",
  "status": "activated"
}

List Bundles

GET {router_url}/control/v1/bundles

Response (200):

{
  "bundles": [
    {
      "bundle_id": "bundle-09692dfe-...",
      "snapshot_id": "09692dfe-ae57-...",
      "uploaded_at": "2026-02-20T07:51:26Z",
      "active": true
    }
  ],
  "active_bundle_id": "bundle-09692dfe-..."
}

Router Status

GET {router_url}/control/v1/status

Rollback

POST {router_url}/control/v1/rollback

Health Check

GET {router_url}/health

---

Platform API (Governance)

Base URL: https://platform.hyperroute.dev Authentication: Authorization: Bearer {HYPERROUTE_API_KEY}

Get Baseline Schema

GET {platform_url}/api/v1/schemas/{tenant_id}

Returns the current active schema versions for diff comparison.

Create Approval Request

POST {platform_url}/api/v1/approvals/{tenant_id}

Creates a proposal when breaking changes are detected. The response includes a review_url for the Platform UI.

Check Approval Status

GET {platform_url}/api/v1/approvals/{tenant_id}

Record Schema Version

POST {platform_url}/api/v1/schemas/{tenant_id}

Create Snapshot

POST {platform_url}/api/v1/schemas/{tenant_id}/snapshots

Activate Snapshot

POST {platform_url}/api/v1/schemas/{tenant_id}/activate

---

Registry Storage Layout

S3/R2 Key Structure

{prefix}/
├── subgraphs/
│   └── {name}/
│       └── {version}/
│           ├── schema.graphql
│           └── metadata.json
├── snapshots/
│   └── {snapshot_id}/
│       └── snapshot.json
├── bundles/
│   └── {snapshot_id}/
│       ├── bundle.tar.gz
│       └── manifest.json

Operations

---

Command → API Mapping