Add documenation of all apps/packages

2026-07-31 09:47:39 -04:00
parent e299d1e5cc
commit 887e9ea78c
10 changed files with 354 additions and 35 deletions
@@ -1,13 +1,59 @@
-# backend
+# @blade-and-brawn/api

-To install dependencies:
+ElysiaJS backend for Blade & Brawn: the level calculator endpoint, Printful/Webflow
+commerce sync, and the admin API used by `apps/portal`.

-```bash
-bun install
-```
+## Stack

-To run:
+- [ElysiaJS](https://elysiajs.com) on Bun, run in `node:cluster` worker processes
+  (see `src/index.ts`; worker count is `min(CPU cores, MAX_WORKER_COUNT)`)
+- PostgreSQL via [Kysely](https://kysely.dev)
+- JWT cookie auth (`@elysia/jwt`)

-```bash
-bun run dev
-```
+## Environment variables
+
+All required unless noted. See `src/util.ts` for the source of truth.
+
+| Variable | Purpose |
+| --- | --- |
+| `PRINTFUL_AUTH` | Printful API token |
+| `PRINTFUL_STORE_ID` | Printful store ID |
+| `PRINTFUL_WEBHOOK_SECRET` | Shared secret appended to the Printful webhook URL |
+| `WEBFLOW_SITE_ID` | Webflow site ID |
+| `WEBFLOW_COLLECTION_PRODUCTS_ID` | Webflow CMS collection ID for products |
+| `WEBFLOW_COLLECTION_SKUS_ID` | Webflow CMS collection ID for SKUs |
+| `WEBFLOW_AUTH` | Webflow API token |
+| `WEBFLOW_WEBHOOK_SECRET` | Webflow webhook signing secret |
+| `AUTH_SECRET` | JWT signing secret (must match `AUTH_SECRET` in `apps/portal`) |
+| `ADMIN_PASSWORD` | sha256 hex digest checked against on `/auth/login` |
+| `DATABASE_URL` | Postgres connection string |
+| `DATABASE_POOL_MAX` | Postgres pool size |
+| `MAX_WORKER_COUNT` | Upper bound on cluster worker processes |
+| `NODE_ENV` | optional, defaults to `development` |
+| `LOG_LEVEL` | optional, defaults to `info` |
+
+## Scripts
+
+Run from the repo root as `bun run dev:api` / `bun run build:api`, or from
+this directory:
+
+- `dev` — run with hot reload
+- `start` — run without hot reload
+- `build` — compile to a standalone binary at `dist/server`
+- `db:migrate:latest` / `:rollback` / `:up` / `:down` / `:reset` — Kysely migrations (`src/database/migrations`)
+- `db:types:gen` — regenerate `src/database/out/db.d.ts` from the database schema
+- `db:seed` — run `src/database/seed.ts` (loads `seed-data/standards-config.json`)
+
+## Structure
+
+- `src/server.ts` — Elysia app: routes, plugins, error handling
+- `src/services/` — calculator, standards, commerce, events, event queue
+- `src/database/` — Kysely instance, migrations, seed data
+- `src/scripts/` — one-off scripts (e.g. `register-webhooks.ts` to (re)register
+  Printful/Webflow webhooks against this API's domain)
+
+## Deployment
+
+Deployed to Fly.io (`fly.toml`). After a domain changes, re-run
+`src/scripts/register-webhooks.ts` with production env vars to point Printful's
+and Webflow's webhooks at the new domain — see issue #3 for the full checklist.
@@ -1,7 +1,9 @@
 import { Printful, PrintfulClient, PrintfulError, Webflow, WebflowClient, WebflowError } from "@blade-and-brawn/commerce";
 import { env } from "../util";

-const DOMAIN = "dev.api.bladeandbrawn.com";
+const DOMAIN = env.NODE_ENV === "development" ?
+    "dev.api.bladeandbrawn.com" :
+    "api.bladeandbrawn.com";

 const PRINTFUL_WEBHOOK_URL = env.NODE_ENV === "development" ?
    `http://${DOMAIN}/webhooks/printful?secret=${env.PRINTFUL_WEBHOOK_SECRET}` :