Ryan/Reactive-Resume
1
0
Fork 0
mirror of https://github.com/AmruthPillai/Reactive-Resume.git synced 2026-07-14 14:57:00 +10:00
Code Issues Packages Projects Releases Wiki Activity
Files
fda4e500b3430ceb8f50687dd80730a5f6caeb10
Reactive-Resume/.planning/codebase/INTEGRATIONS.md
T
Amruth Pillai adfc9b527b docs: map existing codebase 
Adds .planning/codebase/ with parallel-mapper outputs covering stack,
integrations, architecture, structure, conventions, testing, and concerns.
2026-05-11 11:16:33 +02:00

16 KiB
Raw Blame History

External Integrations

Analysis Date: 2026-05-11

APIs & External Services

AI Providers (user-supplied API keys, called per-request from packages/api/src/services/ai.ts):

  • OpenAI — Default base URL https://api.openai.com/v1 (packages/ai/src/types.ts)
    • SDK: @ai-sdk/openai ^3.0.63 via createOpenAI(...).chat(model)
    • API key supplied per-call from the resume's ai config; not read from server env
  • Anthropic — Default base URL https://api.anthropic.com/v1
    • SDK: @ai-sdk/anthropic ^3.0.76 via createAnthropic(...).languageModel(model)
  • Google Gemini — Default base URL https://generativelanguage.googleapis.com/v1beta
    • SDK: @ai-sdk/google ^3.0.71 via createGoogleGenerativeAI(...).languageModel(model)
  • Vercel AI Gateway — Default base URL https://ai-gateway.vercel.sh/v3/ai
    • SDK: ai ^6.0.177 via createGateway(...).languageModel(model)
  • OpenRouter — Default base URL https://openrouter.ai/api/v1
    • SDK: @ai-sdk/openai-compatible ^2.0.47 via createOpenAICompatible({ name: "openrouter", ... })
  • Ollama — Default base URL https://ollama.com/api
    • SDK: ollama-ai-provider-v2 ^3.5.0 via createOllama(...)
  • Security: packages/api/src/services/ai.ts resolveBaseUrl rejects non-HTTPS URLs, credentialed URLs, and private/loopback hosts (via packages/utils/src/url-security.node.ts).
  • File-input AI calls are capped at 10MB (MAX_AI_FILE_BYTES).

OAuth Identity Providers (server-side env-configured, optional):

  • Google — GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET (config in packages/auth/src/config.ts).
  • GitHub — GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET.
  • LinkedIn — LINKEDIN_CLIENT_ID / LINKEDIN_CLIENT_SECRET.
  • Custom Generic OAuth — OAUTH_PROVIDER_NAME, OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, plus either OAUTH_DISCOVERY_URL or all three of OAUTH_AUTHORIZATION_URL/OAUTH_TOKEN_URL/OAUTH_USER_INFO_URL. Scopes from OAUTH_SCOPES (defaults openid profile email). Wired via Better Auth's genericOAuth plugin.
  • Trusted providers for account linking (packages/auth/src/config.ts): google, github, linkedin.

Translation / Localization:

  • Crowdin — CROWDIN_PROJECT_ID, CROWDIN_API_TOKEN (env) / CROWDIN_PERSONAL_TOKEN (CI). Config in crowdin.yml; pull request automation labelled l10n. Source catalog apps/web/locales/en-US.po.

Font Catalog Tooling:

  • Google Fonts Developer API — GOOGLE_CLOUD_API_KEY consumed by packages/scripts/fonts/generate.ts hitting https://www.googleapis.com/webfonts/v1/webfonts. Output committed at packages/fonts/src/webfontlist.json.

Data Storage

