Fred Platform
Architecture
Entry point for the Fred codebase. Read this first — about 20 minutes — and every other document in this repo will make sense.
What is Fred
Fred is a platform for deploying operator-configured AI agents at team scale. A platform admin sets the guardrails — quotas, allowed models, allowed tools. A team admin enrolls agents from a catalog and configures them for the team's context: prompts, MCP tools, routing policy. Team members interact with those agents through a managed chat interface — without writing code.
What makes Fred different from a simple LLM wrapper is its strict enforcement of governance boundaries. Operators configure within limits they cannot exceed. Every action is team-scoped and authorized. Execution is isolated from product management so neither layer can accidentally reach into the other's concerns. Fred is designed to run in regulated environments where auditability and role separation matter.
The one design decision that explains everything
Fred has three layers. They never merge.
This separation means the execution engine can evolve without touching product
APIs, and the product surface can evolve without touching how agents run. It also
keeps the authorization model clean: the ExecutionGrant carries
user_id, team_id, agent_instance_id, and
policy constraints — the runtime validates it but never issues it.
Components
Deployed services
These components run as processes or containers in a production deployment.
| Component | Layer | Role |
|---|---|---|
apps/fred-agents |
Runtime | Reference agent pod — the Fred-provided set of agents, built on fred-runtime |
apps/control-plane-backend |
Control plane | Product/session/admin APIs and ExecutionGrant issuance |
apps/knowledge-flow-backend |
Control plane | Document ingestion, retrieval, and knowledge management |
apps/frontend |
Client | React SPA — chat UI, agent management, session lifecycle |
Authoring libraries
These are Python libraries — they are not running services. They are the building
blocks used to write agent pods. apps/fred-agents is itself built with
them and serves as the reference implementation. Any team can import these same
libraries to author their own fully deployable agent pod, tailored to their context,
that slots into the same platform without modifying Fred's core.
| Library | Layer | What it provides |
|---|---|---|
libs/fred-runtime |
Runtime | Execution framework — agent engine, SSE, HITL, checkpoints. The core import for any custom agent pod. |
libs/fred-sdk |
SDK | Shared execution contracts, typed primitives, prompt utilities |
libs/fred-core |
Cross-cutting | Caching, config, logging, KPI stores |
fred-runtime, define
your agent behaviors, and deploy the result as a standard container. The control
plane enrolls it exactly like apps/fred-agents — no changes to Fred's
core required.
ignored/fred/agentic-backend is archived.
The backend migration is complete. Do not reference it as a target or active service.
Five mental models to internalize before writing code
› 1 Team-scoped agent instances
There are no global agents. An agent exists as a template (defined in the runtime pod catalog) and an instance (enrolled by a team admin in control-plane). Members interact only with instances. The instance carries tuning field values, MCP configuration, and prompt overrides — all team-scoped and stored in control-plane, never in the runtime pod.
› 2 The ExecutionGrant — the trust envelope
When the frontend calls execute, control-plane issues an
ExecutionGrant that encodes user_id,
team_id, agent_instance_id,
session_id, and policy constraints. The runtime validates
this grant on every request. Neither the frontend nor the user can forge
or escalate it. This is the primary security boundary between product
and execution.
› 3 The MCP catalog — tools as first-class citizens
Agents use tools via the Model Context Protocol (MCP). The MCP catalog
(mcp_catalog.yaml in the agent pod) declares available
servers, their configuration fields, and their behavioral contracts.
The control-plane proxies this catalog to the frontend — it does not
interpret it. The operator selects which MCP servers an agent instance
uses at enrollment time.
› 4 Platform admin vs team admin — orthogonal, not hierarchical
A platform admin (owner) sets immutable guardrails: quotas,
allowed model profiles, allowed MCP servers. A team admin
(manager) configures everything within those guardrails:
agents, routing policy, shared prompts.
Neither role can write to the other's surfaces.
Owner cannot manage agents or prompts. Manager cannot touch platform
policy. This is enforced at the API layer, not only in the UI.
See docs/swift/platform/REBAC.md for the full model.
› 5 Personal vs team scope
Everything in Fred is scoped to a team — including "personal."
/teams/personal is a reserved system team that represents
one user's private space. Personal prompts, sessions, and history all
live under this team. There is no parallel user-owned namespace outside
the team model. A user who is not a member of any other team still
has exactly one team: personal.
20-minute reading path
Five documents, in order. Read the why before you open each one.
How work gets done
Every task in Fred follows the same sequence. Planning lives in the repository, not in issue trackers.
docs/swift/rfc/ — the GitHub issue is not the design.docs/CONVENTIONS.md.Full details: docs/PMO.md §7 · Mandatory step rules: CLAUDE.md §Task lifecycle