# flipthedream/agentkit architecture

> Architecture diagram of the GitHub repository flipthedream/agentkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flipthedream/agentkit
- Repository: https://github.com/flipthedream/agentkit

## Overview

1. **What this repo is**
   - `agentkit` is a three-part fullstack framework for agentic workflows: a **SvelteKit 5 frontend**, a **PocketBase-based backend extended in Go**, and a **NATS event bus**.
   - The architecture is intentionally “runtime-configurable” so the same frontend image can run in different deployments without rebuilding.

2. **Top-level runtime shape**
   - The system runs as separate services:
     - **Frontend** on `:5173` in dev or `:3000` in production
     - **Backend/PocketBase** on `:8090`
     - **NATS** on `:4222` with **WebSocket** access on `:9222`
   - A **SQLite database** lives inside PocketBase’s `pb_data` volume, so the backend is also the persistence boundary.

3. **Backend subsystem**
   - The backend entrypoint is `backend/cmd/server/main.go`, which launches PocketBase in Go.
   - `backend/internal/pocketbase/` is the main extension layer: it bootstraps PocketBase, adds hooks, config endpoints, auth behavior, and any custom API behavior.
   - PocketBase provides the core backend capabilities: **auth, database access, file storage, and realtime API**.

4. **Backend-to-frontend contract**
   - The backend exposes `/api/config`, which is the key integration point for runtime configuration.
   - That endpoint supplies browser-facing URLs such as:
     - `PUBLIC_POCKETBASE_URL`
     - `PUBLIC_NATS_WS_URL`
   - It also exposes an internal SSR-facing URL:
     - `INTERNAL_POCKETBASE_URL`
   - This makes the backend the source of truth for deployment-specific connectivity.

5. **Frontend subsystem**
   - The frontend is a **SvelteKit 5** app using the modern runes-based model.
   - `frontend/src/routes/+layout.ts` performs universal loading and fetches runtime config from the backend.
   - `frontend/src/lib/config.ts` centralizes config resolution and provides build-time fallbacks if the backend is unavailable.
   - `frontend/src/lib/pocketbase.ts` creates the PocketBase client, and `frontend/src/lib/nats.svelte.ts` handles browser NATS connectivity.

6. **Browser vs SSR data flow**
   - The frontend uses a split model:
     - **SSR/server-side rendering** talks to PocketBase through `INTERNAL_POCKETBASE_URL` over the Docker network.
     - **Browser-side code** talks to the public PocketBase URL and to NATS over WebSocket.
   - This avoids baking environment-specific hostnames into the frontend build artifact.

7. **Messaging and realtime subsystem**
   - `backend/internal/nats/client.go` is the backend’s NATS client boundary.
   - The repo’s NATS configuration lives in `nats/nats-server.conf`.
   - The intended subject model is hierarchical, with patterns like:
     - `agentkit.>`
     - `agentkit.heartbeat`
     - `agentkit.events.*`
   - NATS is used for cross-service pub/sub and realtime event propagation, separate from PocketBase’s own API/realtime layer.

8. **Deployment boundary**
   - The repo supports three operational modes:
     - **Development** with hot reload (`air` for Go, Vite HMR for SvelteKit)
     - **Self-built production** via multi-stage Docker images
     - **Deploy mode** using prebuilt GitHub Container Registry images
   - Compose files separate these concerns:
     - `docker-compose.yml`
     - `docker-compose.prod.yml`
     - `docker-compose.deploy.yml`

9. **Infrastructure and packaging**
   - Docker is the main orchestration boundary across all environments.
   - Backend and frontend each have dev and prod Dockerfiles, indicating distinct runtime packaging strategies.
   - The backend image is expected to run PocketBase in server mode on `0.0.0.0:8090`; this is important because the healthcheck and deploy flow depend on that command shape.

10. **CI/CD flow**
   - GitHub Actions (`.github/workflows/build.yml`) builds and validates the project.
   - On `main`, it publishes `latest` and `main` images to GHCR; tagged releases publish semantic version tags.
   - This means the deployment story is image-driven rather than source-driven.

