{"slug":"developers/SERVICE_TOPOLOGY","title":"Service Topology — Who Handles What","section":"developers","sectionLabel":"Developers","status":"unclassified","type":"document","path":"developers/SERVICE_TOPOLOGY.mdx","bytes":15712,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nThe Gateway is the single public entry point. It routes requests to downstream\nservices via private Cloudflare Workers service bindings.\n\nExternal apps should begin with the public catalogue:\n`GET /api/v1/platform`, `/packages`, `/services`, `/endpoints`, or\n`/openapi.json`. Those endpoints expose stable contracts only; this topology is\nan implementation reference and does not grant direct access to a service.\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                         CLIENT                                  │\n│            (Browser, Mobile, Third-party App)                   │\n└─────────────────────────────────────────────────────────────────┘\n                              │\n                              ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                      GATEWAY (BFF)                              │\n│              gateway.dev.integratewise.ai                       │\n├─────────────────────────────────────────────────────────────────┤\n│  • JWT Validation        • Tenant Resolution                    │\n│  • Rate Limiting         • CORS Policy                          │\n│  • Request Routing       • Circuit Breaker                      │\n└─────────────────────────────────────────────────────────────────┘\n                              │\n        ┌─────────────────────┼─────────────────────┐\n        │                     │                     │\n        ▼                     ▼                     ▼\n┌───────────────┐   ┌───────────────┐   ┌───────────────┐\n│  INTERNAL     │   │   DOWNSTREAM  │   │   DOWNSTREAM  │\n│  HANDLERS     │   │   SERVICES    │   │   SERVICES    │\n└───────────────┘   └───────────────┘   └───────────────┘\n```\n\n---\n\n## Service Mapping\n\n### Internal Handlers (Gateway Process)\n\nThese are handled directly by the Gateway Worker:\n\n| Target                 | Routes                                                                                                                                                                                           | Handler                        |\n| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |\n| `INTERNAL_AUTH`        | `/api/v1/auth/*`                                                                                                                                                                                 | `routeAuthRequest()`           |\n| `INTERNAL_ADMIN`       | `/admin/*`                                                                                                                                                                                       | `routeAdminRequest()`          |\n| `INTERNAL_SUPPORT`     | `/api/v1/public/*`, `/api/v1/support/*`                                                                                                                                                          | `routeSupportRequest()`        |\n| `INTERNAL_BILLING`     | `/api/v1/billing/*`                                                                                                                                                                              | `routeBillingRequest()`        |\n| `INTERNAL_PROJECTIONS` | `/api/v1/workspace/projection/*`, `/api/v1/workspace/entities`                                                                                                                                   | `routeProjectionRequest()`     |\n| `INTERNAL_TENANTS`     | `/api/v1/tenants/*`                                                                                                                                                                              | `routeTenantsRequest()`        |\n| `INTERNAL_SPINE`       | `/api/v1/workspace/initialize-spine`, `/api/v1/workspace/connectors`, `/api/v1/workspace/spine-config`, `/api/v1/workspace/dashboard`, `/api/v1/workspace/profile`, `/api/v1/workspace/progress` | `routeWorkspaceSpineRequest()` |\n\n---\n\n### Spine (Adaptive Spine)\n\nThe Spine is the connected operating model. Neon Fortress owns canonical\nworkspace truth; D1/KV hold bounded operational and projection state.\n\n| Component                         | Location                                     | Description                                                           |\n| --------------------------------- | -------------------------------------------- | --------------------------------------------------------------------- |\n| **Canonical schema and entities** | Neon Fortress through Governed Spine Writers | Tenant entity truth, relationships, versions and promoted outcomes    |\n| **Operational schema/cache**      | D1/KV                                        | Active context, idempotency, projection snapshots and runtime indexes |\n| **Evidence bytes**                | R2                                           | Raw payloads, files, attachments and immutable evidence               |\n| **Projection Engine**             | `packages/projection-engine`                 | Composes SharedWorkbench from Spine                                   |\n\n**Spine Endpoints (Internal to Gateway):**\n\n| Method | Endpoint                                   | Description              |\n| ------ | ------------------------------------------ | ------------------------ |\n| `POST` | `/api/v1/workspace/initialize-spine`       | Initialize Spine schema  |\n| `GET`  | `/api/v1/workspace/connectors`             | Get connected connectors |\n| `GET`  | `/api/v1/workspace/spine-config`           | Get Spine configuration  |\n| `GET`  | `/api/v1/workspace/dashboard`              | Get dashboard data       |\n| `GET`  | `/api/v1/workspace/profile`                | Get workspace profile    |\n| `GET`  | `/api/v1/workspace/progress`               | Get sync progress        |\n| `GET`  | `/api/v1/workspace/projection/:department` | Compose SharedWorkbench  |\n| `GET`  | `/api/v1/workspace/entities`               | Query entities           |\n| `GET`  | `/api/v1/workspace/readiness`              | Get readiness scores     |\n\n**Spine Data Flow:**\n\n```\nExternal Systems → Connector → Loader/Pipeline → Operational Spine\n→ governed promotion → Neon Fortress → operational/projection rehydration\n                                                     │\n                                                     ▼\n                                              Projection Engine\n                                                     │\n                                                     ▼\n                                              SharedWorkbench\n                                                     │\n                                                     ▼\n                                                  Gateway\n                                                     │\n                                                     ▼\n                                                  Client\n```\n\n---\n\n### Downstream Services (Service Bindings)\n\nThese are separate Cloudflare Workers connected via service bindings:\n\n| Binding           | Service                         | Handles              | Endpoints                                                                |\n| ----------------- | ------------------------------- | -------------------- | ------------------------------------------------------------------------ |\n| `CONNECTOR`       | `integratewise-connector`       | Connector operations | `/api/v1/workspace/connectors/*`, `/api/v1/workspace/register-connector` |\n| `CONNECTOR_SYNC`  | `integratewise-connector-sync`  | Sync operations      | `/api/v1/workspace/connectors/nango-session`                             |\n| `PIPELINE`        | `integratewise-pipeline`        | Data processing      | `/api/v1/pipeline/*`, `/api/v1/loader/*`                                 |\n| `INTELLIGENCE`    | `integratewise-intelligence`    | AI/ML operations     | `/api/v1/capabilities/*`, `/api/v1/brainstorm`, `/api/v1/cognitive/*`    |\n| `KNOWLEDGE`       | `integratewise-knowledge`       | Knowledge base       | `/api/v1/knowledge/*`                                                    |\n| `BFF`             | `integratewise-bff`             | Backend for Frontend | `/api/v1/workbench/*`                                                    |\n| `AGENT_RUNTIME`   | `iw-agent-runtime`              | Agent operations     | `/api/v1/agent/*`, `/api/v1/twin/*`                                      |\n| `L2`              | `integratewise-l2`              | L2 API layer         | `/api/v1/l2/*`                                                           |\n| `WEBHOOK_INGRESS` | `integratewise-webhook-ingress` | Webhook ingestion    | `/webhooks/*`                                                            |\n| `HUB_CONTROLLER`  | `hub-controller-api`            | Hub operations       | `/api/v1/hub/*`                                                          |\n| `ADMIN`           | `integratewise-admin`           | Admin operations     | `/admin/*`                                                               |\n| `BILLING`         | `integratewise-billing`         | Billing operations   | `/api/v1/billing/*`                                                      |\n| `TENANTS`         | `integratewise-tenants`         | Tenant management    | `/api/v1/tenants/*`                                                      |\n\n---\n\n## Request Flow Examples\n\n### 1. Get Workbench\n\n```\nClient → Gateway → INTERNAL_PROJECTIONS → Projection Engine → Response\n```\n\n```\nGET /api/v1/workspace/projection/SALES\n  ↓\nGateway validates JWT, resolves tenant\n  ↓\nrouteProjectionRequest() handles internally\n  ↓\nProjectionEngine.compose() assembles SharedWorkbench\n  ↓\nReturns SharedWorkbench JSON\n```\n\n---\n\n### 2. List Connectors\n\n```\nClient → Gateway → CONNECTOR Service → Response\n```\n\n```\nGET /api/v1/workspace/connectors/catalog\n  ↓\nGateway validates JWT, resolves tenant\n  ↓\nrouteConnectorRequest() forwards to CONNECTOR binding\n  ↓\nintegratewise-connector Worker handles request\n  ↓\nReturns connector catalog\n```\n\n---\n\n### 3. Execute Capability\n\n```\nClient → Gateway → INTELLIGENCE Service → Response\n```\n\n```\nPOST /api/v1/capabilities/resolve\n  ↓\nGateway validates JWT, resolves tenant\n  ↓\nrouteIntelligenceRequest() forwards to INTELLIGENCE binding\n  ↓\nintegratewise-intelligence Worker executes capability\n  ↓\nReturns capability result\n```\n\n---\n\n### 4. OAuth Flow\n\n```\nClient → Gateway → CONNECTOR_SYNC Service → Nango → Response\n```\n\n```\nPOST /api/v1/integrations/salesforce/authorize\n  ↓\nGateway validates JWT, resolves tenant\n  ↓\nrouteConnectorRequest() forwards to CONNECTOR binding\n  ↓\nintegratewise-connector starts OAuth via Nango\n  ↓\nReturns auth_url for redirect\n```\n\n---\n\n### 5. Webhook Ingress\n\n```\nExternal Service → Gateway → WEBHOOK_INGRESS Service → Pipeline\n```\n\n```\nPOST /webhooks/stripe\n  ↓\nGateway verifies webhook signature\n  ↓\nrouteWebhookIngressRequest() forwards to WEBHOOK_INGRESS binding\n  ↓\nintegratewise-webhook-ingress processes event\n  ↓\nTriggers pipeline for data sync\n```\n\n---\n\n## Service Health\n\nCheck all services via readiness probe:\n\n```bash\ncurl https://gateway.dev.integratewise.ai/health/ready\n```\n\n**Response:**\n\n```json\n{\n  \"status\": \"ready\",\n  \"services\": [\n    { \"name\": \"connector\", \"healthy\": true, \"latency_ms\": 45 },\n    { \"name\": \"pipeline\", \"healthy\": true, \"latency_ms\": 32 },\n    { \"name\": \"intelligence\", \"healthy\": true, \"latency_ms\": 67 },\n    { \"name\": \"knowledge\", \"healthy\": true, \"latency_ms\": 28 },\n    { \"name\": \"bff\", \"healthy\": true, \"latency_ms\": 41 },\n    { \"name\": \"agent-runtime\", \"healthy\": true, \"latency_ms\": 55 },\n    { \"name\": \"webhook-ingress\", \"healthy\": true, \"latency_ms\": 22 }\n  ]\n}\n```\n\n---\n\n## Environment Variables (Gateway)\n\n```typescript\nexport interface Env {\n  // D1 Database\n  DB: D1Database;\n\n  // Service Bindings\n  CONNECTOR: Fetcher;\n  CONNECTOR_SYNC?: Fetcher;\n  PIPELINE: Fetcher;\n  INTELLIGENCE: Fetcher;\n  KNOWLEDGE: Fetcher;\n  BFF: Fetcher;\n  L2: Fetcher;\n  AGENT_RUNTIME: Fetcher;\n  WEBHOOK_INGRESS?: Fetcher;\n  HUB_CONTROLLER: Fetcher;\n  ADMIN: Fetcher;\n  BILLING: Fetcher;\n  TENANTS: Fetcher;\n\n  // KV Namespaces\n  RATE_LIMITS: KVNamespace;\n  SESSIONS: KVNamespace;\n  CONNECTOR_STATUS?: KVNamespace;\n  SIGNAL_CACHE?: KVNamespace;\n  METRICS?: KVNamespace;\n  OAUTH_STATE_KV?: KVNamespace;\n\n  // Secrets\n  NANGO_SECRET_KEY?: string;\n  DESCOPE_MANAGEMENT_KEY?: string;\n  HUBSPOT_WEBHOOK_SECRET?: string;\n  SALESFORCE_WEBHOOK_SECRET?: string;\n  GITHUB_WEBHOOK_SECRET?: string;\n  STRIPE_WEBHOOK_SECRET?: string;\n}\n```\n\n---\n\n## Summary\n\n| Endpoint Category    | Handler                                                     |\n| -------------------- | ----------------------------------------------------------- |\n| Auth                 | Gateway (internal)                                          |\n| **Spine reads**      | **Gateway → Spine/Projection → Neon + bounded D1/KV cache** |\n| Workspace/Projection | Gateway (internal) → Projection Engine                      |\n| Connectors           | CONNECTOR service                                           |\n| Integrations         | CONNECTOR service                                           |\n| Sync                 | CONNECTOR_SYNC service                                      |\n| Capabilities         | INTELLIGENCE service                                        |\n| Brainstorm/Cognitive | INTELLIGENCE service                                        |\n| Workbench            | BFF service                                                 |\n| Twin/Proposals       | AGENT_RUNTIME service                                       |\n| Webhooks             | WEBHOOK_INGRESS service                                     |\n| Pipeline/Loader      | PIPELINE service                                            |\n| Knowledge            | KNOWLEDGE service                                           |\n| Admin                | ADMIN service                                               |\n| Billing              | BILLING service                                             |\n\n---\n\n**Gateway:** `https://gateway.dev.integratewise.ai`  \n**All requests go through Gateway** — no direct service access.  \n**Spine is the canonical connected model.** Neon owns its authoritative data;\nD1/KV are bounded operational structures. Product clients access both only\nthrough Gateway semantic contracts.\n"}