# marcisebestyen/relay architecture

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

- Interactive diagram: https://gitdiagram.com/marcisebestyen/relay
- Repository: https://github.com/marcisebestyen/relay

## Overview

Relay is an early-stage background-job orchestration platform. The evidenced runtime workflow is starting the API command: the CLI loads and validates configuration, opens PostgreSQL, builds the HTTP router, and serves health/readiness endpoints. The README also documents database migration operations. Although configuration includes worker settings, the supplied tree shows no worker runtime or job-submission/execution implementation, so those stages are not represented. Unsampled implementation details are omitted.

Main entry points: [`relay-backend/internal/cli/api.go`](https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/cli/api.go) (API command), [`relay-backend/internal/cli/cli.go`](https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/cli/cli.go) (Command setup), [`relay-backend/internal/cli/migrate.go`](https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/cli/migrate.go) (Migration commands), [`relay-backend/internal/api/router.go`](https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/api/router.go) (Route registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Process entry"]
  node_relaycmd["Relay CLI<br/>[main.go]"]
  node_commands["Command setup<br/>[cli.go]"]
  node_configuration["Configuration<br/>[config.go]"]
  node_validation["Role validation<br/>[validate.go]"]
  node_logging["Logging<br/>[logging.go]"]
end

subgraph group_http["HTTP service"]
  node_api_command["API command<br/>[api.go]"]
  node_server["HTTP server<br/>[serve.go]"]
  node_router["Route registration<br/>[router.go]"]
  node_middleware["Request middleware<br/>[middleware.go]"]
  node_errors["Error responses<br/>[errors.go]"]
end

subgraph group_storage["Persistence"]
  node_database[("PostgreSQL pool<br/>[db.go]")]
  node_migration_command["Migration commands<br/>[migrate.go]"]
  node_migrator["Migration runner<br/>[migrate.go]"]
  node_migration_files["Migration files<br/>[migrations.go]"]
  node_postgres[("PostgreSQL")]
end

node_operator(("Operator"))

node_operator -->|"runs command"| node_relaycmd
node_relaycmd -->|"executes"| node_commands
node_commands -->|"loads settings"| node_configuration
node_commands -->|"validates role"| node_validation
node_commands -->|"creates logger"| node_logging
node_commands -->|"registers"| node_api_command
node_operator -->|"runs API"| node_api_command
node_api_command -->|"opens pool"| node_database
node_api_command -->|"builds routes"| node_router
node_api_command -->|"serves handler"| node_server
node_router -->|"registers"| node_middleware
node_router -->|"pings readiness"| node_database
node_router -->|"writes envelopes"| node_errors
node_api_command -->|"registers"| node_migration_command
node_operator -->|"runs migration"| node_migration_command
node_migration_command -->|"opens pool"| node_database
node_migration_command -->|"creates runner"| node_migrator
node_migration_command -->|"loads embedded files"| node_migration_files
node_migrator -->|"applies SQL"| node_postgres
node_database -->|"connects"| node_postgres

click node_relaycmd "https://github.com/marcisebestyen/relay/blob/main/relay-backend/cmd/relay/main.go"
click node_commands "https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/cli/cli.go"
click node_configuration "https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/config/config.go"
click node_validation "https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/config/validate.go"
click node_logging "https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/observability/logging/logging.go"
click node_api_command "https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/cli/api.go"
click node_server "https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/api/serve.go"
click node_router "https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/api/router.go"
click node_middleware "https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/api/middleware.go"
click node_errors "https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/api/errors.go"
click node_database "https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/persistence/db/db.go"
click node_migration_command "https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/cli/migrate.go"
click node_migrator "https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/persistence/migrate/migrate.go"
click node_migration_files "https://github.com/marcisebestyen/relay/blob/main/relay-backend/migrations/migrations.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_relaycmd,node_commands,node_configuration,node_validation,node_logging toneBlue
class node_api_command,node_server,node_router,node_middleware,node_errors toneAmber
class node_database,node_migration_command,node_migrator,node_migration_files,node_postgres toneMint
class node_operator toneIndigo
```

## Components

### Process entry

- [Relay CLI](https://github.com/marcisebestyen/relay/blob/main/relay-backend/cmd/relay/main.go): `relay-backend/cmd/relay/main.go`
- [Command setup](https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/cli/cli.go): `relay-backend/internal/cli/cli.go`
- [Configuration](https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/config/config.go): `relay-backend/internal/config/config.go`
- [Role validation](https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/config/validate.go): `relay-backend/internal/config/validate.go`
- [Logging](https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/observability/logging/logging.go): `relay-backend/internal/observability/logging/logging.go`

### HTTP service

- [API command](https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/cli/api.go): `relay-backend/internal/cli/api.go`
- [HTTP server](https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/api/serve.go): `relay-backend/internal/api/serve.go`
- [Route registration](https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/api/router.go): `relay-backend/internal/api/router.go`
- [Request middleware](https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/api/middleware.go): `relay-backend/internal/api/middleware.go`
- [Error responses](https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/api/errors.go): `relay-backend/internal/api/errors.go`

### Persistence

- [PostgreSQL pool](https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/persistence/db/db.go): `relay-backend/internal/persistence/db/db.go`
- [Migration commands](https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/cli/migrate.go): `relay-backend/internal/cli/migrate.go`
- [Migration runner](https://github.com/marcisebestyen/relay/blob/main/relay-backend/internal/persistence/migrate/migrate.go): `relay-backend/internal/persistence/migrate/migrate.go`
- [Migration files](https://github.com/marcisebestyen/relay/blob/main/relay-backend/migrations/migrations.go): `relay-backend/migrations/migrations.go`
- **PostgreSQL**

### Other components

- **Operator**

## Connections

- Operator → Relay CLI: runs command (evidence: `README.md`)
- Relay CLI → Command setup: executes (evidence: `relay-backend/cmd/relay/main.go`)
- Command setup → Configuration: loads settings (evidence: `relay-backend/internal/cli/cli.go`)
- Command setup → Role validation: validates role (evidence: `relay-backend/internal/cli/cli.go`)
- Command setup → Logging: creates logger (evidence: `relay-backend/internal/cli/cli.go`)
- Command setup → API command: registers (evidence: `relay-backend/internal/cli/cli.go`)
- Operator → API command: runs API (evidence: `README.md`)
- API command → PostgreSQL pool: opens pool (evidence: `relay-backend/internal/cli/api.go`)
- API command → Route registration: builds routes (evidence: `relay-backend/internal/cli/api.go`)
- API command → HTTP server: serves handler (evidence: `relay-backend/internal/cli/api.go`)
- Route registration → Request middleware: registers (evidence: `relay-backend/internal/api/router.go`)
- Route registration → PostgreSQL pool: pings readiness (evidence: `relay-backend/internal/api/router.go`)
- Route registration → Error responses: writes envelopes (evidence: `relay-backend/internal/api/router.go`)
- API command → Migration commands: registers
- Operator → Migration commands: runs migration (evidence: `README.md`)
- Migration commands → PostgreSQL pool: opens pool (evidence: `relay-backend/internal/cli/migrate.go`)
- Migration commands → Migration runner: creates runner (evidence: `relay-backend/internal/cli/migrate.go`)
- Migration commands → Migration files: loads embedded files (evidence: `relay-backend/internal/cli/migrate.go`)
- Migration runner → PostgreSQL: applies SQL (evidence: `relay-backend/internal/persistence/migrate/migrate.go`)
- PostgreSQL pool → PostgreSQL: connects (evidence: `relay-backend/internal/persistence/db/db.go`)
