Codebase Explorer

A map of the repository, package by package. It is here so that "where does this behaviour live" has an answer you can read in a minute.

High-level architecture

Loading diagram...

The gateway serves both planes and holds its own configuration in memory. The analytics service stores usage and nothing else. See Architecture for why the line is drawn there.

Repository tree

tree
CogniGate/
├── gateway/                 # Go edge gateway (port 8080)
│   ├── main.go              # Flag parsing, config load, signal handling
│   ├── app.go               # Wires config + store + providers into a server
│   └── internal/
│       ├── server/          # Every HTTP route, both planes
│       ├── store/           # Tenants, keys, providers, rules, quotas (in memory)
│       ├── routing/         # Alias resolution, fallback, circuit breakers
│       ├── provider/        # Upstream clients and the provider interface
│       ├── catalog/         # Model catalogue refresh and lookup
│       ├── analytics/       # Usage client + the store wrapper that forwards to it
│       ├── cache/           # Response cache
│       ├── capture/         # Debug capture ring buffer
│       ├── events/          # Event log and outbound webhooks
│       ├── apierr/          # The single error envelope every route returns
│       ├── obs/             # Structured logs, Prometheus metrics, tracing
│       ├── httpx/           # Shared HTTP client construction
│       └── config/          # File + environment configuration and validation
├── analytics/               # Java Spring Boot usage store (port 8081)
│   └── src/main/java/com/cognigate/
│       ├── controller/      # UsageController — ingest, totals, breakdown
│       ├── entity/          # UsageMetric
│       ├── repository/      # UsageMetricRepo — every aggregate is a query
│       ├── dto/             # Request and response records
│       ├── service/         # BillingService — the monthly pricing job
│       └── config/          # Security, the API token filter, thread config
├── conformance/             # Black-box suite that drives the running stack
├── spec/                    # GW-1..GW-14 acceptance criteria
├── docs/                    # Next.js documentation site (port 3000)
├── scripts/                 # Generators for the two published API artefacts
├── cognigate.config.yml     # Annotated default configuration
├── docker-compose.yml       # Reference deployment
├── openapi.yaml             # Machine-readable contract for both planes
├── postman_collection.json  # The same surface, as an importable collection
├── setup.sh / setup.ps1     # First-run setup for POSIX and Windows
└── LICENSE                  # Apache-2.0

1. The gateway (Go)

Everything a request touches is in gateway/internal/.

  • server/ — one file per concern, and the place to start. chat.go is the completion path; data.go the rest of the data plane; admin.go the whole /admin/v1 surface; middleware.go authentication, request ids and the audit trail; limits.go and quota.go the four ways a request can be refused with a 429.
  • routing/ — resolve.go turns a requested model or capability alias into an ordered chain of concrete provider/model pairs. dispatch.go walks that chain, and breaker.go keeps a provider that is failing out of it until it recovers. diagnose.go decides whether a given upstream failure is worth falling back over at all.
  • store/ — the in-memory implementation behind every configuration resource, plus the key hashing in keys.go. Data keys are stored hashed; the plaintext is returned once, at mint time, and never again.
  • analytics/ — client.go speaks to the Java service on three endpoints. store.go wraps the memory store and forwards only the usage methods to it, which is how the same binary runs with or without an analytics backend.
  • obs/ — structured logging, the Prometheus registry behind /metrics, and OpenTelemetry spans.

2. The analytics service (Java)

Eleven classes, and they are all about usage.

  • UsageController — POST /api/v1/usage to record, GET /api/v1/usage/totals and GET /api/v1/usage/breakdown to read back. Nothing else is exposed, because nothing else calls it.
  • UsageMetric — one row per completed request. requestId is unique, which is what makes a retried delivery a no-op instead of a double charge. The tenant is a plain string, deliberately: a foreign key would mean usage could not be recorded until tenant rows had been synchronised here first.
  • UsageMetricRepo — every aggregate is a database query returning an already-shaped DTO. Summing in Java would mean loading a billing period's every request into heap to produce five numbers.
  • BillingService — a monthly scheduled job that prices each tenant's window and logs the figure. Its tenant set comes from the usage rows themselves; there is no tenant table here to read instead.
  • ApiTokenFilter / SecurityConfig — a single shared bearer token, required, with no default. Absent configuration fails at startup rather than publishing an open metering API.

3. Configuration

cognigate.config.yml carries the defaults and documents every option inline — listen addresses, timeouts, cache, quota mode, limits, debug capture and observability. See Configuration for the options that matter most.