GitHub technical reference
This page is generated from sync/contract.json and points to canonical technical docs in the octafuse-gateway repository. This website keeps user-facing summaries; APIs, deployments, migrations, architecture, and behavior semantics live with gateway code.
Quickstart Minimal Docker and Cloudflare local D1 startup paths.
User-facing APIs OpenAI / Anthropic / Gemini, Images, Audio, Agent Tools, model lists, and budget state.
Admin HTTP API APIs for Providers, models, routing, Tools, users, keys, billing config, logs, and analytics.
Docker / self-hosted Docker images, Compose, GHCR, Postgres / MySQL, and Zeabur notes.
Reader entry points
Section titled “Reader entry points”| Doc | What it covers |
|---|---|
| Documentation index | Entry points organized by users, developers, operators, and maintainers. |
| Quickstart | Minimal Docker and Cloudflare local D1 startup paths. |
| Admin configuration | Configure Providers, model routing, Agent Tools, users, and API keys after deployment. |
| Feature map | Overview of protocols, Agent Tools, route strategies, billing, administration, and deployment. |
Developers and integration
Section titled “Developers and integration”| Doc | What it covers |
|---|---|
| System integration | Boundaries, key types, and common flows for portals, backends, or SaaS integrations. |
| API overview | Proxy/Admin base URLs, authentication, and error shapes. |
| User-facing APIs | OpenAI / Anthropic / Gemini, Images, Audio, Agent Tools, model lists, and budget state. |
| Admin HTTP API | APIs for Providers, models, routing, Tools, users, keys, billing config, logs, and analytics. |
| Local development and testing | D1, Node + Postgres, Node + MySQL, Docker, and smoke test combinations. |
Architecture and behavior semantics
Section titled “Architecture and behavior semantics”| Doc | What it covers |
|---|---|
| Runtime and data storage | Cloudflare / Node and D1 / Postgres / MySQL combination matrix. |
| Route topology | Request Surface → Route Pool → Upstream Target relationships, operations, Provider Sticky, and failover boundaries. |
| Route strategies | Algorithms, tier overrides, precedence, and Provider Sticky for hash_affinity, weighted_random, weight_priority, and weighted_round_robin. |
| Proxy request lifecycle | Auth, Surface / Pool / Target resolution, four strategies, Provider Sticky, circuits, failover, and async billing. |
| Users and API key data model | Relationships and constraints for users, API keys, budgets, request logs, and audit logs. |
| Streaming billing and cancellation | Streaming chat, client cancellation, usage parsing, and charge state. |
| Image models | gpt-image-2 and Seedream: endpoints, parameters, billing conversion, and ops acceptance. |
| Time and timezone | UTC storage, API output, Admin display, and business day boundaries. |
Deployment and operations
Section titled “Deployment and operations”| Doc | What it covers |
|---|---|
| Deployment patterns | Overview of Cloudflare, Hybrid, full self-hosted, MySQL, and Zeabur modes. |
| Cloudflare deployment | Worker, Admin, D1, Build variables, Workers Builds, and migration order. |
| Docker / self-hosted | Docker images, Compose, GHCR, Postgres / MySQL, and Zeabur notes. |
| Gemini models.generate migration | Migration 0017: merge streaming and non-streaming Surfaces, handle conflicting Pools, and verify Gemini wire actions. |
| Priority-tier route strategy migration | Migration 0018: add Route Pool tier_strategies with deployment order and acceptance checks. |
| Canonical route strategy ID migration | Migration 0019: the historical 2.2.0 strategy-ID cutover and persisted-policy validation. |
| Provider Sticky migration | Migration 0020: add Route Pool Sticky configuration and shared bindings, with v2.3.0 deployment order and operations. |
| Route strategy display-ID migration | Migration 0021: hard-cut cache_affinity / fixed_order to hash_affinity / weight_priority with no old-ID aliases. |
| D1 ↔ Postgres cutover | ETL, reconciliation, canary, cutover, and rollback notes. |
| Cloudflare command cheatsheet | Commands for Cloudflare local dev, dev demo, and production Git deploy. |
Maintainers and conventions
Section titled “Maintainers and conventions”| Doc | What it covers |
|---|---|
| Release and versioning | Changesets, Version PRs, tags, GitHub Releases, and GHCR images. |
| Documentation boundaries and secret hygiene | Repository docs layers, website boundaries, placeholders, and forbidden values. |
| Minimal curl examples | Minimal curl commands for health, user inference, an Agent Tool, and an Admin auth probe. |