SwiftSupport AI — MVP Explainer

Concept

SwiftSupport AI is a B2B SaaS triage engine for customer support teams. It connects to Zendesk via OAuth 2.0, processes incoming tickets through an LLM, and automatically assigns categories, priorities, and routes tickets to the right agent or team — eliminating manual triage for up to 90% of incoming volume.

Problem: Support teams waste hours manually reading, categorizing, and routing tickets. Urgent issues get buried. Agents burn time on repetitive classification instead of resolving problems.

Solution: Every new ticket is analyzed by AI within seconds. Rules-based routing then assigns it to the right team instantly. Managers monitor everything via a dashboard and can correct misclassifications to improve accuracy over time.

---

Architecture

Zendesk Webhook
      │
      ▼
WebhookController (POST /api/webhooks/zendesk/{tenantId})
      │  — responds 202 immediately
      ▼
WebhookProcessingService [@Async on Virtual Thread]
      │
      ├── ZendeskClient (Feign) ──► GET /api/v2/tickets/{id}
      │
      ├── TriageService ──────────► POST /chat/completions (OpenAI)
      │                            ◄── { category, priority, reasoning }
      │
      ├── RoutingService ─────────► Match routing rules (DB)
      │
      ├── TicketAuditRepository ──► INSERT ticket_audit
      │
      └── ZendeskClient (Feign) ──► PUT /api/v2/tickets/{id}  (update priority + tags)

Multi-Tenant Isolation

Every data entity (%%INLINE0%%, %%INLINE1%%, %%INLINE2%%) carries a %%INLINE3%% foreign key. All repository queries are scoped to the authenticated tenant's ID, extracted from the JWT claim tenantId.

Virtual Threads (Java 25)

%%INLINE5%% is annotated %%INLINE6%%. The executor is backed by %%INLINE7%%. Webhooks return %%INLINE8%% in < 5 ms while the I/O-heavy triage pipeline runs on a lightweight virtual thread — no thread pool exhaustion under burst load.

---

Endpoints

Auth (Public)

Method	Path	Description
POST	/api/auth/register	Create company account + admin user, returns JWT
POST	/api/auth/login	Validate credentials, returns JWT

OAuth 2.0 — Zendesk Integration (Authenticated)

Method	Path	Description
GET	/oauth/zendesk/connect?subdomain=acme	Redirects browser to Zendesk authorization page
GET	/oauth/zendesk/callback?code=…&state=…	Exchanges code for token, activates connection
GET	/oauth/zendesk/status	Check if tenant has active Zendesk connection

Webhooks (Public — Zendesk calls these)

Method	Path	Description
POST	/api/webhooks/zendesk/{tenantId}	Receive ticket notification, trigger async triage

Routing Rules (Authenticated — Manager)

Method	Path	Description
GET	/api/rules	List all routing rules
POST	/api/rules	Create a routing rule
PUT	/api/rules/{ruleId}	Update a routing rule
DELETE	/api/rules/{ruleId}	Delete a routing rule

Dashboard (Authenticated — Manager)

Method	Path	Description
GET	/api/dashboard/tickets?page=0&size=20	Paginated AI-processed ticket audit log
GET	/api/dashboard/stats	Total processed, correction rate, quota usage
PUT	/api/dashboard/tickets/{auditId}/correction	Override AI classification

---

Triage AI — LLM Prompt

The AI is called with a structured user prompt and instructed to return pure JSON:

Ticket Subject: {subject}
Ticket Description: {description}

Categories: BILLING, TECHNICAL_BUG, SALES_INQUIRY, ACCOUNT_MANAGEMENT, FEATURE_REQUEST, GENERAL_QUESTION, UNKNOWN
Priorities: URGENT, HIGH, NORMAL, LOW

Respond with ONLY: {"category": "...", "priority": "...", "reasoning": "one sentence"}

Priority rules baked into the prompt:

• URGENT → outage, data loss, security breach, payment failure
• HIGH → broken core feature, billing dispute
• NORMAL → general questions, minor bugs
• LOW → feature requests, feedback

On LLM failure, the service falls back to UNKNOWN / NORMAL so the pipeline never blocks.

---

Routing Rules Engine

Rules are evaluated highest priority first (DESC). First match wins.

Field	Description
%%INLINE27%%	%%INLINE28%% = wildcard (match any category)
%%INLINE29%%	%%INLINE30%% = wildcard (match any priority)
assigneeTarget	Agent email or team name
zendeskGroupId	Zendesk Group ID to set on the ticket
priority	Rule evaluation order (higher = checked first)

Example: Route all URGENT tickets to the on-call team:

