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}` :
@@ -0,0 +1,43 @@
+# @blade-and-brawn/portal
+
+Admin portal for Blade & Brawn — manage the level calculator's standards
+configs/datasets, review apparel orders/products, and inspect activity events.
+Talks to `apps/api` via a typed [`@elysia/eden`](https://elysiajs.com/eden/overview.html)
+client.
+
+## Stack
+
+- SvelteKit 5 + Vite, deployed with `svelte-adapter-bun`
+- Tailwind 4 + daisyUI
+- `jose` for verifying the auth JWT cookie server-side
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `PUBLIC_API_URL` | Base URL of `apps/api`, used by the Eden client (`src/lib/api.ts`) |
+| `AUTH_SECRET` | JWT verification secret — must match `AUTH_SECRET` in `apps/api` |
+
+## Auth
+
+`src/hooks.server.ts` gates every route except `/login` behind a valid `auth`
+JWT cookie (issued by the API's `/auth/login` endpoint). Requests without one
+are redirected to `/login`.
+
+## Scripts
+
+Run from the repo root as `bun run dev:portal` / `bun run build:portal`, or
+from this directory:
+
+- `dev` — Vite dev server
+- `build` — production build
+- `preview` — preview a production build locally
+- `check` / `check:watch` — `svelte-check` type checking
+
+## Structure
+
+- `src/routes/(app)/calculator/` — standards configs and datasets
+- `src/routes/(app)/apparel/` — Printful/Webflow orders and products
+- `src/routes/(app)/activity/` — activity events
+- `src/routes/login/` — login page
+- `src/lib/api.ts` — Eden client used to call `apps/api`