11. **Where extension points live**
   - Backend customization belongs in `backend/internal/pocketbase/` for hooks, auth, API extensions, and OAuth wiring.
   - Messaging conventions belong in `backend/internal/nats/` and `nats/nats-server.conf`.
   - UI additions belong under `frontend/src/routes/`, with SvelteKit file-based routing mapping directly to URL structure.

12. **How to draw the architecture**
   - Draw the **frontend** as the browser-facing shell, with SSR and client-side paths.
   - Draw the **backend** as PocketBase plus Go extensions, owning auth, config, persistence, and backend event integration.
   - Draw **NATS** as a separate eventing layer, connected to the backend and directly reachable from the browser via WebSocket.
   - Show **SQLite/PocketBase storage** as the backend’s internal persistence boundary, not a separate app database service.

Main entry points: [`frontend/src/routes`](https://github.com/flipthedream/agentkit/tree/main/frontend/src/routes) (SvelteKit app), [`backend/internal/pocketbase/pocketbase.go`](https://github.com/flipthedream/agentkit/blob/main/backend/internal/pocketbase/pocketbase.go) (PocketBase ext), [`backend/cmd/server/main.go`](https://github.com/flipthedream/agentkit/blob/main/backend/cmd/server/main.go) (Server entry), [`.github/workflows/build.yml`](https://github.com/flipthedream/agentkit/blob/main/.github/workflows/build.yml) (Build workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["SvelteKit app<br/>frontend app"]
  node_frontend_layout["Runtime config<br/>SSR loader<br/>[+layout.ts]"]
  node_frontend_config["Config resolver<br/>client config<br/>[config.ts]"]
  node_frontend_pb["PocketBase client<br/>browser client<br/>[pocketbase.ts]"]
  node_frontend_nats["NATS client<br/>browser ws client<br/>[nats.svelte.ts]"]
end

subgraph group_backend["Backend"]
  node_backend_entry["Server entry<br/>go entrypoint<br/>[main.go]"]
  node_backend_pb_ext["PocketBase ext<br/>go extension layer<br/>[pocketbase.go]"]
  node_backend_config_api["Config API<br/>backend API<br/>[pocketbase.go]"]
  node_backend_hooks["Hooks & auth<br/>backend behavior<br/>[pocketbase.go]"]
  node_backend_nats["NATS boundary<br/>go client<br/>[client.go]"]
  node_pb_core[("PocketBase core<br/>backend platform")]
  node_pb_data[("SQLite storage<br/>persistent volume")]
end

subgraph group_messaging["Messaging"]
  node_nats_server(("NATS server<br/>event bus<br/>[nats-server.conf]"))
  node_nats_subjects["Subjects<br/>topic model<br/>[nats-server.conf]"]
end

subgraph group_infra["Infra"]
  node_compose_dev["Compose files<br/>orchestration<br/>[docker-compose.yml]"]
  node_backend_images["Backend images<br/>container packaging"]
  node_frontend_images["Frontend images<br/>container packaging"]
end

subgraph group_cicd["CI/CD"]
  node_build_workflow["Build workflow<br/>ci pipeline<br/>[build.yml]"]
end

node_frontend_app -->|"loads config"| node_frontend_layout
node_frontend_layout -->|"fetches runtime config"| node_backend_config_api
node_frontend_config -->|"resolves from"| node_backend_config_api
node_frontend_app -->|"uses"| node_frontend_pb
node_frontend_app -->|"connects to"| node_frontend_nats
node_frontend_layout -->|"normalizes"| node_frontend_config
node_backend_entry -->|"starts"| node_backend_pb_ext
node_backend_pb_ext -->|"extends"| node_pb_core
node_backend_pb_ext -->|"serves"| node_backend_config_api
node_backend_pb_ext -->|"contains"| node_backend_hooks
node_backend_pb_ext -->|"publishes events"| node_backend_nats
node_backend_nats -->|"connects to"| node_nats_server
node_nats_server -->|"routes by"| node_nats_subjects
node_pb_core -->|"persists in"| node_pb_data
node_backend_entry -->|"runs under"| node_compose_dev
node_frontend_app -->|"runs under"| node_compose_dev
node_backend_entry -->|"packages as"| node_backend_images
node_frontend_app -->|"packages as"| node_frontend_images
node_build_workflow -->|"builds"| node_backend_images
node_build_workflow -->|"builds"| node_frontend_images
node_build_workflow -->|"validates deploys"| node_compose_dev

click node_frontend_app "https://github.com/flipthedream/agentkit/tree/main/frontend/src/routes"
click node_frontend_layout "https://github.com/flipthedream/agentkit/blob/main/frontend/src/routes/+layout.ts"
click node_frontend_config "https://github.com/flipthedream/agentkit/blob/main/frontend/src/lib/config.ts"
click node_frontend_pb "https://github.com/flipthedream/agentkit/blob/main/frontend/src/lib/pocketbase.ts"
click node_frontend_nats "https://github.com/flipthedream/agentkit/blob/main/frontend/src/lib/nats.svelte.ts"
click node_backend_entry "https://github.com/flipthedream/agentkit/blob/main/backend/cmd/server/main.go"
click node_backend_pb_ext "https://github.com/flipthedream/agentkit/blob/main/backend/internal/pocketbase/pocketbase.go"
click node_backend_config_api "https://github.com/flipthedream/agentkit/blob/main/backend/internal/pocketbase/pocketbase.go"
click node_backend_hooks "https://github.com/flipthedream/agentkit/blob/main/backend/internal/pocketbase/pocketbase.go"
click node_backend_nats "https://github.com/flipthedream/agentkit/blob/main/backend/internal/nats/client.go"
click node_nats_server "https://github.com/flipthedream/agentkit/blob/main/nats/nats-server.conf"
click node_nats_subjects "https://github.com/flipthedream/agentkit/blob/main/nats/nats-server.conf"
click node_compose_dev "https://github.com/flipthedream/agentkit/blob/main/docker-compose.yml"
click node_backend_images "https://github.com/flipthedream/agentkit/tree/main/backend/Dockerfile"
click node_frontend_images "https://github.com/flipthedream/agentkit/tree/main/frontend/Dockerfile"
click node_build_workflow "https://github.com/flipthedream/agentkit/blob/main/.github/workflows/build.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_frontend_layout,node_frontend_config,node_frontend_pb,node_frontend_nats toneBlue
class node_backend_entry,node_backend_pb_ext,node_backend_config_api,node_backend_hooks,node_backend_nats,node_pb_core,node_pb_data toneAmber
class node_nats_server,node_nats_subjects toneMint
class node_compose_dev,node_backend_images,node_frontend_images toneRose
class node_build_workflow toneIndigo
```

## Components

### Frontend

SvelteKit browser shell with SSR and client-side runtime config.

- [SvelteKit app](https://github.com/flipthedream/agentkit/tree/main/frontend/src/routes): frontend app · Browser-facing UI shell and routing layer. · `frontend/src/routes`
- [Runtime config](https://github.com/flipthedream/agentkit/blob/main/frontend/src/routes/+layout.ts): SSR loader · Universal layout loading that fetches backend-supplied runtime settings. · `frontend/src/routes/+layout.ts`
- [Config resolver](https://github.com/flipthedream/agentkit/blob/main/frontend/src/lib/config.ts): client config · Centralizes browser and SSR config resolution with fallbacks. · `frontend/src/lib/config.ts`
- [PocketBase client](https://github.com/flipthedream/agentkit/blob/main/frontend/src/lib/pocketbase.ts): browser client · Client-side PocketBase connectivity for the app. · `frontend/src/lib/pocketbase.ts`
- [NATS client](https://github.com/flipthedream/agentkit/blob/main/frontend/src/lib/nats.svelte.ts): browser ws client · Browser WebSocket connection to NATS. · `frontend/src/lib/nats.svelte.ts`

### Backend

PocketBase server extended in Go for config, auth, and APIs.

- [Server entry](https://github.com/flipthedream/agentkit/blob/main/backend/cmd/server/main.go): go entrypoint · Launches PocketBase in server mode. · `backend/cmd/server/main.go`
- [PocketBase ext](https://github.com/flipthedream/agentkit/blob/main/backend/internal/pocketbase/pocketbase.go): go extension layer · Bootstraps PocketBase and wires custom behavior. · `backend/internal/pocketbase/pocketbase.go`
- [Config API](https://github.com/flipthedream/agentkit/blob/main/backend/internal/pocketbase/pocketbase.go): backend API · Exposes runtime deployment config to the frontend. · `backend/internal/pocketbase/pocketbase.go`
- [Hooks & auth](https://github.com/flipthedream/agentkit/blob/main/backend/internal/pocketbase/pocketbase.go): backend behavior · Custom auth, hooks, and API extensions around PocketBase. · `backend/internal/pocketbase/pocketbase.go`
- [NATS boundary](https://github.com/flipthedream/agentkit/blob/main/backend/internal/nats/client.go): go client · Backend-side NATS client and pub/sub integration. · `backend/internal/nats/client.go`
- **PocketBase core**: backend platform · Provides auth, database, file storage, and realtime API.
- **SQLite storage**: persistent volume · PocketBase data volume and embedded SQLite persistence boundary.

### Messaging

NATS event bus and subject conventions.

- [NATS server](https://github.com/flipthedream/agentkit/blob/main/nats/nats-server.conf): event bus · Standalone NATS broker with websocket access. · `nats/nats-server.conf`
- [Subjects](https://github.com/flipthedream/agentkit/blob/main/nats/nats-server.conf): topic model · Hierarchical subject space for app events and heartbeats. · `nats/nats-server.conf`

### Infra

Docker, compose, and release packaging.

- [Compose files](https://github.com/flipthedream/agentkit/blob/main/docker-compose.yml): orchestration · Development, production, and deploy service definitions. · `docker-compose.yml`
- [Backend images](https://github.com/flipthedream/agentkit/tree/main/backend/Dockerfile): container packaging · Dev and production Dockerfiles for the Go/PocketBase service. · `backend/Dockerfile`
- [Frontend images](https://github.com/flipthedream/agentkit/tree/main/frontend/Dockerfile): container packaging · Dev and production Dockerfiles for the SvelteKit service. · `frontend/Dockerfile`

### CI/CD

Build and publish workflow.

- [Build workflow](https://github.com/flipthedream/agentkit/blob/main/.github/workflows/build.yml): ci pipeline · Builds, validates, and publishes release images to GHCR. · `.github/workflows/build.yml`

## Connections

- SvelteKit app → Runtime config: loads config · Route layout performs universal config loading.
- Runtime config → Config API: fetches runtime config · SSR and browser both rely on backend-supplied deployment URLs.
- Config resolver → Config API: resolves from · Uses backend config when available and falls back when needed.
- SvelteKit app → PocketBase client: uses · UI reads and writes PocketBase through the browser client.
- SvelteKit app → NATS client: connects to · Browser establishes WebSocket access to NATS.
- Runtime config → Config resolver: normalizes · Layout-level config is funneled through the shared resolver.
- Server entry → PocketBase ext: starts · Entrypoint launches the PocketBase extension layer.
- PocketBase ext → PocketBase core: extends · Custom backend behavior is mounted onto PocketBase.
- PocketBase ext → Config API: serves · Backend exposes runtime config for browser and SSR clients.
- PocketBase ext → Hooks & auth: contains · Hooks, auth, and API customizations live here.
- PocketBase ext → NATS boundary: publishes events · Backend integrates with the event bus boundary.
- NATS boundary → NATS server: connects to · Backend publishes and subscribes through NATS.
- NATS server → Subjects: routes by · Broker uses hierarchical subject patterns for messages.
- PocketBase core → SQLite storage: persists in · PocketBase owns the embedded SQLite persistence boundary.
- Server entry → Compose files: runs under · Service startup is orchestrated through compose.
- SvelteKit app → Compose files: runs under · Frontend service is defined by compose environments.
- Server entry → Backend images: packages as · Backend runtime is built from dedicated Dockerfiles.
- SvelteKit app → Frontend images: packages as · Frontend runtime is built from dedicated Dockerfiles.
- Build workflow → Backend images: builds · CI produces backend container images.
- Build workflow → Frontend images: builds · CI produces frontend container images.
- Build workflow → Compose files: validates deploys · Workflow supports image-driven release and deployment flows.