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 5 — Task Manager Based on Lead Status Description: A task manager that automatically derives and surfaces tasks from a lead's status, so users always see the next action per lead (and across the pipeline) instead of tracking it manually. As a lead moves through statuses, the relevant tasks are created, updated, or closed automatically. Technical implementation: Model tasks as their own entity linked to a lead (lead_id, type, status, due_date, assignee, source). Drive task creation/transition from lead-status changes via an event-driven approach: when a lead's status changes, an event handler evaluates rules and creates/updates/closes the corresponding tasks (e.g. new → "qualify"; enriched → "review & prioritize"; contacted → "follow-up in X days"). Keep the status→task mapping in a configurable rule set (registry/config) rather than hardcoded, so the workflow can be adjusted without a re-deploy. Ensure idempotency so a repeated status event doesn't spawn duplicate tasks. Support both auto-generated and manually created tasks, with clear distinction by source. Provide filtering/sorting (by status, due date, assignee, overdue) and surface tasks in a dedicated view plus contextually on the lead record. Consider coupling to the existing HITL approval points so approval steps appear as tasks too. This fits naturally with Ticket 1 (enrichment status feeding tasks), Ticket 6 (upsell leads generating outreach tasks), and your existing task/ICP dashboards. Acceptance criteria: Tasks are automatically created/updated/closed based on lead-status transitions. The status→task mapping is configurable without a re-deploy. No duplicate tasks on repeated status events (idempotent). Users can view tasks in a dedicated task view and on the individual lead record. Filtering/sorting by status, due date, assignee, and overdue is available. Manual tasks are supported and distinguishable from auto-generated ones. Want me to push all of these (Tickets 1–7) into ClickUp? It's connected — I can create them as tasks with descriptions and acceptance criteria. Just tell me which Space/List. **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.