Architecture

🦅 Harpy Eagle · Go Temporal Kafka S3

High-Level Topology

┌─────────────────────────────────────────────────────────────────┐
│                       Client Applications                       │
└─────────────────────────────┬───────────────────────────────────┘
                              │ ConnectRPC HTTP/2 (h2c) :9000
                   ┌──────────▼──────────┐
                   │      API Server     │
                   │  TextToImageService │
                   │   SpriteService     │
                   └──────────┬──────────┘
                              │
               ┌──────────────┼──────────────────────┐
               │              │                       │
          ┌────▼────┐  ┌──────▼──────┐        ┌───────▼───────┐
          │ Database│  │ Kafka Broker│        │ S3 / MinIO      │
          │ (psql)  │  │ (Redpanda)  │        │ (sprite uploads,│
          └─────────┘  └──────┬──────┘        │  optional)      │
                              │ subscribe      └─────────────────┘
                   ┌──────────▼──────────────────────────────────┐
                   │                 Worker Process                │
                   │                                               │
                   │  ┌─────────────────────────────────────────┐ │
                   │  │ TextToImage Kafka consumer                │ │
                   │  │ (legacy import path)                      │ │
                   │  └─────────────────────────────────────────┘ │
                   │                                               │
                   │  ┌─────────────────────────────────────────┐ │
                   │  │ GenerateImageConsumer (Kafka)             │ │
                   │  └──────────────┬──────────────────────────┘ │
                   │                 │ trigger                     │
                   │  ┌──────────────▼──────────────────────────┐ │
                   │  │ Temporal Worker — task queue              │ │
                   │  │ "image-generation"                        │ │
                   │  │ GenerateImageWorkflow                     │ │
                   │  │   1. UpdateStatusActivity   → gRPC        │ │
                   │  │   2. GenerateImageActivity  → ext API     │ │
                   │  │   3. DownloadAndUploadActivity → S3       │ │
                   │  │   4. UpdateResultActivity   → gRPC        │ │
                   │  │   5. PublishCompletionActivity → Kafka    │ │
                   │  └───────────────────────────────────────────┘ │
                   │                                               │
                   │  ┌─────────────────────────────────────────┐ │
                   │  │ Ingestion Temporal Worker (optional)      │ │
                   │  │ task queue "harpy-eagle-image-gen"        │ │
                   │  │ active only when FAL_API_KEY is set       │ │
                   │  │ GenerateEntityImageWorkflow               │ │
                   │  │  fal.ai → download → MinIO → Postgres     │ │
                   │  └───────────────────────────────────────────┘ │
                   └───────────────────────────────────────────────┘
                              │
               ┌──────────────┼──────────────┐
               │              │              │
          ┌────▼────┐  ┌──────▼──────┐  ┌───▼──────────────────┐
          │Database │  │  Kafka      │  │   S3 / MinIO          │
          │(status  │  │ (completion │  │  (generated images,   │
          │ updates)│  │  events)    │  │   entity images)      │
          └─────────┘  └─────────────┘  └───────────────────────┘

The service has two distinct generation paths that share infrastructure (Postgres, Kafka, Temporal, S3/MinIO) but do not share code:

Text-to-image (TextToImageService + imageworker) — the original, fully event-driven pipeline: API publishes to Kafka, worker consumes and drives a Temporal workflow that calls an external image API and writes status back over gRPC.
Entity image ingestion (lib/ingestion) — a second, independently registered Temporal worker/workflow for generating and storing images for external “entities” (e.g. game characters) directly against fal.ai. It has no Kafka involvement and no dedicated gRPC service of its own; it is started only when FAL_API_KEY is set and is invoked by starting its workflow directly against the shared Temporal client.

There is also a sprite asset catalog (SpriteService) that is unrelated to AI generation: it’s a straightforward CRUD service, backed by Postgres, for cataloging pre-existing RPG character-sheet sprite images (uploaded via the CLI, not generated).

Binary Entrypoints

`cmd/api/main.go` — API Server

Serves TextToImageService and SpriteService over HTTP/2 h2c on :9000, plus /health and /info (build metadata) endpoints.

Dependency wiring:

psql.Conn → TextToImageRepo → TextToImageService → gRPC handler
kafka.Conn → Producer[*GenerateImage] → TextToImageService
psql.Conn → SpriteRepo → SpriteService → gRPC handler
(optional) S3 bucket (S3_ENDPOINT) → SpriteService (reserved for a future upload RPC — unused today)

