> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gegentic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How the Gegentic services fit together, from the gateway to the portal.

Gegentic is made up of a small set of cooperating services. The easiest way to see the whole system at once is the [gegentic-quickstart](https://github.com/gegentic/gegentic-quickstart) Docker Compose bundle, which brings up every service together — this page describes the architecture defined there.

## Services

| Service                           | Port                         | Role                                                                                                                             |
| --------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Portal                            | `3002`                       | Web UI for org and project governance — policies, agents, access keys, traces                                                    |
| API                               | `4001` (REST), `4002` (gRPC) | Core backend. Manages orgs, projects, policies, and agents. The system of record other services call into                        |
| Gateway                           | `8787`                       | LLM gateway. Proxies AI requests to upstream providers, enforcing auth and guardrails on the way through                         |
| Guardian                          | `8700`                       | Guardrail evaluation engine. Scores prompts and completions against a policy's rule set (jailbreak detection, compliance checks) |
| Tracing                           | `5001`                       | Observability. Stores request/response spans for the audit log and review queue                                                  |
| Postgres, SuperTokens, ClickHouse | internal only                | Infrastructure dependencies — relational storage, auth sessions, and trace storage. Not exposed outside the Compose network      |

## Services diagram

```mermaid theme={null}
graph LR
  Customer["Customer app"] --> Gateway
  Portal["Portal :3002"] --> API

  subgraph Gegentic stack
    Gateway["Gateway :8787"] --> API["API :4001/:4002"]
    Gateway --> Guardian["Guardian :8700"]
    Gateway --> Tracing["Tracing :5001"]
    API --> Postgres[(Postgres)]
    API --> SuperTokens[(SuperTokens)]
    Tracing --> ClickHouse[(ClickHouse)]
  end

  Gateway --> Upstream["Upstream LLM provider"]
```

## Request flow

A governed LLM request moves through the stack like this:

```mermaid theme={null}
sequenceDiagram
  participant C as Customer app
  participant G as Gateway
  participant A as API
  participant Gd as Guardian
  participant L as Upstream LLM
  participant T as Tracing

  C->>G: Request (Access Key)
  G->>A: Validate key, fetch Agent + Policy Set
  G->>Gd: Evaluate input guardrails
  G->>L: Forward request
  L->>G: Completion
  G->>Gd: Evaluate output guardrails
  G->>T: Write span
  G->>C: Response
```

The Gateway sits in front of every AI call. It checks the Access Key against the API service, fetches the Agent's Policy Set, and routes the request through Guardian both before the call leaves (input guardrails) and after the response comes back (output guardrails) before returning it. Every step along the way is recorded as a span in Tracing, which powers the [audit log](/observability/audit-log) and [review queue](/observability/review-queue).

The Portal is a separate flow — it's the UI org owners use to configure Projects, Policy Sets, and Agents, and to browse traces. It talks to the API service directly and never sits on the request path.

## Try it locally

The full architecture above is exactly what [gegentic-quickstart](https://github.com/gegentic/gegentic-quickstart) starts with `docker compose up`. See [Run Gegentic Locally with Quickstart](/self-hosting) for setup instructions.