Developers & platform
This page is for running the repo, integrating with the BFF, and hardening the stack. For how ArcLogic thinks about money and what the engine numbers mean, start with Philosophy and Engines.
1. Local setup
From the repository root, install dependencies and start the web workspace. The app is a Next.js App Router project under apps/web.
npm install npm run dev # or: npm run dev -w @arclogic/web
Copy .env.example to apps/web/.env.local and fill values. Never commit secrets. See the repo INTEGRATIONS.md for Clerk, Vercel, Stripe, and Sentry per-environment wiring.
- Clerk — required for any signed-in experience: publishable and secret keys.
- ARCLOGIC_BROKER=mock — in-memory book with no external credentials.
- Tradier —
TRADIER_ACCESS_TOKENandTRADIER_BASE_URL(sandbox for paper) when ready. - Polygon —
POLYGON_API_KEY(orMASSIVE_API_KEY) for quotes as implemented in the BFF.
Use Sign up in the app or /sign-up. In Clerk, allow origins for localhost:3000 and your production domain. For deploys, a typical Vercel project uses the monorepo root with apps/web as the app root; mirror env vars to match test vs live keys (see INTEGRATIONS.md).
2. BFF API (v1)
Routes are Next.js Route Handlers under /api/v1/…. They generally require an authenticated session (Clerk) unless you change middleware.
Accounts & market data
| Method | Path | Notes |
|---|---|---|
| GET | /api/v1/accounts | List accounts (broker) |
| GET | /api/v1/accounts/{accountId}/balances | Account balances for accountId or default |
| GET | /api/v1/accounts/{accountId}/positions | Open positions (Tradier or mock mapping) |
| GET | /api/v1/accounts/{accountId}/orders | Open / session orders |
| GET | /api/v1/quotes?symbols=SYM1,SYM2 | Quotes with short TTL cache |
| GET | /api/v1/stream/quotes?symbols=… | Server-Sent Events; polling-style stream today |
| POST | /api/v1/orders/preview | Dry-run order preview; feature-guarded |
Operations
| GET | /api/v1/health | Liveness, broker flags, Sentry/Redis hints (no secrets) |
The BFF may apply per-IP rate limiting. Treat 429 and 5xx as back-off signals. Do not send broker tokens from the browser — only server environment variables.
3. Security
The product UI is a thick client to the BFF. Third-party API keys and broker credentials load only in server runtime (local .env or the host’s secret store, e.g. Vercel).
Sign-in and sessions are handled by Clerk; middleware protects app routes, with marketing and documentation paths allowlisted. Tradier, Polygon, and optional Stripe or Sentry keys are server-only. Client bundles should only see publishable or intentionally public values.
Production should use HTTPS. Baseline security headers are configured in next.config.ts. For portfolio and scenario persistence, treat non-production environments accordingly until you have a production-grade data story and an updated privacy policy.