From 87987fcf176f35380002cddb4ab127d39542b9f6 Mon Sep 17 00:00:00 2001
From: Lewis Tierney <lewis@widgetbot.io>
Date: Mon, 18 May 2026 13:34:04 +0100
Subject: [PATCH] docs: add TechDocs scaffold for Backstage

---
 catalog-info.yaml | 21 +++++++++++
 docs/index.md     | 95 +++++++++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml        |  8 ++++
 3 files changed, 124 insertions(+)
 create mode 100644 catalog-info.yaml
 create mode 100644 docs/index.md
 create mode 100644 mkdocs.yml

diff --git a/catalog-info.yaml b/catalog-info.yaml
new file mode 100644
index 0000000..beb5bcf
--- /dev/null
+++ b/catalog-info.yaml
@@ -0,0 +1,21 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: hookla
+  description: Webhook relay service - converts provider webhooks into Discord embeds.
+  annotations:
+    github.com/project-slug: widgetbot-io/hookla
+    backstage.io/techdocs-ref: dir:.
+    backstage.io/kubernetes-id: hookla
+  links:
+    - url: https://github.com/widgetbot-io/hookla
+      title: Source
+      icon: github
+  tags:
+    - widgetbot
+    - scala
+spec:
+  type: service
+  lifecycle: production
+  owner: group:widgetbot
+  system: widgetbot
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..d5b0e4b
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,95 @@
+# hookla
+
+`hookla` is WidgetBot's webhook relay service. It receives webhooks from
+third-party providers (GitHub, GitLab, Sonarr, and others), converts the
+payloads into formatted Discord embeds, and posts them to a configured Discord
+webhook.
+
+## What it does
+
+Each provider integration has a stored `ProviderSettings` row keyed by a unique
+token. An external provider sends its webhook to `/process/<token>`; hookla
+looks up the settings, identifies the provider, decodes the event payload, and
+dispatches it to the matching handler. The handler builds a Discord embed and
+sends it to the linked Discord webhook.
+
+Supported inbound providers:
+
+- GitHub (push, issue, check run, create, delete events)
+- GitLab (push, issue, job, note, tag events)
+- Sonarr (grab, download, rename, test events)
+- Radarr and Ombi (handlers present)
+
+## Architecture
+
+- **Language / runtime**: Scala 2.13, runs on the JVM (Java 11).
+- **HTTP layer**: [Finch](https://github.com/finagle/finch) endpoints served by
+  Finagle's `Http.server` ([twitter-server](https://github.com/twitter/twitter-server)).
+- **Dependency injection**: [MacWire](https://github.com/softwaremill/macwire)
+  compile-time wiring (see `HooklaModules`).
+- **Database**: PostgreSQL, accessed with [Quill](https://getquill.io/)
+  (`quill-async-postgres`). Schema migrations are managed by
+  [Flyway](https://flywaydb.org/) and applied automatically on startup.
+- **JSON**: [circe](https://circe.github.io/circe/) for decoding inbound
+  payloads and encoding Discord output.
+- **Discord output**: embeds are built with [AckCord](https://github.com/Katrix/AckCord)
+  data types and posted to `discord.com/api/webhooks/...`.
+
+### Request flow
+
+```
+provider --> POST /process/{token} --> WebhookController
+          --> ProviderSettingsService (token lookup)
+          --> decode payload (circe)
+          --> MainHandler --> provider handler --> Discord embed
+          --> DiscordMessageService --> Discord webhook
+```
+
+`GET /process/{token}` returns the stored provider settings for a token.
+
+## Key directories
+
+- `src/main/scala/venix/hookla/` — application root (`App`, `HooklaConfig`, `HooklaModules`).
+- `src/main/scala/venix/hookla/controllers/` — Finch HTTP endpoints (`WebhookController`).
+- `src/main/scala/venix/hookla/handlers/` — per-provider event handlers (`github/`, `gitlab/`, `sonarr/`, `radarr/`, `ombi/`).
+- `src/main/scala/venix/hookla/types/` — payload models and provider definitions.
+- `src/main/scala/venix/hookla/services/` — database and Discord services.
+- `src/main/scala/venix/hookla/models/` — Quill-mapped database models.
+- `src/main/resources/db/migration/` — Flyway SQL migrations.
+- `src/main/resources/application.conf` — HOCON configuration.
+
+## Configuration
+
+Configuration is loaded from `application.conf` via `circe-config`. It is driven
+by environment variables:
+
+- `ENV` — environment name (defaults to `development`).
+- `INTERNAL_PORT` — HTTP listen port (defaults to `8443`).
+- `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USER`, `DB_PASSWORD` — PostgreSQL
+  connection details (used for both the Quill context and Flyway, with
+  `sslmode=require`).
+
+## Running locally
+
+Requires a JDK (11) and sbt. A reachable PostgreSQL database is needed; Flyway
+migrations run automatically on boot.
+
+```sh
+# set the DB_* env vars first
+sbt run
+```
+
+The server logs `Server started on port <port>` once ready.
+
+## Deployment
+
+`hookla` ships as a Docker image. The GitHub Actions workflow
+(`.github/workflows/scala.yml`) runs `sbt clean compile docker:stage` and builds
+/ pushes the image to GitHub Container Registry on pushes to `master` and on
+tags.
+
+- Image: `ghcr.io/widgetbot-io/hookla`
+- Base image: `gcr.io/distroless/java:11`
+- Exposed port: `8443`
+- Tags: `latest` on `v*` tags, `staging` on `master`, plus branch / PR / SHA /
+  semver tags.
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..6801821
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,8 @@
+site_name: hookla
+docs_dir: docs
+
+nav:
+  - Overview: index.md
+
+plugins:
+  - techdocs-core