80 lines
3.4 KiB
Markdown
80 lines
3.4 KiB
Markdown
# @blade-and-brawn/api
|
|
|
|
ElysiaJS backend for Blade & Brawn: the level calculator endpoint, Printful/Webflow
|
|
commerce sync, and the admin API used by `apps/portal`.
|
|
|
|
## Stack
|
|
|
|
- [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`)
|
|
|
|
## 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.
|
|
|
|
### Running migrations/seed against production
|
|
|
|
The deployed image only contains the compiled binary (see `Dockerfile`) — no
|
|
source, no `bun_modules`, no migration files — so these can't be run from
|
|
`fly ssh console` on the API app itself. Instead, use `migrate.sh` at the repo
|
|
root, which tunnels to the Postgres app (`blade-and-brawn-db`, legacy/unmanaged
|
|
Fly Postgres) via `fly proxy`, fetches the production `DATABASE_URL` for you,
|
|
and runs the scripts against it:
|
|
|
|
```bash
|
|
./migrate.sh migrate # db:migrate:latest (default if no argument given)
|
|
./migrate.sh seed # db:seed
|
|
./migrate.sh both # both, in order
|
|
```
|
|
|
|
Both underlying scripts prompt for a `y/N` confirmation before touching the
|
|
database, and `db:seed` is idempotent (skips seeding if the default rows
|
|
already exist). If the tunneled connection fails on TLS, legacy Postgres
|
|
sometimes needs `?sslmode=disable` appended — edit `migrate.sh` if so.
|