TextToImageService RPCs: ListTextToImages, GetTextToImage, CreateTextToImage, UpdateTextToImage

On CreateTextToImage:

Inserts record with STATUS_STAGED
Publishes GenerateImage proto to Kafka

SpriteService RPCs: ListSprites, GetSprite, CreateSprite (no UpdateSprite/DeleteSprite RPC is exposed yet, though the repository implements Update/Delete). Sprite creation is entirely CLI-driven — the CLI uploads the sheet PNG straight to S3 itself and calls CreateSprite with an already-known storage_url; there is no server-side upload path or AI-generation step involved.

`cmd/worker/main.go` — Worker

Runs, concurrently, in a single process:

TextToImage Kafka consumer — subscribes to the harpyeaglev1.TextToImage topic (group app-1); legacy/import path independent of the generation workflow below.
imageworker Temporal worker — task queue image-generation; registers GenerateImageWorkflow and its activities.
GenerateImageConsumer — subscribes to the harpyeaglev1.GenerateImage Kafka topic (ML_WORKER_TOPIC, group temporal-worker-group); starts a GenerateImageWorkflow run per message via the Temporal client.
ingestion Temporal worker (optional) — task queue harpy-eagle-image-gen; registers GenerateEntityImageWorkflow and its activities. Started only when FAL_API_KEY is set; requires a MinIO/S3 client built from the S3_* vars (mustMinIOClient, distinct from the gocloud.dev/blob bucket the imageworker/API paths use).

Layer Structure

cmd/
  api/main.go        — API server entrypoint, route registration
  worker/main.go      — worker entrypoint, wires both Temporal workers + both Kafka consumers
  *.go                 — Cobra CLI (root, create/get/list/sprite/textimage/builtin-sprites/s3)
