Overview

The streaming-first Go server for AI agents.

Start here

Getting started	From go get to a tested streaming endpoint in about ten minutes
Examples	Runnable programs: hello, streaming, an OpenAI proxy, an agent UI, a JSON API
API reference	Every exported symbol, in one page

Guides

Guide	Read it when
Streaming	You stream anything: SSE, NDJSON, tokens, progress, feeds
AI backends	You serve a model: OpenAI-compatible endpoints, proxies, agent events, MCP
Routing	You need the pattern rules, groups, mounts, or why a route panicked
Middleware	You write or port middleware: ordering, CORS, auth, logging, rate limits
Security	You want to know what the defaults stop and what is still your job
Configuration	You need to change a limit, or understand a derived one
Deployment	You ship it: Docker, systemd, Kubernetes, nginx, TLS
Testing	You test handlers and streams
Benchmarking	You measure a streaming endpoint with photon bench

Migrating

Migration overview — a concept map across frameworks, then a guide for each: net/http · chi · gin · echo · Fiber · FastAPI and Express

Project

Changelog · Contributing · Security policy · Benchmarks · Performance audit · License: Apache-2.0

Design and decisions

The documents below record how Photon was designed: the requirements, the research behind each decision, the decisions themselves, and the places where implementation proved the design wrong. They were written before the code and are kept as dated records rather than rewritten.

On the project name. The project was called Velo when these documents were written and was renamed Photon afterwards. The records keep the old name, because retroactively editing a decision record destroys what it is for. Where they quote code, the import path is the old one; the module is now github.com/agenticmarket/photon.

The original briefs are in history/.

Design documents

#	Document	Covers goal.txt §
00	Executive Summary	1
01	Product Definition	3, 4
02	Personas and Use Cases	5
03	Competitive and Existing-Project Analysis	2, 6, 7, 38
04	Architecture Overview	8, 9
05	Request Lifecycle	9
06	Routing Design	8
07	Concurrency Model	11
08	Memory Model	10
09	Streaming and Backpressure	12, 17
10	AI Architecture	15, 17
11	MCP Architecture	16
12	Security Architecture	13, 14, 21
13	Threat Model	31
14	Reliability Architecture	18
15	Observability Architecture	19
16	API Design	20, 21, 22
17	Dependency and Supply-Chain Strategy	23, 24
18	Performance Model and Targets	4, 5, 23
19	Benchmark Methodology	6, 7, 28
20	Testing Strategy	25
21	Security Testing Strategy	26
22	Fuzzing, Stress, Soak and Chaos	25, 27, 29, 30
23	Deployment and Compatibility	32, 33
24	Versioning and Project Structure	29, 34
25	Roadmap, Open Questions, Risks	36, 37, 38, 39
26	Architecture Readiness Review	39, 40

Architecture Decision Records

ADR	Decision	Status
ADR-0001	Why Go	Accepted
ADR-0002	HTTP core: net/http vs. custom parser vs. fasthttp	Accepted
ADR-0003	Router architecture	Accepted
ADR-0004	Concurrency model	Accepted
ADR-0005	Memory management	Accepted
ADR-0006	Streaming architecture	Accepted
ADR-0007	AI integration strategy	Accepted
ADR-0008	MCP integration	Accepted
ADR-0009	Security defaults	Accepted
ADR-0010	No default write/read timeout	Accepted
ADR-0011	API surface minimalism	Accepted
ADR-0012	No HTTP/3 in core	Accepted
ADR-0013	Dependency budget	Accepted
ADR-0014	Zero-overhead-when-disabled observability	Accepted
ADR-0015	Configuration surface	Accepted
ADR-0016	Resource limit profile and host scaling (resolves Q1, Q3, Q4)	Accepted
ADR-0017	Streaming backpressure policy (resolves Q2)	Accepted

Research notes (evidence base)

Note	Subject
01	Go HTTP ecosystem: measured performance
02	Go runtime, GC, memory model
03	Router algorithms and alternative stacks
04	Protocols, advisories, DoS
05	AI infrastructure and MCP

Reading order

1. 00-executive-summary.md — what we are building and the five decisions that shape it
2. 01-product-definition.md — core / module / extension boundary
3. 04-architecture-overview.md — the shape of the system
4. 12-security-architecture.md — because it constrains everything else
5. 18-performance-model-and-targets.md — because goals.txt’s numbers need conditions
6. Everything else as needed

A note on goal.txt

goal.txt is the requirements input and is preserved verbatim. Where this design disagrees with it, the disagreement is stated explicitly and in bold in the relevant document, with the reasoning. Silently contradicting the brief would be worse than following it.