config/projects/business/memory/audit-2026-02-16.md

DocFast Codebase Audit — 2026-02-16

Priority 1: HIGH IMPACT (Do Now)

1. Structured Logging + Request IDs

• Current: console.log/error everywhere — no request correlation, no structured format
• Impact: Debugging production issues is nearly impossible. Can't trace a request through the system.
• Fix: Add request ID middleware, use structured JSON logging (pino)

2. Graceful Error Handling in Browser Pool

• Current: acquirePage() hangs indefinitely if all pages are busy and queue is full — the QUEUE_FULL error only fires if pdfQueue.length >= MAX_QUEUE_SIZE, but the queue size check happens AFTER the rate limit check (which is in middleware), so the request already passed rate limiting
• Current: No timeout on page operations — if Puppeteer hangs, the request hangs forever
• Fix: Add timeout to acquirePage(), add overall request timeout for PDF generation

3. Missing Error Handling in Async Operations

• Current: Several fire-and-forget patterns that silently swallow errors:
  • sendVerificationEmail().catch(err => console.error(...)) — email failure is silent to user
  • pool.query(...).catch(console.error) in verifyTokenSync — DB write failures silently ignored
  • saveUsageEntry().catch(console.error) — usage tracking silently fails
• Impact: Users could sign up but never receive verification email, with no feedback

4. Input Validation Gaps

• Current: Convert endpoints accept any JSON body. No max length on HTML input (only 2MB express limit). No validation on PDF options (format, margin values)
• Current: Template rendering passes user data directly to template render functions — no field validation against the schema
• Fix: Validate format values (A4, Letter, etc.), margin format, reject obviously malicious HTML sizes

5. Memory Leak Risk in Verification Cache

• Current: verificationsCache array grows unbounded — every verification ever created stays in memory
• Current: rateLimitStore map never gets cleaned up proactively (only on check)
• Fix: Add periodic cleanup, TTL-based eviction

6. SEO Improvements

• Current: Basic meta description, no Open Graph tags, no structured data, no sitemap.xml, no robots.txt
• Fix: Add OG tags, Twitter cards, JSON-LD structured data, sitemap, robots.txt

7. Response Headers & Security

• Current: API responses don't include X-Request-Id header
• Current: No Cache-Control headers on static assets
• Current: CSP policy from helmet is default — could be tighter
• Fix: Add proper caching headers, request ID, tighten CSP

Priority 2: MEDIUM IMPACT

8. API Response Consistency

• Current: Mixed response formats:
  • Signup returns {status, message} or {status, apiKey, tier, message}
  • Errors sometimes {error}, sometimes {error, detail}
  • Recovery returns key directly in response (security concern — should match signup UX)
• Fix: Standardize error/success envelope format

9. Database Connection Resilience

• Current: No connection retry logic. If PostgreSQL is temporarily down on startup, the app crashes.
• Current: No health check interval on pool connections
• Fix: Add retry with backoff on startup, add connectionTimeoutMillis

10. Test Coverage

• Current: Only 1 test file (136 lines) with basic tests. No integration tests, no template tests.
• Fix: Add proper test suite covering all routes, error cases, rate limiting

11. Version Mismatch

• Current: package.json says 0.1.0, health endpoint returns 0.2.1 (hardcoded string)
• Fix: Read version from package.json or env

12. Docker Compose Version

• Current: Uses deprecated version: "3.8" key
• Fix: Remove it (modern compose doesn't need it)

13. Accessibility

• Current: Landing page has no skip-to-content link, no focus indicators, modal not keyboard-trapable, no aria-labels on interactive elements
• Fix: Add ARIA attributes, focus management, keyboard navigation

14. Performance: Static Asset Optimization

• Current: Landing page loads Inter font from Google Fonts (render-blocking). No asset fingerprinting, no compression middleware.
• Fix: Add compression middleware, preload fonts, add cache headers

Priority 3: NICE TO HAVE

15. OpenAPI Spec Accuracy

• Verify /openapi.json matches actual API behavior (email-change route not documented)

16. Unused Code

• verifications table + token-based verification seems legacy (superseded by code-based verification). The GET /verify route and verifyToken/verifyTokenSync functions may be dead code.

17. Usage Tracking Race Condition

• In-memory usage map with async DB saves — concurrent requests could cause count drift

18. Template XSS via Currency

• Template esc() function escapes output, but cur (currency) is injected without escaping in the template HTML. d.currency could contain XSS payload.

19. Double !important Overflow CSS

• Landing page has aggressive !important overrides for mobile that could cause issues with new components

---

Execution Plan (CEO Decisions)

Batch 1 — Backend Hardening (spawn backend dev):

• Structured logging with pino + request IDs (#1)
• PDF generation timeout (#2)
• Memory leak fixes — verification cache cleanup, bounded rateLimitStore (#5)
• Version from env/package.json (#11)
• Compression middleware (#14)
• Template currency XSS fix (#18)

Batch 2 — Frontend/SEO (spawn UI/UX dev):

• SEO: OG tags, Twitter cards, sitemap.xml, robots.txt (#6)
• Accessibility: ARIA labels, focus management, keyboard nav (#13)
• Static asset caching headers (#7, #14)

Batch 3 — QA verification of all changes