{
  "name": "Urgent → On-Call",
  "matchCategory": null,
  "matchPriority": "URGENT",
  "assigneeTarget": "oncall@acme.com",
  "zendeskGroupId": 12345,
  "priority": 100
}

---

Data Model

CustomerAccount (tenant)
  ├── User (M:1) — email, passwordHash, role (ADMIN|MANAGER|AGENT)
  ├── HelpdeskConnection (M:1) — OAuth tokens per platform (ZENDESK|INTERCOM|FRESHDESK)
  ├── RoutingRule (M:1) — category/priority → assignee mapping
  └── TicketAudit (M:1) — immutable AI processing record with optional correction

---

Monetization

Tier	Monthly Ticket Quota	Price
Starter	1,000 tickets/month	$49/month
Pro	5,000 tickets/month	$149/month
Enterprise	Unlimited	Custom

Quota is tracked via CustomerAccount.currentMonthTicketCount, incremented after each processed ticket. Overage handling (warn → block → upsell) is a post-MVP feature.

---

Business Analysis

TAM: The global customer service software market is $11B+ (2024) growing at 12% CAGR. ICP: SaaS/e-commerce companies with 5–50 support agents on Zendesk, Intercom, or Freshdesk. ROI for customer: Median first-response time drops from hours to seconds for auto-triaged tickets. Agents focus on resolution, not sorting. CSAT improves. Competitive moat: Routing rules tied to correction feedback loop creates a flywheel — the more corrections a tenant submits, the more accurate their routing becomes (future: fine-tuning per tenant).

Risks:

• LLM latency/cost at scale → mitigated by async processing + model selection (GPT-4o-mini is ~10× cheaper than GPT-4o)
• Zendesk API rate limits → mitigated by async queue (future: Kafka/SQS)
• Hallucinated categories → mitigated by enum validation + correction loop

---

How to Run

Prerequisites

• Java 25
• Maven 3.9+
• PostgreSQL 16+ running locally (or Docker)
• OpenAI API key (or compatible LLM endpoint)
• Zendesk developer account (for OAuth)

1. Database

CREATE DATABASE swiftsupport;

2. Configuration

Add to src/main/resources/application.yml:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/swiftsupport
    username: postgres
    password: yourpassword
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: false

swiftsupport:
  jwt-secret: "your-32-char-secret-key-here!!!!!"
  jwt-expiration-ms: 86400000   # 24h
  zendesk:
    client-id: your-zendesk-client-id
    client-secret: your-zendesk-client-secret
    redirect-uri: http://localhost:8080/oauth/zendesk/callback
    base-url: https://placeholder.zendesk.com
  llm:
    api-key: sk-your-openai-key
    model: gpt-4o-mini
    base-url: https://api.openai.com/v1

3. Build & Run

mvn clean package -DskipTests
java -jar target/swift-support-ai-0.0.1-SNAPSHOT.jar

4. Quick Smoke Test

# Register tenant
curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"companyName":"Acme Corp","domain":"acme.com","email":"admin@acme.com","password":"secret123"}'

