_Phalanx (backend)

What is this service?

This package is the HTTP API for _Phalanx: it powers squad data, wallet-linked auth, Pacifica-facing helpers (headers, jobs), frontline/insight routes, and storage-backed features via PostgreSQL and Supabase. The Next.js website calls this API using the base URL configured as NEXT_APP_API_URL (see website/README.md).

Tech stack

• Runtime: Node.js, TypeScript
• HTTP: Express 4
• Config & validation: dotenv, envalid
• Database: PostgreSQL via postgres (SQL client)
• Auth: JWT (jsonwebtoken), bcryptjs, TweetNaCl (wallet/signature flows)
• Storage / BaaS: Supabase JS client (@supabase/supabase-js)
• Logging: pino / pino-http
• Dev: ts-node-dev (hot reload), tsx for scripts

Production builds use tsc; Vercel can run the app as serverless (server.ts default export) while local development uses a long-lived process (src/index.ts).

Environment variables

Create backend/.env in this directory (loaded via dotenv in src/utils/env/envConfig.ts). All variables below are validated at startup.

Variable	Purpose
NODE_ENV	development, production, or test.
HOST	Bind address (default 0.0.0.0; local dev often localhost). Ignored in typical Vercel serverless runs.
PORT	Listen port (default 3000).
CORS_ORIGIN	Allowed browser origin(s) for credentialed requests. Comma-separated if multiple, e.g. http://localhost:3001,https://app.example.com. Must include your website origin.
DATABASE_URL	PostgreSQL connection string (required for real runs; migrations/init use it).
AUTH_SECRET	Secret for JWT/HMAC signing. Must be at least 16 characters when auth features run.
SUPABASE_URL	Supabase project URL (e.g. storage).
ANON_KEY	Supabase anon key (passed to the Supabase client in supabaseAdmin.ts).
JOB_SECRET	If set, /api/jobs/* requires Authorization: Bearer <secret> or x-job-secret.
CRON_SECRET	Optional; aligns with Vercel Cron Authorization: Bearer when securing scheduled jobs.
ELFA_API_KEY	Optional; used by insight/Elfa helpers when configured.
PACIFICA_API_KEY	Optional; used for Pacifica API requests that need a key (see pacificaHeaders.ts).

Script-only (not in envConfig): yarn create:pacifica-api-key reads PACIFICA_WALLET_PRIVATE_KEY from the environment for that CLI script.

Install and run

Prerequisites: Node.js (LTS recommended), Yarn 1.x, a reachable PostgreSQL instance, and (if you use them) Supabase project keys.

yarn install --frozen-lockfile

Copy or create .env with at least DATABASE_URL, AUTH_SECRET (≥16 chars), CORS_ORIGIN matching your frontend origin, and SUPABASE_URL / ANON_KEY if those features are used.

Development (reload on change):

yarn dev

The server listens at http://<HOST>:<PORT> (defaults: host from env, port 3000). Point the website’s NEXT_APP_API_URL at that base URL without a trailing /api (the client adds /api/...).

Production-style run:

yarn build
yarn start

Other commands

Command	Purpose
yarn create:pacifica-api-key	Helper script for Pacifica API key flow (requires PACIFICA_WALLET_PRIVATE_KEY).
yarn vercel-dev	Local Vercel dev integration.
yarn format	Prettier on src/**/*.ts.

API surface (overview)

Mounted under /api (see src/server.ts):

• /api — health
• /api/auth — authentication
• /api/squads — squads
• /api/wallet — wallet-related endpoints
• /api/jobs — scheduled/job endpoints (protect with JOB_SECRET when set)
• /api/insight — insight/Elfa integration
• /api/frontline — frontline data

Align CORS, port, and the website env so the browser can call this API without cross-origin or wrong-host issues.