Full-Stack Developer Assignment

SaaS Feature Development: **Ticket 1 — Lead Enrichment in Lists via Claude (with metered billing)** *Description:* Leads in a list should be automatically enriched by Claude (e.g. missing company data, industry, role, company size, pain-point hypothesis based on existing fields). Enrichment is a paid action, so the customer must be charged for it through our payment engine. *Technical implementation:* Run enrichment as an asynchronous background job per lead or as a batch (queue, e.g. BullMQ/SQS), not synchronously in the request. An enrichment service wraps the Claude API call with a structured prompt and enforces JSON output (defined schema for the target fields). Apply rate limiting and retry with backoff against API limits. Write results into normalized lead fields; persist the raw response, model version, and timestamp for traceability. Ensure idempotency via lead ID so re-runs don't create duplicates. Isolate per-lead failures (one failed lead must not break the batch). For billing: before/at enrichment, charge the customer through our payment engine (per-lead or per-batch pricing — to be defined). Recommended flow: compute the billable quantity, create a charge/usage record via the payment engine, and only commit the enrichment once the charge is authorized (or record it as metered usage if billed in arrears). Persist a billing reference per enrichment run for reconciliation, and handle declined/failed payments gracefully (block the run, surface a clear error, don't silently enrich). *Acceptance criteria:* - Enrichment can be triggered per lead and as a list batch. - Structured fields are populated; empty/uncertain values are marked as "not determined" rather than hallucinated. - Per-lead status is visible (pending / enriched / failed) including failure reason. - Token/cost consumption is logged. - The customer is charged via the payment engine for each enrichment run; a billing reference is stored, and declined payments block the run with a clear error. --- **Ticket 2 — Modular Tool Activation in the Platform** *Description:* Individual tools/modules should be switchable on/off per tenant and/or plan (entitlement / feature-flag system). *Technical implementation:* Entitlement model at the tenant level (e.g. a `tenant_features` table), decoupled from the plan so manual overrides/trials are possible. Server-side authorization is mandatory (middleware/guard checks entitlement before tool endpoints) — frontend gating alone is not sufficient. The frontend hides locked modules or shows an upsell hint. Maintain a central feature definition (registry) so new modules can be registered without schema changes. Cache entitlements per session with invalidation on change. *Acceptance criteria:* - Modules are independently switchable per tenant; changes take effect without a re-deploy. - Locked tools are blocked server-side (no access via direct API call). - Plan assignment sets default entitlements; manual overrides are preserved. --- **Ticket 3 — AI Model Update for HyroPage** *Description:* The previously used Google model has been deprecated. Migrate to a current version. *Technical implementation:* Don't hardcode the model ID — drive it via configuration/env to enable future swaps without code changes. Select a current Gemini version as the replacement and verify prompt/parameter compatibility (output format, token limits, possibly changed response structure). Run a regression test against a representative set of HyroPage inputs to detect quality/format deviations. Add fallback/error handling for the transition period. *Acceptance criteria:* - The deprecated model is no longer referenced anywhere. - Model selection is configurable. - Regression test passes; output format is compatible with existing processing. *Note:* It would be worth verifying which concrete successor version makes sense (and whether the API signature has changed) — model line-ups change frequently. Let me know and I'll research the current state. --- **Ticket 4 — Integrate Email Pricing Tiers** *Description:* Introduce two pricing tiers: €19.99 (2,500 leads) and €39.99 (unlimited leads). *Technical implementation:* Plan definition with a quota attribute (`lead_limit`: 2500 or `null`/unlimited). Billing integration (e.g. Stripe Subscriptions/Prices) for both tiers including webhook handling for status changes. Usage metering: count lead consumption per billing period and check it against the quota; on reaching the 2,500 limit, define a hard or soft limit (block vs. warn + upsell trigger). Quota reset at the start of each period. Tight coupling to Ticket 2 (entitlements) is recommended. *Acceptance criteria:* - Both tiers are bookable; upgrade/downgrade works including prorated billing. - Per-period lead counter is correct; the 2,500 limit is enforced. - The unlimited plan runs without limit checks. - Consumption is visible to the user in the UI. --- **Ticket 6 — Upsell Identification from Support Tickets + Automated Outreach** *Description:* Support tickets should be analyzed for upsell potential. When potential is detected, the person is created as a lead in a separate list, and the appropriate outreach via email and call starts automatically. *Technical implementation:* A classification service evaluates new/closed tickets via Claude (upsell signal + score + rationale + recommended product/tier), with structured JSON output. A threshold decides whether an upsell lead is created. Create the lead in a dedicated upsell list with a source reference (ticket ID, detected signal). Then trigger the appropriate campaign: a personalized upsell email (template + personalized fields) plus a call triggered via HYROCALL. Best modeled as a workflow/state machine: identified → lead_created → outreach_started → (HITL checkpoint before send?). Recommendation: a human-in-the-loop approval before sending, to catch misclassifications — this fits your existing HITL pattern. *Acceptance criteria:* - Tickets are automatically checked for upsell potential; score + rationale are stored. - When the threshold is exceeded, a lead is created in the upsell list (with ticket reference, no duplicates). - The appropriate email + call are triggered; HITL approval optionally placed upstream. - Per-lead outreach status is traceable.