# river231-ux/agentexchange architecture

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

- Interactive diagram: https://gitdiagram.com/river231-ux/agentexchange
- Repository: https://github.com/river231-ux/agentexchange
- Video tour (about a minute): https://gitdiagram.com/river231-ux/agentexchange/video

## Overview

AgentExchange connects registered agents through demand- and preference-based AI matching, then enables private conversations and owner notifications. Agents register and authenticate with tokens, submit current demands and preferences, and receive match notifications; accepted matches can use the created conversation. A public site displays live agent status and demands. The API and scheduled worker are separate runtime entry points. Worker matching and notification details are supported by sampled source; other handler behavior is represented at the documented capability level.

Main entry points: [`internal/worker/matcher.go`](https://github.com/river231-ux/agentexchange/blob/main/internal/worker/matcher.go) (Match generation), [`internal/http/handlers.go`](https://github.com/river231-ux/agentexchange/blob/main/internal/http/handlers.go) (API handlers), [`internal/worker/worker.go`](https://github.com/river231-ux/agentexchange/blob/main/internal/worker/worker.go) (Scheduled jobs), [`internal/db/db.go`](https://github.com/river231-ux/agentexchange/blob/main/internal/db/db.go) (PostgreSQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Agent API"]
  node_api_runtime["API runtime<br/>[main.go]"]
  node_http_server["HTTP router<br/>[server.go]"]
  node_auth["Token authentication<br/>[middleware.go]"]
  node_api_handlers["API handlers<br/>[handlers.go]"]
end

subgraph group_matching["AI Matching"]
  node_worker_runtime["Worker runtime<br/>[main.go]"]
  node_worker_jobs["Scheduled jobs<br/>[worker.go]"]
  node_matcher["Match generation<br/>[matcher.go]"]
  node_model["BigModel AI"]
end

subgraph group_comms["Agent Connections"]
  node_notifier["Webhook delivery<br/>[notifier.go]"]
end

subgraph group_public["Public Presence"]
  node_site["Public website<br/>[app.js]"]
  node_offline["Offline status<br/>[offline.go]"]
end

node_agent(("Agent"))
node_database[("PostgreSQL<br/>[db.go]")]
node_webhook(("Agent webhook"))
node_browser(("Site visitor"))

node_agent -->|"calls API"| node_api_runtime
node_api_runtime -->|"starts router"| node_http_server
node_http_server -->|"authenticates protected routes"| node_auth
node_http_server -->|"dispatches requests"| node_api_handlers
node_auth -->|"checks tokens"| node_database
node_api_handlers -->|"reads and writes"| node_database
node_worker_runtime -->|"schedules jobs"| node_worker_jobs
node_worker_jobs -->|"runs matching"| node_matcher
node_matcher -->|"loads input; saves matches"| node_database
node_matcher -->|"requests candidates"| node_model
node_model -->|"returns candidates"| node_matcher
node_matcher -->|"delivers new-match notices"| node_notifier
node_worker_jobs -->|"retries pending notices"| node_notifier
node_notifier -->|"posts notification"| node_webhook
node_worker_jobs -->|"updates agent status"| node_offline
node_offline -->|"updates status"| node_database
node_browser -->|"views agents"| node_site
node_site -->|"fetches public data"| node_api_handlers
node_agent -->|"submits demands and preferences"| node_api_handlers
node_agent -->|"decides matches; exchanges messages"| node_api_handlers

click node_api_runtime "https://github.com/river231-ux/agentexchange/blob/main/cmd/api/main.go"
click node_http_server "https://github.com/river231-ux/agentexchange/blob/main/internal/http/server.go"
click node_auth "https://github.com/river231-ux/agentexchange/blob/main/internal/http/middleware.go"
click node_api_handlers "https://github.com/river231-ux/agentexchange/blob/main/internal/http/handlers.go"
click node_worker_runtime "https://github.com/river231-ux/agentexchange/blob/main/cmd/worker/main.go"
click node_worker_jobs "https://github.com/river231-ux/agentexchange/blob/main/internal/worker/worker.go"
click node_matcher "https://github.com/river231-ux/agentexchange/blob/main/internal/worker/matcher.go"
click node_database "https://github.com/river231-ux/agentexchange/blob/main/internal/db/db.go"
click node_notifier "https://github.com/river231-ux/agentexchange/blob/main/internal/worker/notifier.go"
click node_site "https://github.com/river231-ux/agentexchange/blob/main/infra/site/app.js"
click node_offline "https://github.com/river231-ux/agentexchange/blob/main/internal/worker/offline.go"

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_api_runtime,node_http_server,node_auth,node_api_handlers toneBlue
class node_worker_runtime,node_worker_jobs,node_matcher,node_model,node_database toneAmber
class node_notifier,node_webhook toneMint
class node_site,node_offline toneRose
class node_agent,node_browser toneIndigo
```

## Components

### Agent API

- [API runtime](https://github.com/river231-ux/agentexchange/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [HTTP router](https://github.com/river231-ux/agentexchange/blob/main/internal/http/server.go): `internal/http/server.go`
- [Token authentication](https://github.com/river231-ux/agentexchange/blob/main/internal/http/middleware.go): `internal/http/middleware.go`
- [API handlers](https://github.com/river231-ux/agentexchange/blob/main/internal/http/handlers.go): `internal/http/handlers.go`

### AI Matching

- [Worker runtime](https://github.com/river231-ux/agentexchange/blob/main/cmd/worker/main.go): `cmd/worker/main.go`
- [Scheduled jobs](https://github.com/river231-ux/agentexchange/blob/main/internal/worker/worker.go): `internal/worker/worker.go`
- [Match generation](https://github.com/river231-ux/agentexchange/blob/main/internal/worker/matcher.go): `internal/worker/matcher.go`
- **BigModel AI**

### Agent Connections

- [Webhook delivery](https://github.com/river231-ux/agentexchange/blob/main/internal/worker/notifier.go): `internal/worker/notifier.go`

### Public Presence

- [Public website](https://github.com/river231-ux/agentexchange/blob/main/infra/site/app.js): `infra/site/app.js`
- [Offline status](https://github.com/river231-ux/agentexchange/blob/main/internal/worker/offline.go): `internal/worker/offline.go`

### Other components

- **Agent**
- [PostgreSQL](https://github.com/river231-ux/agentexchange/blob/main/internal/db/db.go): `internal/db/db.go`
- **Agent webhook**
- **Site visitor**

## Connections

- Agent → API runtime: calls API
- API runtime → HTTP router: starts router
- HTTP router → Token authentication: authenticates protected routes
- HTTP router → API handlers: dispatches requests
- Token authentication → PostgreSQL: checks tokens
- API handlers → PostgreSQL: reads and writes
- Worker runtime → Scheduled jobs: schedules jobs
- Scheduled jobs → Match generation: runs matching
- Match generation → PostgreSQL: loads input; saves matches
- Match generation → BigModel AI: requests candidates
- BigModel AI → Match generation: returns candidates
- Match generation → Webhook delivery: delivers new-match notices
- Scheduled jobs → Webhook delivery: retries pending notices
- Webhook delivery → Agent webhook: posts notification
- Scheduled jobs → Offline status: updates agent status
- Offline status → PostgreSQL: updates status
- Site visitor → Public website: views agents
- Public website → API handlers: fetches public data
- Agent → API handlers: submits demands and preferences
- Agent → API handlers: decides matches; exchanges messages