Constellation API

⚙️

Constellation API

The central integration hub. Every request — HTTP, CLI, or MCP — enters this single FastAPI service, passes through the middleware stack, and returns a normalized response. All routes, CLI commands, and MCP tools are auto-generated from @service_method decorators at startup.

---

Module Map

Integrations

github

jira

slack

google (gmail / calendar / chat)

microsoft365 (mail / calendar)

confluence

notion

stripe

sap (successfactors / scim)

moloni

teamtailor

twilio

whatsapp

glassdoor

websearch

Each: adapter.py · service.py · routes.py · oauth.py

Platform

analytics

DuckDB DORA metrics

documents

Upload, chunk, embed

graphrag

Hybrid retrieval

mcp

Tool registry + executor

knowledge_graph

Sagittarius bridge

digest

Async digest jobs

graph

Memory & context API

jobs

Async sync job polling

Core

generator

http_generator.py, cli_generator.py, decorator.py, registry.py

middleware

auth, cache, metrics, output_format, rate_limit, webhook_auth

auth

JWT / API key, OAuth OIDC, external auth

admin

Admin routes

health

Liveness + readiness

db

PostgreSQL pool (WhatsApp store)

oauth

LLM OAuth flow

Shared

schemas/

Pydantic models (request / response)

utils/

Logger, response helpers, JSON utils, decorators, graph embeddings

Entry point

main.py

---

What & Why

Constellation API is a multi-tenant FastAPI service that acts as the single integration gateway for the entire Octopus platform. It receives requests from three entry points — the HTTP API, the Constellation CLI, and the MCP interface — runs them through a five-stage middleware stack, and dispatches to the right service class.

The generator pattern is the core architectural innovation. When a developer adds a new integration, they write a service class with @service_method decorators. At startup, core/generator/http_generator.py reads the registry and automatically builds:

• FastAPI APIRouter instances with the correct path, method, and schema
• CLI subcommands (via cli_generator.py)
• MCP tool descriptions registered in the tool registry

No hand-written route files. No CLI argument parsers. No MCP tool manifests. One decorator → three entry points.

---

Middleware Stack

Every inbound request passes through five middleware layers before reaching any handler. The diagram below shows the order of execution (outer → inner) and the cache-hit short-circuit:

Request

→

CORS

Origin check preflight

→

Auth

JWT / API Key validation

→

Cache

Redis L2 lookup

→

Metrics

Prometheus counters

→

OutputFormat

json / text / agent

→

Handler

Service method

→

Response

Cache HIT

⤷ returns cached response directly, bypasses Metrics → OutputFormat → Handler

Middleware registration order in main.py (FastAPI processes in reverse add order, so last-added runs first):

Add order	Middleware	Runs
1st	CustomCORSMiddleware	Outermost — every request
2nd	MetricsMiddleware	After CORS
3rd	APIKeyAuthMiddleware	After Metrics
4th	WebhookAuthMiddleware	After Auth (webhook paths only)
5th	RateLimitMiddleware	After Auth (tenant_id available)
6th	CacheMiddleware	After Rate Limit
7th	OutputFormatMiddleware	Innermost before handler
8th	StripPrefixMiddleware	ALB /constellation prefix stripping

---

Startup Sequence

main.py executes the following steps every time the process starts. Steps 1–5 complete synchronously before the server begins accepting connections. Steps 6–7 run in a background task so /health/live returns 200 immediately for ALB health checks.

1

Load config

app/config.py imported first — patches huggingface_hub, reads env vars into Settings

2

Import service modules

`import app.integrations.*.service` triggers @service_method registration into service_registry

3

build_routers(service_registry)

http_generator.py iterates registry → builds one APIRouter per service → mounted on app

4

Register static routers

health, admin, mcp, analytics, documents, graph, oauth (google/jira/slack/github/notion/sap/…)

5

Setup middleware stack

CORS → Metrics → APIKeyAuth → WebhookAuth → RateLimit → Cache → OutputFormat → StripPrefix

6

Lifespan — sync startup (blocking)

MCP tool registry reload · PostgreSQL pool init · sync job cleanup loop start · ALB /health/live now returns 200

7

Lifespan — heavy startup (background task)

DuckDB cache clear · Redis connect + cache clear + cache warming · embedding model preload · Sagittarius bridge connect + vector index verify · MCP semantic search index init

---

Key Files Reference

File	Role
apps/constellation/app/main.py	FastAPI app, lifespan, middleware setup, router registration
apps/constellation/app/core/generator/http_generator.py	Reads service_registry → builds APIRouter instances for all @service_method decorated methods
apps/constellation/app/core/generator/decorator.py	Defines @service_method decorator and ServiceMethodMeta dataclass
apps/constellation/app/core/generator/registry.py	Global service_registry dict; populated at import time
apps/constellation/app/core/middleware/	auth.py, cache.py, metrics.py, output_format.py, rate_limit.py, webhook_auth.py
apps/constellation/app/integrations/	20 + service directories; each has adapter.py, service.py, routes.py, oauth.py
apps/constellation/app/shared/schemas/	Pydantic models shared across services
apps/constellation/app/shared/utils/	Logger, response helpers, JSON utils, graph embedding helpers