Architecture Overview
Octopus — System Context
What is Octopus and Why Does it Exist?
Modern engineering teams need data from a dozen or more SaaS products simultaneously — issue trackers, version control, communication tools, HR systems, billing platforms. Connecting each application directly to each SaaS means reimplementing OAuth flows, token refresh logic, error handling, and response normalization over and over.
Octopus is a unified integration layer. Instead of every application connecting to 20+ APIs with different auth schemes and SDKs, they connect to Octopus once. Octopus handles:
- Authentication — OAuth2 authorization code flows, token refresh, and per-tenant credential storage via JWT claims
- Normalization — uniform response shapes across heterogeneous SaaS APIs
- Exposure — a single deployment serves HTTP, CLI, and MCP interfaces generated from one source of truth
- Multi-tenancy — every request carries a JWT with
tenant_id+user_email; a single Octopus deployment serves many teams in complete isolation
The result: application developers write one HTTP call (or one CLI command, or one MCP tool invocation) and get back normalized data from any supported service, fully authenticated, with caching and analytics built in.
Three-Workspace Architecture
Octopus is a uv monorepo with three workspace packages that have clear dependency boundaries:
orbit-sagittarius package
FalkorDB (Redis-backed)
Vector indexes · Embeddings
Temporal graph queries
standalone — no deps
HTTP routes (auto-generated)
20+ integration adapters
JWT multi-tenant auth
Redis cache · DuckDB analytics
imports orbit-sagittarius
Discovers commands at runtime
from /v1/meta endpoint
No business logic
deps: typer · httpx only
calls constellation HTTP API
Key design constraint: constellation-lite has zero knowledge of integration business logic. It discovers all available commands dynamically from the running constellation server via /v1/meta, then proxies every invocation as an HTTP request. New integrations added to constellation automatically appear in the CLI with no CLI code changes.
The @service_method Decorator
The entire HTTP + CLI surface is generated from a single decorator. Every integration method tagged with @service_method is registered in service_registry. At startup, build_fastapi_app() walks the registry and mounts a FastAPI route; build_cli_app() walks the same registry and creates a Typer command. The MCP tool list exposed at /mcp/tools is also derived from the same registry. One decorator, three interfaces.
Technology Stack
| Concern | Technology | Notes |
|---|---|---|
| Web Framework | FastAPI 0.115 | Python 3.11 · async-first · auto-generated OpenAPI docs |
| Auth | JWT + API Key + OAuth2 | python-jose · PyJWT · per-request tenant_id + user_email claims |
| HTTP Client | httpx | Async client used in all integration adapters and CLI proxy |
| Cache | Redis 7+ | DB 0: response cache + rate limiting · stale-while-revalidate strategy |
| Database | PostgreSQL (asyncpg) | Optional relational store for persistent platform state |
| Analytics | DuckDB | In-process OLAP engine for DORA metrics and team health queries |
| Knowledge Graph | FalkorDB (Redis-backed) | DB 1: graph nodes + edges + vector indexes via orbit-sagittarius |
| Embeddings | sentence-transformers | all-mpnet-base-v2 · 768-dim vectors stored in FalkorDB |
| CLI | Typer | Full CLI in constellation · proxy CLI in constellation-lite |
| Package Manager | uv | Monorepo workspace · Python 3.11 pinned via .python-version |
| API Framework (MCP) | Custom MCP engine | Tool registry + executor; tools exposed at /mcp/tools and /mcp/execute |
Reference
Environment Variables
Octopus is configured entirely via environment variables. Copy .env.example to .env to get started:
cp .env.example .env
Required variables:
| Variable | Purpose |
|---|---|
INTERNAL_API_KEY | Authenticates internal API-to-API calls |
JWT_SECRET_KEY | Signs and verifies JWT tokens (HS256 by default) |
JWT_PUBLIC_KEY | RSA public key for asymmetric JWT verification (base64-encoded) |
Infrastructure variables (with defaults):
| Variable | Default | Purpose |
|---|---|---|
PORT | 4002 | Uvicorn listen port |
REDIS_HOST | localhost | Redis hostname |
REDIS_PORT | 6380 | Redis port (host-mapped; internal container port is 6379) |
SAGITTARIUS_REDIS_URL | redis://localhost:6380/1 | Redis URL for knowledge graph (DB 1) |
ENVIRONMENT | development | Controls debug logging and CORS |
Per-integration OAuth variables — each integration requires its own CLIENT_ID, CLIENT_SECRET, and REDIRECT_URI. See .env.example for the full list covering Google, Jira, GitHub, Microsoft 365, Slack, WhatsApp, SAP, and Moloni.
Python Version
Octopus requires Python 3.11. The version is pinned in .python-version at the repo root. uv enforces this automatically.
cat .python-version
# 3.11
uv Workspace Commands
# Install all workspace members and their dependencies
uv sync
# Run the constellation API server
uv run --package constellation uvicorn app.main:app --host 0.0.0.0 --port 4002 --reload
# Run the full CLI (constellation workspace)
uv run --package constellation constellation --help
# Run the lite CLI proxy (constellation-lite workspace)
uv run --package constellation-lite constellation --help
# Run tests
uv run pytest apps/constellation/tests/ -x -q
# Build the docs site
cd apps/docs && npm run build