# is7qin/c3api architecture

> Architecture diagram of the GitHub repository is7qin/c3api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/is7qin/c3api
- Repository: https://github.com/is7qin/c3api

## Overview

c3api is a self-hosted AI gateway with an embedded admin and user console. Clients send requests through the HTTP server; the proxy authenticates and gates AI traffic, obtains scheduler-selected upstream attempts, forwards supported protocols, and records usage for billing and statistics. Admin and user APIs expose account, template, routing, rules, pricing, and usage management. The README documents the broader capabilities; several worker and integration links below are therefore documented relationships rather than inspected call sites.

Main entry points: [`internal/repository`](https://github.com/is7qin/c3api/tree/main/internal/repository) (Repositories), [`internal/proxy/pipeline.go`](https://github.com/is7qin/c3api/blob/main/internal/proxy/pipeline.go) (AI proxy pipeline), [`internal/server/server.go`](https://github.com/is7qin/c3api/blob/main/internal/server/server.go) (HTTP server), [`internal/scheduler/routing_view.go`](https://github.com/is7qin/c3api/blob/main/internal/scheduler/routing_view.go) (Plan selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP and consoles"]
  node_server["HTTP server<br/>[server.go]"]
  node_web["Web console<br/>[App.tsx]"]
  node_api["API handlers"]
  node_service["Admin services<br/>[service.go]"]
end

subgraph group_gateway["AI gateway"]
  node_proxy["AI proxy pipeline<br/>[pipeline.go]"]
  node_protocols["Protocol forwarding"]
end

subgraph group_routing["Routing and rules"]
  node_scheduler["Plan selection<br/>[routing_view.go]"]
  node_compiler["Routing compiler"]
  node_routingservice["Routing management<br/>[routing.go]"]
  node_rules["Rules engine<br/>[engine.go]"]
end

subgraph group_operations["Usage and operations"]
  node_quality["Quality observation"]
  node_billing["Billing and usage"]
  node_pricing["Pricing sync<br/>[worker.go]"]
  node_workers["Background workers<br/>[worker.go]"]
end

subgraph group_persistence["Persistence"]
  node_repository["Repositories"]
  node_database[("PostgreSQL state")]
end

node_clients(("SDKs and browser"))
node_upstreams(("AI providers"))
node_redis[("Redis coordination")]

node_clients -->|"send requests"| node_server
node_server -->|"serves console"| node_web
node_web -->|"calls API"| node_server
node_server -->|"routes admin API"| node_api
node_api -->|"invokes services"| node_service
node_server -->|"routes AI traffic"| node_proxy
node_proxy -->|"selects attempts"| node_scheduler
node_proxy -->|"evaluates rules"| node_rules
node_proxy -->|"dispatches formats"| node_protocols
node_protocols -->|"forwards requests"| node_upstreams
node_proxy -->|"records usage"| node_billing
node_proxy -->|"observes attempts"| node_quality
node_quality -.->|"persists facts"| node_repository
node_compiler -.->|"reads observations"| node_repository
node_compiler -->|"publishes plans"| node_scheduler
node_routingservice -->|"manages routing data"| node_repository
node_routingservice -->|"updates routing"| node_scheduler
node_rules -->|"loads rules"| node_repository
node_service -->|"reads and writes"| node_repository
node_repository -->|"queries state"| node_database
node_billing -.->|"stores usage and balances"| node_repository
node_workers -->|"runs sync worker"| node_pricing
node_pricing -->|"upserts prices"| node_repository
node_database -.->|"publishes invalidations"| node_server
node_workers -.->|"coordinates instances"| node_redis

click node_server "https://github.com/is7qin/c3api/blob/main/internal/server/server.go"
click node_web "https://github.com/is7qin/c3api/blob/main/web/src/App.tsx"
click node_api "https://github.com/is7qin/c3api/tree/main/internal/handler"
click node_service "https://github.com/is7qin/c3api/blob/main/internal/service/service.go"
click node_proxy "https://github.com/is7qin/c3api/blob/main/internal/proxy/pipeline.go"
click node_protocols "https://github.com/is7qin/c3api/tree/main/internal/proxy"
click node_scheduler "https://github.com/is7qin/c3api/blob/main/internal/scheduler/routing_view.go"
click node_compiler "https://github.com/is7qin/c3api/blob/main/internal/scheduler/routing_compiler_wire.go"
click node_routingservice "https://github.com/is7qin/c3api/blob/main/internal/service/routing.go"
click node_rules "https://github.com/is7qin/c3api/blob/main/internal/rule/engine.go"
click node_quality "https://github.com/is7qin/c3api/tree/main/internal/quality"
click node_billing "https://github.com/is7qin/c3api/tree/main/internal/billing"
click node_pricing "https://github.com/is7qin/c3api/blob/main/internal/pricing/worker.go"
click node_workers "https://github.com/is7qin/c3api/blob/main/internal/worker/worker.go"
click node_repository "https://github.com/is7qin/c3api/tree/main/internal/repository"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_web,node_api,node_service,node_clients toneBlue
class node_proxy,node_protocols,node_redis toneAmber
class node_scheduler,node_compiler,node_routingservice,node_rules toneMint
class node_quality,node_billing,node_pricing,node_workers toneRose
class node_repository,node_database,node_upstreams toneIndigo
```

## Components

### HTTP and consoles

- [HTTP server](https://github.com/is7qin/c3api/blob/main/internal/server/server.go): `internal/server/server.go`
- [Web console](https://github.com/is7qin/c3api/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [API handlers](https://github.com/is7qin/c3api/tree/main/internal/handler): `internal/handler`
- [Admin services](https://github.com/is7qin/c3api/blob/main/internal/service/service.go): `internal/service/service.go`

### AI gateway

- [AI proxy pipeline](https://github.com/is7qin/c3api/blob/main/internal/proxy/pipeline.go): `internal/proxy/pipeline.go`
- [Protocol forwarding](https://github.com/is7qin/c3api/tree/main/internal/proxy): `internal/proxy`

### Routing and rules

- [Plan selection](https://github.com/is7qin/c3api/blob/main/internal/scheduler/routing_view.go): `internal/scheduler/routing_view.go`
- [Routing compiler](https://github.com/is7qin/c3api/blob/main/internal/scheduler/routing_compiler_wire.go): `internal/scheduler/routing_compiler_wire.go`
- [Routing management](https://github.com/is7qin/c3api/blob/main/internal/service/routing.go): `internal/service/routing.go`
- [Rules engine](https://github.com/is7qin/c3api/blob/main/internal/rule/engine.go): `internal/rule/engine.go`

### Usage and operations

- [Quality observation](https://github.com/is7qin/c3api/tree/main/internal/quality): `internal/quality`
- [Billing and usage](https://github.com/is7qin/c3api/tree/main/internal/billing): `internal/billing`
- [Pricing sync](https://github.com/is7qin/c3api/blob/main/internal/pricing/worker.go): `internal/pricing/worker.go`
- [Background workers](https://github.com/is7qin/c3api/blob/main/internal/worker/worker.go): `internal/worker/worker.go`

### Persistence

- [Repositories](https://github.com/is7qin/c3api/tree/main/internal/repository): `internal/repository`
- **PostgreSQL state**

### Other components

- **SDKs and browser**
- **AI providers**
- **Redis coordination**

## Connections

- SDKs and browser → HTTP server: send requests (evidence: `README.md`)
- HTTP server → Web console: serves console (evidence: `internal/server/server.go`)
- Web console → HTTP server: calls API (evidence: `README.md`)
- HTTP server → API handlers: routes admin API (evidence: `internal/server/server.go`)
- API handlers → Admin services: invokes services (evidence: `internal/handler/handler.go`)
- HTTP server → AI proxy pipeline: routes AI traffic (evidence: `internal/server/server.go`)
- AI proxy pipeline → Plan selection: selects attempts (evidence: `internal/proxy/pipeline.go`)
- AI proxy pipeline → Rules engine: evaluates rules (evidence: `internal/proxy/pipeline.go`)
- AI proxy pipeline → Protocol forwarding: dispatches formats (evidence: `README.md`)
- Protocol forwarding → AI providers: forwards requests (evidence: `README.md`)
- AI proxy pipeline → Billing and usage: records usage (evidence: `README.md`)
- AI proxy pipeline → Quality observation: observes attempts
- Quality observation → Repositories: persists facts
- Routing compiler → Repositories: reads observations
- Routing compiler → Plan selection: publishes plans (evidence: `README.md`)
- Routing management → Repositories: manages routing data (evidence: `internal/service/routing.go`)
- Routing management → Plan selection: updates routing (evidence: `internal/service/routing.go`)
- Rules engine → Repositories: loads rules (evidence: `internal/rule/engine.go`)
- Admin services → Repositories: reads and writes (evidence: `internal/service/service.go`)
- Repositories → PostgreSQL state: queries state (evidence: `internal/repository/routing_query.go`)
- Billing and usage → Repositories: stores usage and balances
- Background workers → Pricing sync: runs sync worker (evidence: `internal/pricing/worker.go`)
- Pricing sync → Repositories: upserts prices (evidence: `internal/pricing/worker.go`)
- PostgreSQL state → HTTP server: publishes invalidations (evidence: `README.md`)
- Background workers → Redis coordination: coordinates instances (evidence: `README.md`)