lib/
  base/
    service.go, model.go, grpc.go, consumer.go, producer.go
                       — generic Service[T]/Repository[T]/Producer[T] interfaces
                         and a generic ConnectRPC handler shared by both
                         TextToImage and Sprite
  harpyeagle/
    textimage/
      service.go       — TextToImageService (CRUD + Kafka publish)
      consumer.go       — Kafka consumer for the legacy TextToImage topic
      grpc/service.go   — Connect RPC handler adapter
      mocks/            — mockery-generated
    sprite/
      service.go        — SpriteService (CRUD; Create/Update bypass the
                           generic base service — see comments in service.go)
      model.go, interface.go
      grpc/service.go    — Connect RPC handler adapter
    imageworker/
      workflow.go        — GenerateImageWorkflow definition (task queue "image-generation")
      activities.go       — UpdateStatus, GenerateImage, DownloadAndUpload,
                             UpdateResult, PublishCompletion; also the fal.ai
                             queue-polling logic used by GenerateImageActivity
      consumer.go          — Kafka consumer that starts a workflow per GenerateImage message
    blobstore/
      blobstore.go         — gocloud.dev/blob S3-compatible bucket helper
                              shared by the API server and imageworker
  imagegen/
    falai.go, generator.go — fal.ai client used by the ingestion pipeline (ImageGenerator interface)
  ingestion/
    workflow.go            — GenerateEntityImageWorkflow (task queue "harpy-eagle-image-gen")
    activities.go            — BuildPrompt, GenerateImage (via imagegen.ImageGenerator),
                                DownloadImage, UploadToStorage (minio-go), PersistEntityImage,
                                SetActiveImage — writes directly to entity_images via database/sql
    worker.go                — registers the workflow + activities on a Temporal worker
  quota/
    quota.go               — daily generation quota tracker (image_generation_quota table);
                              defined but not currently wired into any service or handler
  kafka/
    conn.go, consumer.go, producer.go — franz-go based Kafka client used by cmd/worker and cmd/api
  repo/
    conn.go               — DB connection + goose migrations (embedded, run on startup)
    textimage.go            — texttoimages CRUD
    entity_image.go          — entity_images CRUD (not currently called outside ingestion/activities.go's raw SQL)
    sprite.go                — sprites CRUD
  schemas/
    harpyeagle/v1/...       — generated Go code from schemas/*.proto (buf)
schemas/
  harpyeagle/v1/
    textimage.proto         — TextToImage message + status enum
    generate.proto            — GenerateImage wrapper message (text-to-image only; image-to-image is defined but unimplemented)
    sprite.proto               — Sprite message
    services/
      textimage.proto          — TextToImageService RPC definitions
      sprite.proto              — SpriteService RPC definitions

External Dependencies

Service	Purpose	Config
PostgreSQL	Persistent storage (texttoimages, entity_images, sprites, image_generation_quota)	`DATABASE_URL`
Kafka / Redpanda	Job queue + completion events	`KAFKA_BROKERS`
Temporal	Workflow orchestration (two independently registered workers)	`TEMPORAL_HOST`
MinIO / S3	Generated/uploaded image storage	`S3_*` vars
fal.ai	Image generation backend, used by both the text-to-image path (as one possible `IMAGE_API_ENDPOINT`) and the entity-image ingestion path	`FAL_API_KEY`, `IMAGE_API_ENDPOINT`/`IMAGE_API_TOKEN`

Temporal Workflow: `GenerateImageWorkflow`

Task queue: image-generation Retry policy: 3 attempts, 5s initial interval Activity timeout: 15 minutes per activity

Step	Activity	Description
1	`UpdateStatusActivity`	gRPC call to API: set status → `STATUS_BUILDING`
2	`GenerateImageActivity`	HTTP POST to `IMAGE_API_ENDPOINT` (fal.ai-compatible; handles both fal.ai’s async queue response and a plain synchronous JSON response) → temporary image URL
3	`DownloadAndUploadActivity`	Fetch image from temp URL, upload to S3/MinIO → permanent URL. If no S3 bucket is configured, falls back to the source URL unchanged.
4	`UpdateResultActivity`	gRPC call: set status → `STATUS_COMPLETED` + URL (or `STATUS_FAILED` + error)
5	`PublishCompletionActivity`	Kafka publish to completion topic; best-effort, only on success, errors logged but non-fatal

If step 2 or 3 fails, the workflow still runs step 4 to persist STATUS_FAILED before returning an error.

Temporal Workflow: `GenerateEntityImageWorkflow` (ingestion)

Task queue: harpy-eagle-image-gen Retry policy: 3 attempts, 1s initial interval, 2x backoff, 30s max interval

Step	Activity	Description
1	`BuildPromptActivity`	Assembles a prompt from entity attributes, or passes through a caller-supplied custom prompt
2	`GenerateImageActivity`	Calls the configured `imagegen.ImageGenerator` (fal.ai)
3	`DownloadImageActivity`	Downloads the image bytes from the provider’s temporary URL
4	`UploadToStorageActivity`	Uploads to S3/MinIO via `minio-go`
5	`PersistEntityImageActivity`	Inserts a row into `entity_images`
6	`SetActiveImageActivity`	Optional; if `SetAsActive` was requested, clears other active flags for the entity and marks this image active. Failure here is non-fatal.

Event Flow: Text-to-Image Generation

Client → API: CreateTextToImage
  → DB: INSERT status=STATUS_STAGED
  → Kafka: Publish GenerateImage message (topic harpyeaglev1.GenerateImage)

Kafka → Worker: GenerateImageConsumer
  → Temporal: StartWorkflow("generate-image-{uuid}")

Temporal → Worker: GenerateImageWorkflow
  → gRPC → API: UpdateTextToImage(STATUS_BUILDING)
  → IMAGE_API_ENDPOINT (fal.ai or compatible): POST → temp URL
  → S3: upload → permanent URL (or pass through temp URL if S3 unset)
  → gRPC → API: UpdateTextToImage(STATUS_COMPLETED, url) or (STATUS_FAILED, error)
  → Kafka: Publish completion event (harpyeagle.texttoimages.completed) [best-effort]

Client polls: GetTextToImage(uuid) until status != STATUS_BUILDING

CLI (`cmd/`)

A Cobra-based CLI (built into the same binary as main.go) talks to the API server over gRPC:

create/get/list subcommands for texttoimage and sprite
sprite create --file ... --name ... — upload a single sprite sheet PNG to S3 and register it
sprite sprites-bulk --dir ... — bulk-import every .png in a directory as a sprite
builtin-sprites — seeds the catalog with a hard-coded roster of vendored RPG character-sheet assets (assets/builtin-sprites/*.png), matching a companion game engine’s (“goblin-shark”) built-in demo roster slot-for-slot

Architecture

High-Level Topology

Binary Entrypoints

cmd/api/main.go — API Server

cmd/worker/main.go — Worker