# Login → get JWT
TOKEN=$(curl -s -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@acme.com","password":"secret123"}' | jq -r .token)

# Create routing rule
curl -X POST http://localhost:8080/api/rules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Billing → Finance","matchCategory":"BILLING","assigneeTarget":"billing@acme.com","priority":10}'

# View dashboard stats
curl http://localhost:8080/api/dashboard/stats \
  -H "Authorization: Bearer $TOKEN"

---

References

• AI-Powered SaaS Ideas — BigIdeasDB
• Zendesk OAuth 2.0 Docs
• OpenAI Chat Completions API
• Spring Boot 4.0 Reference
• JJWT 0.12.x Reference
• Java Virtual Threads (JEP 444)

---

Análisis FinOps para SwiftSupport AI

Visión General de Costos y Rentabilidad

SwiftSupport AI, en su fase inicial como micro-startup, demuestra un modelo de negocio con un margen de beneficio saludable, incluso con una base de clientes modesta. Los costos operativos se centran principalmente en el consumo de LLM y la infraestructura cloud básica. La clave para mantener la rentabilidad a medida que la startup escala será la gestión proactiva de estos dos pilares.

Estimación de Costos Mensuales

Basado en un escenario inicial de 5 clientes en el plan 'Starter' (hasta 1000 tickets/mes) y 1 cliente en el plan 'Pro' (hasta 5000 tickets/mes), el volumen total de tickets procesados es de aproximadamente 10,000 tickets/mes.

• Consumo de LLM (OpenAI gpt-4-turbo):

* Estimación de tokens por ticket: ~750 tokens de entrada y ~75 tokens de salida. * Total de tokens mensuales: ~8.25 millones de tokens (7.5M entrada, 0.75M salida). * Costo estimado: $105/mes (basado en gpt-4-turbo: $10/M entrada, $30/M salida).

• Infraestructura Cloud (AWS):

* Servidor de Aplicación (Spring Boot): Una instancia t3.small de EC2 (2 vCPU, 2 GiB RAM) es adecuada para la carga inicial con Virtual Threads. Costo: ~$18/mes. * Base de Datos (PostgreSQL): Una instancia db.t3.micro de AWS RDS (2 vCPU, 1 GiB RAM) para PostgreSQL. Costo: ~$18/mes. * Networking y Monitoreo: Costos básicos asociados a transferencia de datos, CloudWatch, etc. Costo: ~$18/mes. * Total Infraestructura Cloud: $54/mes.

• Otros Costos: Un pequeño colchón para herramientas, logs, etc. ~$5/mes.

Costo Operativo Mensual Total Estimado: $105 (LLM) + $54 (Cloud) + $5 (Otros) = $164/mes.

Estimación de Ingresos Mensuales

Considerando los planes de monetización:

• Plan Starter: $99/mes (hasta 1000 tickets).
• Plan Pro: $299/mes (hasta 5000 tickets).

Con una base inicial de 5 clientes Starter y 1 cliente Pro: Ingresos Starter: 5 $99 = $495/mes. Ingresos Pro: 1 $299 = $299/mes.

Ingreso Mensual Total Estimado: $495 + $299 = $794/mes.

Margen de Beneficio

• Ingresos: $794/mes
• Costos: $164/mes
• Beneficio Bruto: $794 - $164 = $630/mes

Margen de Beneficio: (($794 - $164) / $794) 100 = ~79%

Este margen es excelente para una fase inicial, indicando un modelo de negocio viable con buen potencial de crecimiento.

Estrategias de Optimización FinOps

Para garantizar la sostenibilidad y escalar eficientemente, SwiftSupport AI debe implementar las siguientes estrategias FinOps:

1. Optimización del Consumo de LLM:

* Tiering de Modelos: Implementar una lógica para seleccionar dinámicamente el modelo de LLM. Por ejemplo, utilizar %%INLINE38%% o %%INLINE39%% para tickets de menor prioridad o aquellos con alta confianza de clasificación basada en reglas heurísticas, y reservar gpt-4-turbo para casos más complejos o donde la precisión sea crítica. Esto puede reducir drásticamente los costos de LLM sin comprometer la calidad general. * Caché de Respuestas: Almacenar en caché las respuestas del LLM para tickets con contenido idéntico o muy similar (ej. preguntas frecuentes). Esto evita llamadas redundantes a la API del LLM. * Ingeniería de Prompts: Refinar continuamente los prompts para que sean concisos y extraer solo la información necesaria, minimizando el conteo de tokens de entrada y salida. * Validación de Salida: Si el LLM devuelve un formato inesperado, reintentar con un modelo más barato o un prompt simplificado antes de escalar a un modelo más caro o fallar.

1. Optimización de Infraestructura Cloud:

* Instancias Reservadas (RIs): Una vez que la carga de trabajo sea predecible, considerar la compra de RIs de 1 o 3 años para EC2 y RDS. Esto puede reducir los costos de estas instancias hasta en un 50-70% en comparación con las instancias bajo demanda. * Base de Datos Gestionada Alternativa: Evaluar proveedores de PostgreSQL como Neon.tech o Supabase, que a menudo ofrecen planes generosos para micro-startups y escalan de forma más granular que RDS, potencialmente reduciendo costos a muy baja escala. * Serverless para Webhooks: Aunque Spring Boot con Virtual Threads es eficiente, para picos de tráfico muy irregulares, una arquitectura serverless (ej. AWS Lambda) para el procesamiento inicial de webhooks podría ser más costo-efectiva, pagando solo por ejecución. Sin embargo, esto añade complejidad y puede no ser adecuado para el objetivo de "Producto > Infra". * Apagar Entornos No Productivos: Implementar automatización para apagar las instancias de desarrollo y staging fuera del horario laboral o cuando no estén en uso.

1. Monitoreo y Alertas:

* Implementar un monitoreo robusto del consumo de tokens de LLM y los costos asociados. Configurar alertas para picos inesperados que puedan indicar un uso ineficiente o un ataque. * Monitorizar el uso de CPU, RAM y E/S de la base de datos para asegurar que la instancia db.t3.micro sea suficiente o para planificar una actualización proactivamente si es necesario.

Estas optimizaciones permitirán a SwiftSupport AI mantener un control estricto sobre sus gastos operativos mientras escala su base de clientes y expande sus capacidades.