# Gateway Architecture — Agent + Skill + Graph Pipeline

This is the **interface layer** of the Agents project. Everything that connects
the outside world to the agent system lives here — REST APIs, Discord bot,
and authentication.

---

## Directory Map

| Path | Description | Docs |
|---|---|---|
| `gateway/v1/` | REST API endpoints — chat, agent listing, OpenAI-compatible completions | [v1.md](v1/v1.md) |
| `gateway/discord/` | Discord bot connector — in-process DM handler with LangGraph integration | [discord.md](discord/discord.md) |
| `gateway/auth/` | Auth service registry + Jellyfin Quick Connect implementation | [auth.md](auth/auth.md) |

---

## Supporting Modules

| Path | Purpose |
|---|---|
| `gateway/dependencies.py` | FastAPI `Depends` providers — `get_llm_client()`, `get_agent_graph()` |
| `src/config.py` | `.env` loader and config accessor |
| `src/llm.py` | OpenAI-compatible client factory (DeepSeek) |
| `src/state.py` | LangGraph `AgentState` TypedDict |
| `src/graph.py` | LangGraph StateGraph factory — agent_node, tool_node, routing |
| `src/tools_adapter.py` | Wraps skill tools as LangChain `@tool` functions |
| `src/auth_store.py` | SQLite persistence for Discord → service auth linking |
| `agents/` | Agent definitions (dataclass + registry) |
| `agents/skills/` | Skill definitions — prompt fragments, tool schemas, executors |

---

## High-Level Request Flow

```
┌──────────────────────────────┐
│  Client (OpenWebUI / HTTP)   │
└──────────────┬───────────────┘
               │ POST /v1/chat/completions
               ▼
┌──────────────────────────────┐
│  gateway/v1/chat.py          │  ← resolves agent, invokes graph
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│  LangGraph StateGraph        │  ← src/graph.py
│  ┌──────────┐   ┌──────────┐│
│  │agent_node│──▶│tool_node ││
│  │(LLM call)│◀──│(skills)  ││
│  └──────────┘   └──────────┘│
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│  agents/skills/              │  ← Seerr API, Jellyfin API, etc.
└──────────────────────────────┘
```

For a detailed step-by-step walkthrough of the graph execution (including
multi-turn context and tool-calling loops), see [v1.md](v1/v1.md).

---

## Startup

`main.py` is the entry point. At startup it:

1. Loads `.env` → creates the LLM client (DeepSeek) → stores on `app.state.llm_client`
2. Calls `load_all_agents()` → imports every agent and skill module (they self-register)
3. Imports `gateway.auth.jellyfin` → self-registers the Jellyfin auth service
4. Mounts routers: `/v1/*` (chat endpoints) and `/api/v1/auth/*` (auth endpoints)
5. Starts the Discord bot as a background asyncio task (lifespan)