---
license: mit
pipeline_tag: text-generation
tags:
- agent
- agent-graph
- state-machine
- multi-agent-orchestration
- gemini-2.5-flash
- zod
- system-design
- production-ai
language:
- en
- es
library_name: nextjs
---

# 🚗 AutoApp — Production Agentic State Machine Blueprint

> **System Card & Architecture Blueprint:** An enterprise-ready, deterministic multi-agent state machine designed for automotive B2B workflows. Deconstructs monolithic LLM prompts into isolated, typed worker nodes, adversarial evaluation gates, and Human-in-the-Loop (HITL) checkpoints.

* **GitHub Repository:** [thomasskarp/autoapp](https://github.com/thomasskarp/autoapp)
* **Living Architecture Map:** [AGENT_GRAPH.md](https://github.com/thomasskarp/autoapp/blob/main/AGENT_GRAPH.md)

---

## 📌 Context: Deconstructing the Monolithic Mega-Prompt

In automotive retail, dealership sales reps submit inventory data via informal messages (*"Just took in a 2021 Toyota Corolla XEI with 45k km, clean title, asking 22M ARS"*). 

Early prototypes that used a single monolithic prompt to extract data, estimate official market prices, enforce 20% dealership margins, and write ads broke down due to the **non-linear failure trap**:
$$\mathbf{P}(\text{success}) = \prod_{i=1}^{n} p_i$$
Without intermediate verification, errors in early reasoning compound across the entire pipeline.

---

## 🗺️ State Machine Flow

```
[User Input] 
     │
     ▼
[1. Intent Router (< 15ms)] ──(Add Stock)──► [2. Spec Extractor (Gemini + Zod)]
                                                        │
                                                        ▼
                                             [3. Relational Valuator]
                                             (PostgreSQL pg_trgm GIN in < 5ms)
                                                        │
                                                        ▼
                                             [4. Concurrent Fan-Out]
                                             (Parallel copy: IG, FB, MeLi, WhatsApp)
                                                        │
                                                        ▼
                                             [5. Quality & Margin Checker]
                                             (Adversarial Gate: Margin 15-25%)
                                                        │
                                                        ▼
                                             [6. Human-in-the-Loop Gate]
                                             (Awaits human approval)
                                                        │
                                                        ▼
                                             [7. Transactional Dispatcher]
                                             (Serial write to PostgreSQL & APIs)
```

---

## ⚙️ Key Architectural Principles

1. **Harness Engineering ("Humans Steer, Agents Execute"):** Software engineers define constraints, typed schemas, and invariant gates. The model performs execution within bounded sandboxes.
2. **Adversarial Verification:** *An agent should never grade its own homework.* Generative copywriters and extractors are audited by an independent, non-generative Quality Checker gate.
3. **Clean-Context Workers:** Each node executes with isolated, minimal context, eliminating cognitive drift and cutting unnecessary token usage.
4. **Relational Grounding over Vector Search:** Numerical catalog valuations are performed via PostgreSQL `pg_trgm` GIN inverted indexes (< 5ms) rather than asking the LLM to recall numbers.
5. **Serial Mutations vs. Parallelized Reads:** Multichannel copywriting runs in parallel (fan-out); database updates and marketplace publications run strictly serially.

---

## 📦 Typed State Interface (`AutoAppState`)

```typescript
export interface AutoAppState {
  sessionId: string
  inputMessage: string
  intent?: 'ADD_STOCK' | 'APPRAISAL' | 'LEAD_CRM' | 'GENERAL_FAQ'
  draftVehicle?: {
    marca: string
    modelo: string
    anio: number
    km: number
    precio_venta: number
  }
  officialValuation?: {
    tablePrice: number
    marginPercent: number
    source: 'POSTGRES_PG_TRGM'
  }
  generatedCopies?: {
    instagram?: { caption: string; hashtags: string[] }
    facebook?: { title: string; description: string }
    mercadolibre?: { title: string; description: string }
    whatsapp?: { chat_pitch: string }
  }
  validation: {
    passed: boolean
    errors: string[]
  }
  requiresConfirmation: boolean
}
```

---

## 🔬 Benchmark & Latency Telemetry

| Node | Mechanism | Latency | Guardrail |
| :--- | :--- | :--- | :--- |
| **Router** | Regex + Semantic classification | `< 15ms` | Fallback to GENERAL_FAQ |
| **Extractor** | Gemini 2.5 Flash + Zod | `~250ms` | Strict schema validation |
| **Valuator** | PostgreSQL `pg_trgm` GIN | `< 5ms` | Grounded against official books |
| **Copy Fan-Out** | Asynchronous concurrency | `~2.2s` | Platform character limits |
| **Quality Checker** | Deterministic business rules | `< 2ms` | Rejects margin < 15% |
| **HITL Gate** | Suspended state checkpoint | Human | Explicit confirmation button |

---

## 📄 License & Attribution

Developed by **Thomas Skarp** as part of the **AutoApp** Automotive B2B SaaS platform. Distributed under the MIT License.