Architecture Overview: shiplog

Repo: shiplog (fictional internal service, shiplog.example) Audience: Engineers joining the team or reviewing a change Generated from: the repository tree, package manifests and source files

What shiplog does

shiplog collects deploy events from CI, groups them into releases, and publishes a changelog page and a Slack summary for each release. It replaces a spreadsheet the team used to fill in by hand.

High-level flow

CI sends a webhook to POST /api/events after each deploy.
The API validates the payload and writes a row to the events table.
A worker picks up new events every 60 seconds, groups them by service and tag, and creates or updates a release.
When a release is marked final, the worker renders the changelog and posts the Slack summary.

Repository layout

Path	Purpose
`apps/api/`	HTTP API (Node 20, Fastify). Webhook intake, auth, read endpoints
`apps/worker/`	Background jobs. Grouping, rendering, Slack posting
`apps/web/`	Changelog site (Next.js, static export)
`packages/db/`	Drizzle schema, migrations and typed queries
`packages/shared/`	Zod schemas shared by API and worker
`infra/`	Docker Compose for local dev, Terraform for staging and prod

Components

API (`apps/api`)

Entry point: src/server.ts registers routes and plugins.
Webhook auth uses an HMAC signature header checked in src/plugins/verify-signature.ts.
Payloads are parsed with the shared DeployEvent schema. Invalid payloads return 422 and are logged, never stored.

Worker (`apps/worker`)

Runs a simple loop in src/index.ts instead of a queue library. Each job is idempotent and keyed on event ID.
jobs/group-events.ts builds releases. Grouping rule: same service, same git tag, within 30 minutes.
jobs/publish-release.ts renders Markdown and calls the Slack webhook. Retries 3 times with backoff.

Database (`packages/db`)

Postgres 16. Three main tables:

events: one row per deploy webhook
releases: one row per grouped release, with status draft or final
release_events: join table

Migrations live in packages/db/migrations and run on API start in dev, and as a separate step in CI for staging and prod.

Web (`apps/web`)

Reads final releases at build time and exports static HTML. A rebuild is triggered by the worker after each publish.

Configuration

All config is read from environment variables in packages/shared/src/env.ts, validated at boot. Required: DATABASE_URL, WEBHOOK_SECRET, SLACK_WEBHOOK_URL. Missing values stop the process with a clear error.

Local development

docker compose up in infra/ starts Postgres. Then pnpm dev runs the API, worker and web app together. Seed data is in packages/db/seed.ts.

Testing

Unit tests sit next to source files as *.test.ts (Vitest).
apps/api/test/webhook.e2e.test.ts posts real signed payloads against a test database.

Known gaps

The worker loop is single-instance. Running two copies can double-post to Slack.
No retention policy on events yet. The table grows forever.
Web rebuild depends on a deploy hook URL that is not documented in the README.