> For the complete documentation index, see [llms.txt](https://docs.mediafier.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediafier.ai/platform/platform-architecture.md).

# Platform Architecture

Three layers, one enforcement chain, one trace ID — the shape of the platform without the internals.

> **Three layers. One enforcement chain. One trace ID.**

Mediafier's architecture has three concentric layers. Agent surfaces on the outside. The gateway in the middle. Governed resources and the runtimes that execute them on the inside. Every interaction crosses all three. Every interaction emits a trace ID.

***

## The three layers

```
        ┌────────────────────────────────────────────────────┐
        │  AGENT SURFACES                                    │
        │  Agent-first (CLI + MCP) · Slack/Teams · Pippa     │
        └─────────────────────┬──────────────────────────────┘
                              │
                              ▼
        ┌────────────────────────────────────────────────────┐
        │  THE SINGLE GATEWAY                                │
        │  Identity → Org → Authz → Rate → Billing → Audit   │
        └─────────────────────┬──────────────────────────────┘
                              │
                              ▼
        ┌────────────────────────────────────────────────────┐
        │  GOVERNED RESOURCES & RUNTIMES                     │
        │  discovery (what you may invoke) ·                 │
        │  execution (the runtimes that do the work)         │
        └────────────────────────────────────────────────────┘
```

### Layer 1: agent surfaces

Three primary surfaces, in this order:

1. **Agent-first (CLI + MCP)** — the primary integration. Any agent platform, any harness, any IDE.
2. **Slack & Teams** — team-native conversational operations.
3. **Pippa chat** — web/mobile control-room interface.

All three surfaces resolve identity from Auth0 and reach the same gateway. There is no "back door" surface that bypasses governance.

### Layer 2: the single gateway

Every request crosses a deterministic enforcement chain. The chain is ordered: identity proves who you are, organization context decides which tenant boundary applies, authorization decides whether you can invoke this specific tool, rate limiting protects shared capacity, billing enforces credits before execution, and audit records what happened. Only after the chain completes does the gateway dispatch the call to the runtime that owns the tool.

Credentials are resolved server-side per call and injected by the gateway, scoped to a single invocation; tools and agents never receive access to Mediafier's credential stores, and secrets stay out of agent payloads and runtime logs.

### Layer 3: governed resources + runtimes

Inside the boundary, discovery and execution are distinct concerns. Discovery is the governed, read-only view agents plan against: which resources your organization may invoke, and what each one's contract is. Execution is the runtime work — running the tool, the skill, the MediaClaw step, the workflow, or a partner integration — and it is reachable only through the gateway. That separation is what lets Mediafier grow and revise capabilities without breaking the contracts agents bind to; see [Governed Resources & Discovery](/platform/governed-resource-substrate.md).

***

## Where the trace ID lives

Every request is stamped with a trace ID at gateway entry. That ID:

* Returns to the caller in the response headers (`X-Trace-Id`) and in error envelopes.
* Is propagated to every downstream runtime call.
* Lands in the audit log as the join key for "what happened" across identity, billing, and execution records.

If a customer reports a problem, the only piece of information support needs is the trace ID. From there the entire chain is reconstructable.

***

## What runs where

Agent surfaces — your harness, IDE, CI process, or chat client — run in your environment. Everything from the gateway inward runs in Mediafier's infrastructure, entered through the single canonical ingress `https://mcp.mediafier.ai/mcp`. The trace ID stitches the two sides together: one ID follows the call from your client through enforcement and execution and back.

***

## Where to go next

| If you're…                                | Read next                                                                  |
| ----------------------------------------- | -------------------------------------------------------------------------- |
| Wanting the philosophy behind this layout | [Core Philosophy](/overview/core-philosophy.md)                            |
| Integrating                               | [Agent-First Access (CLI + MCP)](/connect/agent-first-access.md)           |
| Studying the gateway in detail            | [The Gateway](/platform/gateway.md)                                        |
| Studying discovery                        | [Governed Resources & Discovery](/platform/governed-resource-substrate.md) |