1. Current-State Assessment 1.1 Current Architecture (Text Flow) [Browser: React+Vite SPA] | | HTTPS (assumed, not confirmed) v [Single VPS] |-- [Node.js/Express API] | |-- Basic Auth (session or token — mechanism unspecified) | |-- Business logic: resume parsing, prompt construction | |-- Calls -----> [External LLM API] (generation) | |-- Writes -----> [Local Filesystem] (generated PDFs) | |-- Reads/Writes -> [PostgreSQL] (same VPS, assumed) | |-- [PostgreSQL DB] (co-located, no confirmed replica/backup) |-- [Local FS] (PDF storage, no confirmed backup/CDN) Deployment: manual (SSH/script, unspecified) -> single VPS, no staging confirmed Monitoring: none Rate limiting: none Everything — app server, database, and file storage — runs on one host. There is a single deployment target and no described separation between environments. 1.2 Confirmed Facts vs Assumptions # Confirmed Fact Assumption (flagged, not fabricated) 1 Frontend: React + Vite Frontend is served as static build (not confirmed how — same VPS via Nginx? Node static serve?) 2 Backend: Node.js/Express Framework version, middleware stack unknown 3 Database: PostgreSQL Version, hosting mode (same VPS vs managed) unconfirmed — plan assumes same VPS since no separate DB host is mentioned 4 Generation via external LLM API Which provider, rate limits, cost-per-call, and contract SLA unknown 5 Single VPS hosting Provider, specs (CPU/RAM/disk), OS unknown 6 PDFs stored on local filesystem No backup, no CDN, no size/retention policy stated — assumed unbounded growth risk 7 No automated tests Coverage is 0% by statement, not "low" 8 No API rate limiting Applies to both the LLM-calling endpoints and all public endpoints — assumed uniform absence 9 Manual deployment No CI/CD, no rollback tooling confirmed 10 No monitoring/alerting Assumed this includes no uptime checks, no error tracking, no log aggregation 11 DB backups not automated Unknown if any manual/ad hoc backup exists at all — assumed none exist 12 Basic authentication only Interpreted as password-based auth without MFA, without confirmed hashing algorithm, rate-limited login, or session hardening — needs verification 13 2 developers, 6-week timeline Fixed constraint — plan is scoped to be achievable by 2 people in 6 weeks 14 5,000 registered users, ~100 concurrent peak Year-one target — used to size infra, not to justify premature scaling Open — HTTPS/TLS termination method unconfirmed Open — Data retention/deletion policy for resumes (PII) unconfirmed Open — Whether resumes contain regulated data (e.g., addresses, phone numbers only, or more) unconfirmed 1.3 Bottlenecks and Gaps Mapped to Production Risk Category Gap Risk at 100 Concurrent Peak / 5K Users Compute Single VPS runs API+DB+file storage One process crash or DB lock takes down everything; no headroom for LLM call latency spikes I/O Local filesystem for PDFs Disk fills silently; no redundancy means PDF loss = permanent data loss for users Auth "Basic authentication only" Credential stuffing, brute force, and session hijacking are unmitigated; likely account-takeover exposure Input validation Not confirmed present Injection into LLM prompts (prompt injection), SQL injection if raw queries used, XSS in resume rendering Rate limiting None A single user (or bot) can exhaust LLM API quota/budget or DB connections, causing outage for all users Secrets management Not described LLM API key and DB credentials likely in .env or hardcoded — high blast radius if VPS is compromised Testing 0% automated Every deploy is a regression risk; manual QA won't scale to weekly/biweekly releases Deployment Manual Human error risk, no rollback path, deployment downtime uncontrolled Backups None automated Total data loss on disk failure, accidental deletion, or ransomware — unrecoverable Dependency fragility External LLM API is a hard dependency with no fallback Provider outage or rate-limit change fully blocks the core product function Observability None Failures are discovered by users, not by the team; mean-time-to-detect is unbounded 2. Target Production Architecture 2.1 Target Architecture (Text Flow) Given the stated scale (5,000 users, ~100 concurrent peak) and team size (2 developers), a distributed/microservices architecture is not justified. The target is a hardened single-VPS-class deployment with externalized state and clear environment separation. [DNS + TLS: Let's Encrypt via reverse proxy] | v [Nginx/Caddy reverse proxy] - TLS termination - Rate limiting (basic, IP-based) - Static asset serving (React build) | v [Node.js/Express API - process-managed (pm2 or systemd, 2+ instances via cluster mode)] - AuthN/AuthZ middleware - Input validation layer - Rate limiting (per-user, per-IP) - Structured logging -> [Log aggregator] | ----------------------------------------- | | | v v v [Managed PostgreSQL [Object Storage [External LLM API] or hardened VPS-hosted (S3-compatible: e.g. - Timeout + retry Postgres w/ automated Backblaze B2/S3) for - Circuit breaker backups + PITR] generated PDFs] - Fallback/queue on failure [Monitoring/Alerting: Uptime check + error tracker (e.g. self-hosted or low-cost SaaS) + log dashboard] Key shift from current state: move PDFs off local disk to object storage (removes single point of data loss, enables CDN-style delivery), and move DB to either a managed Postgres instance or the same VPS with automated backup tooling if budget forces co-location. 2.2 Environments Environment Purpose Config/Secrets Approach Development Local dev on developer machines .env.local, not committed; .env.example checked in as template Staging Pre-production validation, mirrors prod config at smaller scale Separate VPS or same VPS with isolated ports/containers; separate DB instance/schema; separate LLM API key with low quota to control cost Production Live traffic Secrets in environment variables injected at deploy time via secrets manager (e.g. Doppler, Infisical, or VPS provider's native secret store) — never in source control Open question: budget may not support a fully separate staging VPS. Minimum-viable alternative: a Docker Compose-based staging stack on the same VPS with a distinct port/subdomain, acceptable at this scale given budget constraints. 2.3 CI/CD, Migrations, Backup, Disaster Recovery CI/CD GitHub Actions (or equivalent) pipeline: lint -> test -> build -> deploy Deploy via SSH+script or a lightweight CD tool (e.g., a git pull + pm2 reload hook) — full container orchestration is not justified at this scale Every merge to main triggers staging deploy; production deploy is a manual-approval gate initially, until confidence is established Database migrations Adopt a migration tool (e.g., node-pg-migrate or Prisma Migrate) — no manual schema edits in production Every migration is reversible or has a documented rollback step Migrations run as a distinct CI/CD step before app deploy, never inline in app boot Backup strategy Automated nightly full DB backup + point-in-time recovery (WAL archiving) if using managed Postgres; if self-hosted, pg_dump on a cron schedule to off-VPS storage (object storage bucket) Backups tested via periodic restore drill (monthly, at minimum before go-live and once post-launch) Object storage (PDFs) uses provider-native versioning/redundancy rather than custom backup logic Disaster recovery RPO/RTO targets are not specified by the user — flagged as an open question. Recommended default for this scale: RPO ≤24h, RTO ≤4h, to be confirmed with stakeholders Documented runbook: how to restore DB from latest backup, redeploy app from last known-good tag, and restore object storage access 2.4 Monitoring, Logging, Alerting, Caching, Rate Limiting Monitoring: uptime check (e.g., UptimeRobot free/low-cost tier) on the public endpoint and LLM-dependent endpoint separately Error tracking: Sentry (or self-hosted alternative) for backend and frontend exception capture Logging: structured JSON logs (e.g., pino) shipped to a low-cost aggregator or at minimum rotated local logs with size caps Alerting: threshold alerts on error rate, response latency, and disk usage; delivered via email/Slack webhook — no dedicated on-call tooling justified at 2-developer scale Caching: cache LLM responses where prompts are deterministic/repeatable is likely not applicable (resumes are user-specific), but cache static reference data (e.g., ATS keyword lists, templates) in memory or Redis if introduced later — not launch-blocking Rate limiting: two layers — (1) reverse-proxy IP-based limiting for blunt abuse protection, (2) application-level per-user limiting specifically on LLM-calling endpoints, since these are the highest-cost, most abuse-prone routes 3. Security & Compliance Hardening 3.1 Authentication & Authorization Replace "basic authentication" with: bcrypt/argon2 password hashing (verify current hashing — if plaintext or weak hashing, this is launch-blocking), enforced password complexity minimums, and login rate limiting/lockout after repeated failures Session management: move to signed, HTTP-only, secure cookies or short-lived JWTs with refresh-token rotation — confirm which is currently used, as "basic authentication" is ambiguous Add email verification on signup to reduce fake-account abuse of LLM quota Authorization: confirm every resume/document endpoint checks resource ownership (userId match), not just that a valid session exists — this is a common IDOR gap in AI-assisted prototypes and must be explicitly audited 3.2 Encryption, Validation, Abuse Prevention In transit: enforce HTTPS everywhere via reverse proxy TLS termination; HSTS header enabled At rest: enable Postgres disk encryption if using managed hosting (most managed providers default this on); encrypt object storage bucket (S3-compatible providers support this natively) Input validation: schema validation (e.g., Zod/Joi) on every API input boundary — particularly work-history text fields, which flow into LLM prompts (prompt-injection surface) and into PDF rendering (XSS/injection surface if rendered as HTML before PDF conversion) Abuse prevention: rate limit LLM-calling endpoints per user/session; enforce max input length on resume text fields to control LLM token cost and prevent denial-of-wallet attacks Secrets: rotate LLM API key and DB credentials before launch if they have ever been exposed in a repo, chat log, or shared document during MVP build 3.3 Compliance Flag Resumes plausibly contain personal data (name, contact info, employment history) — this implies baseline data-protection obligations (e.g., GDPR/CCPA-style user rights: data export, deletion) depending on user geography, which is not stated Open question: what user geographies are targeted? This determines whether formal compliance frameworks apply. Do not assume EU/CCPA applicability without confirmation — flagged, not fabricated Minimum recommended regardless of jurisdiction: a documented data retention policy and a user-initiated account/data deletion path, since this is low-cost to implement and reduces liability 3.4 Audit Cadence, Incident Response, Rollback Audit cadence: dependency vulnerability scan (npm audit or Snyk) on every CI run; manual security review of auth/authorization code before go-live; quarterly review post-launch Incident response: a one-page runbook — who is notified, how to roll back a deploy, how to rotate a compromised secret, how to communicate a user-facing incident. With 2 developers, this must be lightweight but must exist before go-live Rollback protocol: every production deploy tagged in git; deploy script supports deploy <previous-tag> as a one-command rollback; database migrations must be backward-compatible for at least one release to allow app rollback without DB rollback 4. Technical Debt Register Issue Impact Severity Production Risk Fix Priority No automated tests Regressions ship undetected High Broken core flow (resume generation) reaches users Add unit tests for auth/validation, integration tests for API routes, E2E test for critical path Launch-blocking (minimum coverage) No API rate limiting Cost/availability exposure Critical LLM budget exhaustion or DoS by single actor Add reverse-proxy + app-level rate limiting on auth and LLM endpoints Launch-blocking Manual deployment Human error, no rollback High Extended downtime during bad deploy CI/CD pipeline with tagged, reversible deploys Launch-blocking No monitoring/alerting Blind to failures High Outages discovered by users, slow MTTR Uptime check + error tracker + basic alerting Launch-blocking DB backups not automated Unrecoverable data loss Critical Total loss of user resumes/accounts on failure Automated nightly backup + restore drill Launch-blocking Basic authentication only Account takeover risk Critical Credential stuffing, session hijack, IDOR Hardened hashing, lockout, ownership checks, secure sessions Launch-blocking Local filesystem for PDFs Disk exhaustion, no redundancy High Permanent PDF loss, service outage from full disk Migrate to object storage (S3-compatible) Launch-blocking No input validation (assumed) Prompt injection, XSS, malformed data High Data corruption, LLM misuse, security exploit Schema validation at all API boundaries Launch-blocking No secrets management Credential exposure High Full system compromise if VPS breached Externalize secrets, rotate keys pre-launch Launch-blocking No staging environment Untested changes hit prod directly Medium Higher deploy failure rate Minimum-viable staging (same VPS, isolated) Complete if feasible No caching layer Not yet a bottleneck at stated scale Low Unnecessary LLM/API latency under load Add if latency issues observed post-launch Deferrable Single VPS (no horizontal scaling) Ceiling on concurrent capacity Medium Degraded performance beyond ~100 concurrent if under-provisioned Vertical scale first; horizontal only if metrics justify Deferrable — monitor No documented DR/runbook Slow incident recovery Medium Extended outage during incident One-page runbook before go-live Launch-blocking (lightweight version) Sequencing logic: fix data-loss and security-critical items first (backups, auth, secrets, rate limiting) since these are irreversible-harm categories; testing and CI/CD next since they gate the safety of all subsequent changes; deferrable items (caching, horizontal scaling, full staging parity) are explicitly not worth the 2-developer time budget before an MVP launch at this scale. 5. Testing & Quality Strategy 5.1 Testing Pyramid Mapped to Critical User Journey Critical journey: Sign up -> Log in -> Enter work history -> Generate resume via LLM -> Download/view PDF /\ /E2E\ <- 1-2 flows: full signup-to-PDF-download journey (Playwright/Cypress) /------\ /Integr. \ <- API route tests: auth endpoints, resume CRUD, LLM-call endpoint /----------\ (mock LLM API), PDF generation service /------------\ / Unit \ <- validation logic, auth/password hashing, prompt-construction /----------------\ logic, PDF formatting utility functions Unit tests: highest count, fastest feedback — target auth, validation, and prompt-building logic first since these are highest-risk and most testable in isolation Integration tests: API endpoints with the LLM call mocked (never call the real LLM API in CI — cost and flakiness) E2E tests: one or two full-path tests covering the critical journey above; kept minimal given 2-developer bandwidth 5.2 Pre-Deploy Release Gate Checklist All unit and integration tests pass in CI Lint and static analysis pass with zero high-severity findings Migration applied successfully against a staging DB copy Manual smoke test of the critical journey on staging No secrets present in diff (automated secret-scanning in CI, e.g., gitleaks) Rollback tag confirmed available before deploy proceeds 5.3 Recommended Tooling Static analysis/linting: ESLint (with a security plugin such as eslint-plugin-security), Prettier for formatting consistency Secret scanning: gitleaks or truffleHog in CI Dependency scanning: npm audit or Snyk in CI Test runners: Vitest (pairs naturally with Vite) for unit/integration, Playwright for E2E 6. Risk Register Risk Probability Impact Mitigation Trigger Signal LLM API cost overrun from unrestricted usage High High Rate limiting, input length caps, usage monitoring/budget alerts Daily LLM spend exceeds forecast threshold External LLM API outage or breaking change Medium High Timeout/retry logic, circuit breaker, clear user-facing error state Elevated error rate on generation endpoint Data loss (DB or PDF storage failure) Medium (currently unmitigated) Critical Automated backups, object storage migration, restore drills Disk usage alert, backup job failure notification Account takeover via weak auth Medium High Hardened auth per Section 3.1 Spike in failed login attempts from single IP/user Single VPS resource exhaustion at peak (~100 concurrent) Medium Medium Load testing before launch, vertical scaling headroom, alerting on CPU/memory Sustained CPU/memory >80%, response latency increase Deployment failure with no rollback Medium (currently unmitigated) High CI/CD with tagged rollback capability Failed health check post-deploy Prompt injection via resume input fields Medium Medium Input validation, prompt-construction sanitization Anomalous LLM output patterns, user reports Team bandwidth risk (2 developers, 6 weeks) High High Strict launch-blocking vs deferrable triage (Section 4/7) Scope creep beyond blocking list mid-sprint Unconfirmed compliance exposure (data protection) Low-Medium (unknown geography) Medium-High Confirm target user geography; implement baseline retention/deletion policy regardless Legal/user inquiry about data handling 7. Phased Roadmap & Go-Live Gate 7.1 Phased Sequence (6-Week Window) Phase 1 (Weeks 1-2) — Stop the Bleeding (Data & Security Foundations) Exit criteria: automated backups running and restore-tested; secrets externalized and rotated; auth hardened (hashing, lockout, session security); PDF storage migrated to object storage Phase 2 (Weeks 2-4) — Delivery Pipeline & Guardrails Exit criteria: CI/CD pipeline live with lint/test/build gates; migration tooling adopted; rate limiting active on LLM and auth endpoints; input validation on all endpoints Phase 3 (Weeks 4-5) — Observability & Testing Exit criteria: monitoring/alerting live (uptime, error tracking, basic logging); unit + integration test suite covering auth, validation, and generation flow; one E2E test for critical journey passing in CI Phase 4 (Weeks 5-6) — Load Validation & Go-Live Readiness Exit criteria: load test simulating ~100 concurrent sessions completed with acceptable latency/error rate; DR runbook documented; release gate checklist passed on staging; rollback tested at least once 7.2 Production Readiness Matrix Area Status Gap Action Go-Live Impact Backups Not ready No automation Automated nightly backup + restore drill Block Auth/Session Not ready Basic auth, unconfirmed hashing/session security Harden per Section 3.1 Block Rate limiting Not ready None exists Add proxy + app-level limits Block Secrets management Not ready Unconfirmed, assumed weak Externalize + rotate Block PDF storage Not ready Local disk, no redundancy Migrate to object storage Block Input validation Not ready Unconfirmed presence Add schema validation Block CI/CD Not ready Manual deploy only Build pipeline with rollback Block Monitoring/Alerting Not ready None Add uptime + error tracking + alerts Block Testing Not ready 0% automated Add pyramid per Section 5 Block (minimum coverage) Staging environment Partial Not confirmed to exist Minimum-viable staging on same VPS Complete if feasible Compliance/data policy Not ready No retention/deletion policy Document baseline policy Complete if feasible Caching N/A at current scale Not present Defer Monitor after launch Horizontal scaling N/A at current scale Single VPS Defer, monitor resource usage Monitor after launch Load testing Not done No evidence of testing at target concurrency Run before go-live Block 7.3 Tiered Final Action List Block Before Go-Live Automated, tested database backups Hardened authentication (hashing, lockout, secure sessions) and ownership-based authorization checks API rate limiting on auth and LLM-calling endpoints Secrets externalized from source control, rotated if previously exposed PDF storage migrated off local filesystem to object storage Input validation on all API boundaries CI/CD pipeline with reversible, tagged deploys Minimum monitoring (uptime + error tracking) and basic alerting Minimum automated test coverage on auth, validation, and generation flow, including one E2E critical-path test Load test at approximate target concurrency (~100 sessions) One-page incident/rollback runbook Complete If Feasible Full staging environment parity Documented data retention/deletion policy Dependency and secret scanning integrated into CI Migration tool formally adopted (vs ad hoc schema changes) Monitor After Launch Actual concurrent usage and resource consumption vs the ~100-session estimate LLM API cost trend against budget Error rate and latency trends from the new monitoring stack Long-Term Horizontal scaling or managed database migration if usage growth exceeds single-VPS capacity Caching layer if generation or read latency becomes a measured bottleneck Formal compliance program if geography/data-handling scope expands Expanded test coverage beyond the critical-path minimum 8. Key Decisions & Open Questions 8.1 Key Architectural Decisions Keep a single-VPS-class deployment rather than moving to distributed infrastructure — the stated scale (100 concurrent, 5K users/year) does not justify the operational overhead a 2-developer team cannot absorb Move PDF storage to object storage (S3-compatible) — removes the single largest data-loss risk in the current design at low cost and low complexity Adopt CI/CD with tagged rollback before adding any new feature work — untested manual deploys are the highest-leverage risk given a 6-week timeline with ongoing changes Treat rate limiting and secrets management as launch-blocking rather than deferrable — both carry unbounded financial/security downside for a startup budget Defer horizontal scaling and caching entirely — no evidence in the stated scale justifies the complexity; premature optimization here would consume scarce developer time better spent on security/testing debt Use schema-based input validation (e.g., Zod) library rather than hand-rolled checks — faster to implement broadly across endpoints within the timeline Treat resume data as PII by default pending geography confirmation — cheaper to build minimal retention/deletion support now than retrofit under regulatory pressure later 8.2 Assumptions & Unresolved Questions to Confirm Before Sign-Off What is the actual current authentication mechanism (password hashing algorithm, session vs JWT, cookie flags)? Labeled "basic authentication" but not specified What LLM provider is used, and what are its rate limits, cost structure, and SLA/uptime history? Is the database currently co-located on the same VPS as the app, or hosted separately? What is the current disk capacity and PDF retention policy (if any)? What user geographies are targeted, to determine actual data-protection obligations? Is there any existing backup, even manual/ad hoc, that should be verified before assuming zero? What is the acceptable RPO/RTO for this business — the plan assumes RPO ≤24h/RTO ≤4h pending confirmation Is there existing budget for a managed Postgres service and object storage, or must both be self-hosted on the existing VPS? Has the LLM API key or DB credentials ever been exposed (e.g., committed to a public repo) during MVP development? This determines whether rotation is urgent-block vs routine-hygiene.