Databases:

  • PostgreSQL — Required relational database.
    • Connection env: DATABASE_URL (validated as postgres(ql)://... in packages/env/src/server.ts)
    • Client: drizzle-orm 1.0.0-beta.22 with pg ^8.20.0 Pool, instantiated in packages/db/src/client.ts (singleton via globalThis.__pool / globalThis.__drizzle).
    • Schema location: packages/db/src/schema/index.ts (auth + resume tables) with packages/db/src/relations.ts.
    • Migrations: generated by drizzle-kit into repo-root migrations/ (e.g. 20260507144406_fast_nova/). Generator config at packages/db/drizzle.config.ts.
    • Auto-migration on app start: apps/web/plugins/1.migrate.ts runs drizzle-orm/node-postgres/migrator against the resolved migrations folder.
    • drizzle-kit does NOT auto-load .env — DATABASE_URL must be exported before running pnpm db:generate / pnpm db:migrate (see AGENTS.md "Important" callout).
    • Health probe: packages/api/src/services/storage.ts healthcheck + apps/web/src/routes/api/health.ts runs SELECT 1 through Drizzle (1.5s timeout).

File Storage (selected at runtime in packages/api/src/services/storage.ts):

  • S3-compatible object storage when all three of S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_BUCKET are set.
    • Client: @aws-sdk/client-s3 ^3.1045.0 (S3Client constructed in S3StorageService).
    • Options: S3_REGION (default us-east-1), S3_ENDPOINT (for non-AWS), S3_FORCE_PATH_STYLE.
    • Tested compatible backends: AWS S3 and SeaweedFS (see compose.dev.yml / compose.yml).
    • All writes use ACL: "public-read" (consumed publicly from /uploads/$userId/$ route, with path validation).
  • Local filesystem fallback (LocalStorageService) used when any of the three S3 vars is missing.
    • Path: LOCAL_STORAGE_PATH if set (must be absolute); otherwise <workspace>/data in dev or /app/data in the Docker image.
    • Validated at boot by apps/web/plugins/2.storage.ts (mkdir + access check).
  • Key layout (built in packages/api/src/services/storage.ts):
    • uploads/{userId}/pictures/{timestamp}.jpeg
    • uploads/{userId}/screenshots/{resumeId}/{timestamp}.jpeg
    • uploads/{userId}/pdfs/{resumeId}/{timestamp}.pdf
  • Public read route: apps/web/src/routes/uploads/$userId.$.tsx (ETag, content-type sniffing, path traversal protection).
  • Image preprocessing: sharp ^0.34.5 resizes to 800x800 and re-encodes JPEG at quality 80, unless FLAG_DISABLE_IMAGE_PROCESSING=true.

Caching:

  • No external cache (Redis/Memcached) configured.
  • In-process rate limiter: @orpc/experimental-ratelimit MemoryRatelimiter (packages/api/src/middleware/rate-limit/index.ts).
  • Workbox precache in the service worker (PWA) — apps/web/vite.config.ts VitePWA setup (skipWaiting, clientsClaim, cleanupOutdatedCaches).

Authentication & Identity

Auth Provider: Better Auth 1.6.10, configured in packages/auth/src/config.ts.

  • Mounted as a TanStack Start server handler at /api/auth/* via apps/web/src/routes/api/auth.$.ts.
  • Drizzle adapter: @better-auth/drizzle-adapter bound to db + schema (provider pg).
  • Trusted origins: http://localhost:3000, http://127.0.0.1:3000, and the normalized origin of APP_URL.
  • Secure cookies enabled automatically when APP_URL is https://.
  • Trusted IP headers (used by both Better Auth advanced.ipAddress.ipAddressHeaders and the oRPC rate limiter): CF-Connecting-IP, CF-Connecting-IPv6, True-Client-IP, X-Forwarded-For, X-Real-IP (packages/utils/src/rate-limit.ts).
  • Telemetry: explicitly disabled.

Email/Password:

  • Enabled unless FLAG_DISABLE_EMAIL_AUTH=true.
  • Password hash: bcrypt (cost 10) via hash / compare from bcrypt ^6.0.0.
  • Min 8, max 64 char passwords.
  • Email verification: sent on signup using VerifyEmail template from @reactive-resume/email/templates/auth.
  • Reset password: sendResetPassword -> ResetPasswordEmail template.
  • Email change: sendChangeEmailConfirmation -> VerifyEmailChange template.

Better Auth Plugins (in packages/auth/src/config.ts):

  • jwt() — JWKS published at /api/auth/jwks (also referenced by verifyOAuthToken).
  • admin() — Admin operations.
  • passkey() (@better-auth/passkey ^1.6.10) — WebAuthn passkeys.
  • genericOAuth({ config }) — Driven by OAUTH_* env vars when configured.
  • twoFactor({ issuer: "Reactive Resume" }) — TOTP + backup codes; UI routes /auth/verify-2fa and /auth/verify-2fa-backup.
  • apiKey() (@better-auth/api-key ^1.6.10) — Header x-api-key; enableSessionForAPIKeys: true; per-key rate limit 1000 req/hour.
  • oauthProvider() (@better-auth/oauth-provider ^1.6.10) — Makes this app act as an OAuth 2.1 authorization server for MCP clients. Allows dynamic and unauthenticated client registration (RFC 7591) but redirect URIs are gated by an allowlist in the auth hooks.before middleware and OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS. Audiences whitelist: ${APP_URL}, ${APP_URL}/, ${APP_URL}/mcp, ${APP_URL}/mcp/.
  • username() — Normalized lowercase usernames (^[a-z0-9._-]+$, length 3–64).
  • dash({ apiKey: BETTER_AUTH_API_KEY }) — Better Auth Dashboard (only when BETTER_AUTH_API_KEY is set).

Social Providers:

  • Google, GitHub, LinkedIn — Each activates only when both *_CLIENT_ID and *_CLIENT_SECRET env vars are set (packages/auth/src/config.ts). disableImplicitSignUp: true; account linking enabled.

Session / Access in API context:

  • packages/api/src/context.ts exposes protectedProcedure (referenced in AGENTS.md) for authenticated procedures.
  • oRPC middleware reads request headers via RequestHeadersPlugin (apps/web/src/routes/api/rpc.$.ts, apps/web/src/routes/api/openapi.$.ts).

API Key Auth for HTTP / MCP:

  • x-api-key header recognised by Better Auth API Key plugin.
  • OpenAPI spec at /api/openapi/spec.json declares apiKey security scheme (apps/web/src/routes/api/openapi.$.ts).
  • MCP server first tries OAuth Bearer (Authorization: Bearer ...), then falls back to x-api-key (apps/web/src/routes/mcp/index.ts).

Monitoring & Observability

Error Tracking:

  • None — no Sentry/Datadog/Rollbar SDK present.
  • Errors are logged via console.error (oRPC interceptors onError in apps/web/src/routes/api/rpc.$.ts and apps/web/src/routes/api/openapi.$.ts).

Health Checks:

  • GET /api/health — apps/web/src/routes/api/health.ts returns JSON with DB and storage status; 503 if unhealthy. Used by Docker HEALTHCHECK.

Logs:

  • console.info/console.warn/console.error only. SMTP failures, missing config, sanitization diagnostics, and migration progress are all written to stdout/stderr.

CI/CD & Deployment

Hosting / Distribution:

  • Self-hosted Docker image — Dockerfile builds final image around node:24-slim, expose port 3000, default LOCAL_STORAGE_PATH=/app/data. Multi-stage uses turbo prune for both the web app and the runtime-externals package (which carries bcrypt, sharp, @aws-sdk/client-s3 as native deps).
  • Container labels point to https://rxresu.me and https://docs.rxresu.me.

CI Pipeline:

  • Not present in this worktree (no .github/workflows/ enumerated here). Scripts produce CI-friendly Vitest reports (reports/vitest-junit.xml, reports/vitest-results.json) via the test:ci task.

Local Orchestration:

  • compose.dev.yml — postgres:latest, seaweedfs:latest, seaweedfs_create_bucket (uses quay.io/minio/mc:latest).
  • compose.yml — Same services plus reactive_resume app container, networks data_network / storage_network.

Git Hooks:

  • Lefthook (lefthook.yml) — pre-commit runs biome check --write --unsafe on staged JS/TS/JSON files; commit-msg runs commitlint --edit.

Environment Configuration

Required env vars (validated by Zod in packages/env/src/server.ts):

  • APP_URL — http(s) URL, used for auth base URL, OAuth audiences, OG metadata, and public upload URLs.
  • DATABASE_URL — postgres(ql)://....
  • AUTH_SECRET — Better Auth signing secret (openssl rand -hex 32).

Optional auth env vars:

  • BETTER_AUTH_API_KEY — Enables Better Auth Dashboard plugin.
  • GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET.
  • GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET.
  • LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET.
  • OAUTH_PROVIDER_NAME, OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, OAUTH_DISCOVERY_URL, OAUTH_AUTHORIZATION_URL, OAUTH_TOKEN_URL, OAUTH_USER_INFO_URL, OAUTH_SCOPES, OAUTH_DYNAMIC_CLIENT_REDIRECT_HOSTS.

Optional SMTP env vars (all required together to enable real sends):

  • SMTP_HOST, SMTP_PORT (default 587), SMTP_USER, SMTP_PASS, SMTP_FROM, SMTP_SECURE (default false). Fallback in packages/email/src/transport.ts: log to console with subject/body when SMTP is not fully configured.

Optional storage env vars:

  • LOCAL_STORAGE_PATH — Must be absolute when set.
  • S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_REGION (default us-east-1), S3_ENDPOINT, S3_BUCKET, S3_FORCE_PATH_STYLE (default false).

Optional feature flags:

  • FLAG_DISABLE_SIGNUPS — Disables signups across all providers.
  • FLAG_DISABLE_EMAIL_AUTH — Disables email/password auth and verification flows.
  • FLAG_DISABLE_IMAGE_PROCESSING — Skips Sharp resize/encode (useful on resource-constrained hardware).

Optional tooling env vars:

  • CROWDIN_PROJECT_ID, CROWDIN_API_TOKEN (or CROWDIN_PERSONAL_TOKEN in CI).
  • GOOGLE_CLOUD_API_KEY — For packages/scripts/fonts/generate.ts.

Secrets location:

  • .env at the repo root (gitignored). .env.example provides documented defaults. Existence noted: .env.local, .env.production files present locally (contents not read; may contain secrets).
  • Turbo cache invalidation tied to env vars via turbo.json globalEnv whitelist.

Webhooks & Callbacks

Incoming:

  • OAuth provider callbacks served by Better Auth: /api/auth/oauth2/callback/{providerId} (e.g. /api/auth/oauth2/callback/custom configured in packages/auth/src/config.ts).
  • OAuth Authorization Server endpoints (when this app acts as an OAuth provider for MCP clients): handled by Better Auth oauthProvider plugin under /api/auth/oauth2/*. Login/consent pages at /auth/oauth (apps/web/src/routes/auth/oauth.ts).
  • .well-known discovery routes:
    • apps/web/src/routes/[.]well-known/oauth-authorization-server.ts and .../oauth-authorization-server.$.ts
    • apps/web/src/routes/[.]well-known/oauth-protected-resource.ts and .../oauth-protected-resource.$.ts
    • apps/web/src/routes/[.]well-known/openid-configuration.ts
    • apps/web/src/routes/[.]well-known/mcp/server-card[.]json.ts
    • Generic catch-all: apps/web/src/routes/[.]well-known/$.ts
  • MCP Streamable HTTP transport: apps/web/src/routes/mcp/index.ts (uses WebStandardStreamableHTTPServerTransport). Authenticates via OAuth Bearer or x-api-key.

Outgoing:

  • AI provider HTTPS requests (see "AI Providers" above) — initiated per user request from packages/api/src/services/ai.ts.
  • SMTP outbound (packages/email/src/transport.ts) for verification, password reset, and email-change confirmations.
  • S3 PUT/GET/DELETE/LIST through @aws-sdk/client-s3 when S3 storage is configured.
  • Crowdin and Google Fonts requests only from CI / scripts, not from the runtime web app.

API Endpoints Exposed by the App

Endpoint Handler Purpose
/api/health apps/web/src/routes/api/health.ts Liveness/readiness JSON (DB + storage).
/api/auth/* apps/web/src/routes/api/auth.$.ts Better Auth handler (sessions, OAuth, passkey, JWKS, etc.).
/api/rpc/* apps/web/src/routes/api/rpc.$.ts oRPC server (packages/api/src/routers/index.ts: ai, auth, flags, resume, statistics, storage).
/api/openapi/* apps/web/src/routes/api/openapi.$.ts OpenAPI-style REST wrapper of the oRPC router; spec at /api/openapi/spec.json. Auth via x-api-key.
/mcp apps/web/src/routes/mcp/index.ts MCP Streamable HTTP server (@modelcontextprotocol/sdk).
/uploads/{userId}/... apps/web/src/routes/uploads/$userId.$.tsx Public read of stored images/PDFs with ETag + path validation.
/schema.json apps/web/src/routes/schema[.]json.ts Resume JSON schema.
/.well-known/... apps/web/src/routes/[.]well-known/* OAuth/OIDC/MCP discovery documents.

Rate Limiting

Better Auth (production only, see packages/auth/src/config.ts isRateLimitEnabled):

  • Global default: 60 req / 60s.
  • /sign-in/email: 5/60s; /sign-up/email: 3/60s.
  • /request-password-reset, /send-verification-email: 3/600s.
  • /two-factor/verify-otp, /verify-totp, /verify-backup-code: 5/600s.
  • /is-username-available: 20/60s.
  • OAuth provider endpoints: register 5/60s, authorize 30/60s, token 20/60s, introspect 60/60s, revoke 30/60s, userinfo 60/60s.
  • API keys: 1000 req / hour per key.
  • Source: packages/utils/src/rate-limit.ts.

oRPC procedure-level (in-memory, production only, see packages/api/src/middleware/rate-limit/index.ts):

  • resumePassword: 5 / 10min.
  • pdfExport: 5 / 60s.
  • aiRequest: 20 / 60s.
  • jobsSearch: 30 / 60s.
  • jobsTestConnection: 10 / 60s.
  • storageUpload: 20 / 60s.
  • storageDelete: 30 / 60s.
  • resumeMutations: 60 / 60s.
  • Keys are derived from authenticated user id when present, otherwise from the first trusted-IP header or a UA+language fingerprint.

Optional Services Declared in Compose Files

Service Image Purpose File
postgres postgres:latest Required PostgreSQL DB compose.dev.yml, compose.yml
seaweedfs chrislusf/seaweedfs:latest Optional S3-compatible storage for dev/prod compose.dev.yml, compose.yml
seaweedfs_create_bucket quay.io/minio/mc:latest One-shot init that creates reactive-resume bucket compose.dev.yml, compose.yml
reactive_resume Built from Dockerfile The app itself in prod compose compose.yml

Integration audit: 2026-05-11

Reference in New Issue View Git Blame Copy Permalink