1. Architecture in One Screen
The app is a React 19 + TypeScript single-page client (built with Vite) plus a small Express server (server.ts) that serves static/precompressed assets, handles GitHub OAuth, and provides the SSRF-hardened API proxy. A build step (prerender.js) pre-renders marketing/blog/docs pages for performance and SEO.
vite build → client bundle (code-split vendors)
tsx prerender.js → static HTML for /docs, /blog, tools…
esbuild server.ts → server.cjs (beside dist/)
precompress.js → .br / .gz siblings for assets
2. Deployment ownership and source permissions
The production workflow publishes the publisher's built static site to its configured host; optional API and OAuth endpoints run in the publisher's server environment. This page documents that architecture for transparency. Access to the hosted site or this reference does not grant permission to copy, locally execute, or redistribute the application source. See the Terms and LICENSE for current permissions.
3. Environment Variables
| Variable | Purpose |
|---|---|
| GITHUB_CLIENT_ID | OAuth App client id. A legacy in-repo id is used with a loud warning if unset; set it for rotation without redeploy. |
| GITHUB_CLIENT_SECRET | OAuth App secret. Required for the token exchange; never commit it. |
| APP_URL | Canonical https origin advertised to clients and used as the OAuth redirect target (resolves apex/www and proxy mismatches). |
| TRUST_PROXY | Set true behind a reverse proxy so req.protocol honours X-Forwarded-Proto (auto-on in Cloud Run via K_SERVICE). |
| OAUTH_ALLOWED_ORIGINS | Comma-separated extra origins (e.g. a static hosting mirror) allowed to participate in the OAuth relay. |
| FRAME_ANCESTORS | Comma-separated extra https origins allowed to embed the app in a frame; each is validated and malformed entries are dropped. |
| EXTRA_PROXY_DOMAINS | Comma-separated additional hostnames the API proxy may forward to (your own gateways). |
| NODE_ENV / DISABLE_HMR | production tightens CSP; DISABLE_HMR=true turns off Vite HMR. |
4. Server Endpoints (Overview)
POST /api/proxy — SSRF-allowlisted relay to AI/search providers (rate limited).
/api/gemini/* — Gemini generate/countTokens/image helpers.
/api/anthropic/* — Anthropic relay used when direct browser access is blocked.
/api/auth/github/* — OAuth config, session init/status/relay, callback, and token refresh (origin-checked).
/api/enhance-prompt & similar — server-side prompt utilities (rate limited, errors sanitized).
Static — precompressed brotli/gzip assets, prerendered pages, and an SPA fallback for app routes.
5. Publisher deployment safeguards
- Set
GITHUB_CLIENT_SECRETandAPP_URL; confirm the redirect URI matches in the GitHub App. - Enable
TRUST_PROXY=trueif behind a load balancer (or rely onK_SERVICEon Cloud Run). - Terminate TLS at the proxy; the server sends HSTS in production.
- Only add
FRAME_ANCESTORSorigins you actually want framing the app — a wildcard (especially for shared hosts) reopens clickjacking. - Keep the dependency tree patched;
npm auditshould show no high/critical issues in shipped packages. - Verify
npm testandnpm run buildpass after configuring.
6. Data and privacy boundaries
The application does not use a central account database to persist chat history. Server routes can relay provider requests and handle short-lived OAuth state; origin checks can also write warning logs that include request metadata. The hosting provider controls its own access-log retention. Avoid logging Authorization headers or request bodies, which may contain prompts or credentials.
7. Request Lifecycle — Anatomy of One Chat Message
Follow a single prompt end-to-end; each hop is a place something can be misconfigured or observed:
- composer — Enter key; app resolves equipped model, context (pins, history, skills, memories), and tools into one payload
- provider decision — local provider (Ollama/WebLLM) → direct browser→local call; cloud remote → same-origin API route
- POST /api/proxy — Express validates method (GET/POST only), hostname against the allowlist, path normalization, redirect re-checks; strips/forwards only allowlisted headers; passes Authorization only to provider-credential domains
- rate limit middleware — per-route buckets; exceeding returns a 429-shaped response before any upstream is contacted
- upstream provider — streamed tokens flow back through the proxy to the browser (SSE/chunked), which renders incrementally
- client persistence — the completed message is written to IndexedDB; nothing about this exchange is stored server-side
8. Rate Limiting & Abuse Controls
- API routes (general), auth routes, the proxy, and prompt-enhancement endpoints each carry their own rate limiting
- Request bodies are capped — oversized payloads are rejected before parsing work begins
- OAuth relay is additionally origin-checked; a valid session id from the wrong origin is refused
- Browser-local inference — no network, no server limit possible or needed
- Cold static asset serving (precompressed files) — cached and cheap by design
- Upstream provider quotas — those are the provider's, and they surface as 429s (Part 2)
Limits are protective, not punitive — they bound blast radius of a misconfigured loop or a hammering client. If you hit them legitimately (automated QA, bulk evaluation), that traffic belongs against a self-hosted or dedicated deployment, not the shared proxy.
9. OAuth Session Lifecycle — init, status, relay, refresh
- Init: GitHub sign-in starts with a server-generated session id + secret (cryptographically random), short-lived, stored server-side only for the handshake window.
- Status: the popup polls for completion; status responses never carry raw tokens, and comparisons use timing-safe equality.
- Relay: cross-origin completion passes through an origin-checked relay — exact-origin matching; unknown origins get warnings (which the server may log as metadata) and no tokens.
- Exchange: the client secret never ships to the browser; the token exchange happens server-to-server via
/api/auth/github/callback. - Refresh: refresh tokens get their own origin-checked path; disconnect purges both access and refresh material from every storage tier.
- Expiry: OAuth sessions expire after 15 minutes; a stale session must re-handshake — including after a long-idle tab.
The server session stores completion status rather than the access token, and the OAuth client secret stays on the server. The browser stores GitHub credentials for subsequent requests; disconnect the integration to remove those local credentials.
10. What the Server Logs — and Deliberately Doesn't
| Category | Logged? | Detail |
|---|---|---|
| OAuth origin-check warnings | Yes (metadata) | Origin/host metadata for suspicious requests — for abuse detection, not content review |
| Prompt content / request bodies | No | Bodies may contain prompts, code, or keys — they are never written to logs |
| Authorization headers | No | Explicitly excluded; may carry provider credentials |
| Access/audit logs of the hosting platform | Provider-controlled | CDN/edge retention is governed by the host; this reference cannot set or shorten it |
| Error diagnostics (5xx paths) | Bounded | Sanitized error shapes; upstream error bodies are truncated before they are echoed into logs |
If you operate a fork or private deployment of this server, preserve the invariant: log metadata about that something happened, never the secrets that what carried. One leaked Authorization header in a log aggregates into a credential incident.