Two HNG Tasks That Taught Me More Than the Spec

This is my Stage 9B write-up for the is a queryable profile-intelligence API I built during HNG. By Stage 3 the backend wasn't just CRUD anymore it needed GitHub OAuth with PKCE, JWT access + refresh with rotation, RBAC (admin vs analyst), rate limits, API versioning, and three first-class clients:

Stack: NestJS 11, TypeORM, PostgreSQL, JWT, pdf-parse / mammoth for text extraction, Anthropic Claude for generation, Swagger at /api/v1/docs, Docker Compose for local Postgres + API.

Core flow:

1. 
   POST /api/v1/auth/register or login → JWT
   


2. 
   POST /api/v1/funnels/upload → PDF/DOCX (≤ 5 MiB), extract text, return uploadId + status
   


3. 
   GET /api/v1/funnels/upload/progress/:uploadId → poll until ready
   


4. 
   POST /api/v1/funnels/generate-from-upload → Claude returns awareness → engagement → conversion → retention
   


5. Persist result in PostgreSQL
   

The problem it was solving

Small business owners often have context in documents — pitch decks, one-pagers, notes — but not a marketing framework. The team needed a backend-owned pipeline: upload → extract → generate → store, with a fixed JSON shape the frontend could render without parsing prose.

My job was to make that pipeline boringly predictable for teammates consuming the API.

How I approached it

Contract-first. Swagger became the handshake with frontend and reviewers. Global ValidationPipe (whitelist, forbid unknown fields) so bad payloads fail early with clear 400s, not mysterious 500s.

Upload before AI. Text extraction runs in the upload handler; generation refuses uploads that aren't ready. That split kept slow AI calls out of multipart handling and gave the UI a poll endpoint.

Schema enforcement at the boundary. Claude fills four string slots — nothing else. The product defines the funnel; the model doesn't get to invent nested JSON or markdown essays.

Deploy like someone else will run it. Render for the API, env vars documented in README, TYPEORM_SYNC=false + migrations mindset for anything beyond a throwaway demo.

Team-wise, I treated the marketing service as a bounded context: my repo, my deploy, my docs — but aligned with SEIL's product language and the live site the rest of the squad was building toward.

What broke (and how we fixed it)

1. Claude returned JSON inside markdown fences

Symptom: 502 Bad Gateway, logs showing Unexpected token ''`.

Cause: despite the system prompt saying "raw JSON only," the model sometimes wrapped output in



json ...



.

Fix: coerceJsonFromModelText() strips fences before JSON.parse, then parseMarketingFunnelResult() validates exactly four non-empty strings: awareness, engagement, conversion, retention. Unit tests in funnel-ai.service.spec.ts for parsing edge cases.

2. Generate called before upload was ready

Symptom: frontend showed a spinner forever or users hit generate immediately after upload.

Fix: explicit UPLOAD_NOT_READY (422) with uploadId and status in the error body. Frontend could branch on that instead of guessing.

3. Missing ANTHROPIC_API_KEY in staging

Symptom: opaque failures in demo environment.

Fix: dedicated 503 with code AI_NOT_CONFIGURED — reviewers and teammates know it's env, not logic.

4. Team integration friction — "what's the base URL?"

Symptom: duplicate bug reports about CORS or 404s that were really wrong VITE_API_URL.

Fix: README section for portal dev (VITE_API_URL = origin only, no path) and production Render vars. Swagger "Try it out" with PUBLIC_URL set correctly.

5. Ephemeral disk on Render for uploads

Symptom: uploads worked until redeploy; then uploadId existed but file didn't.

Lesson documented: UPLOAD_STORAGE_ROOT on ephemeral hosts is fine for demos; production needs persistent storage or object storage. We scoped MVP honestly rather than pretending the filesystem was durable.

What I took away

• 
  On a team, your API errors are UX. Structured codes (UPLOAD_NOT_READY, AI_NOT_CONFIGURED) save Slack threads.
  


• 
  LLMs need a bouncer at the door. Prompts aren't contracts — validation is.
  


• 
  Own the slice end-to-end. I didn't merge every SEIL module into one repo; I shipped a service with docs, tests, and a live URL teammates could hit. That's how parallel work actually finishes.

Why this task?

Insighta taught me to survive my own complexity. SEIL taught me to make complexity survivable for other people — frontend, reviewers, teammates — while an AI sits in the middle of the pipeline. That's closer to how real companies ship.

Repo:

Closing thought

HNG doesn't reward the prettiest controller. It rewards systems that hold up when auth, CORS, CSRF, proxies, teammates, and LLMs all show up on the same Tuesday.