Remezcla Demo API

.NET 9 Web API for conversational taco ordering with Salesforce Agentforce integration.

Part of the Remezcla demo:

• remezcla-demo-api - This repository (API backend)
• remezcla-demo-agent - Salesforce Agentforce metadata
• remezcla-demo-ui - React customer/business UI

---

Overview

The Remezcla API provides a REST backend for a demo taco ordering system that integrates with Salesforce Agentforce for conversational ordering. The API handles order management, menu/inventory data, allergy protocols, and real-time collaboration between customer UI and AI agent.

Key Features:

• Conversational ordering via Salesforce Agentforce (6 agent functions)
• Anonymous session-based order tracking (no authentication required for customers)
• Real-time order synchronization (polling-based, AppLink service mesh compatible)
• Mock agent infrastructure for testing without Salesforce
• Demo configuration with seed data

---

Architecture

System Components

Order Management:

• DraftOrderService - Orchestrates order mutations with version control and hint broadcasting
• OrderSessionManager - Manages anonymous session cookies (__remezcla_order_session)
• OrderChangeNotifier - Publishes order change hints for real-time UI updates

Agent Integration:

• 6 Jobs API endpoints optimized for Agentforce: Get_Agent_Context, Update_Order, Get_Allergy_Guidance, Get_User_History, Save_Memory, Submit_Order
• XML context pattern - Responses include xmlPrompt with structured data for LLM consumption
• External Service integration via Heroku AppLink

Real-time Collaboration:

• Polling-based updates (1-second interval) for order synchronization
• Replaces SignalR (incompatible with Heroku AppLink service mesh WebSocket handling)
• Works for both UI-initiated and agent-initiated order changes

Mock Infrastructure (FEATURE_MOCK_AGENT=true):

• /mock/agent/* endpoints that proxy to real controllers
• Configurable behavior presets (helpful, busy, error-prone, silent)
• /mock UI harness for testing scenarios without Salesforce

Authentication

Dual Authorization Policy:

• Salesforce AppLink - X-Client-Context headers parsed into ClaimsPrincipal (for agent calls)
• JWT Bearer - RS256 tokens for authenticated users (optional, demo uses anonymous sessions)
• Anonymous - Most endpoints allow unauthenticated access via session cookies

Database

• PostgreSQL with Entity Framework Core
• Migrations for schema versioning
• Automatic seed data (demo user, menu items, ingredients, allergy protocols)

---

Local Development

First Time Setup

1. Copy the example env file:

cp .env.example .env

2. Get the database URL from Heroku:

heroku config:get DATABASE_URL -a <your-api-app>
# Paste into .env as: DATABASE_URL=postgres://...

3. Update CORS origins in .env if needed (defaults work for standard local dev)

Running the API

Recommended (automatically kills existing servers and loads .env):

./run.sh

Alternative:

dotnet run

The API will start on http://localhost:5050

Testing

# Health check
curl http://localhost:5050/api/health

# Test authentication
curl -X POST http://localhost:5050/api/user/authenticate \
  -H "Content-Type: application/json" \
  -d '{"username": "demo", "password": "demo"}'

# View API documentation
open http://localhost:5050/swagger

Database Migrations

# Create new migration
dotnet ef migrations add MigrationName

# Apply migrations
dotnet ef database update

---

API Reference

Public Endpoints

Menu & Inventory:

• GET /api/menu - List menu items with ingredients
• GET /api/menu/{id} - Get menu item details
• GET /api/inventory - List current inventory

Orders:

• GET /api/orders/draft - Get or create active draft order
• POST /api/orders/draft/operations - Mutate draft order (add/remove/update items)
• POST /api/orders/draft/submit - Submit order

Agent Jobs API (Agentforce integration):

• GET /api/AgentContext - Load menu, user, orders, memory (hydration)
• POST /api/AgentOrder/batch-update - Batch order operations
• GET /api/AgentAllergy/guidance - Get allergy protocols
• GET /api/AgentUser/history - Get past orders
• POST /api/AgentMemory/save - Store user preference
• POST /api/AgentOrder/submit - Submit order

Mock Infrastructure (when FEATURE_MOCK_AGENT=true):

• POST /mock/agent/hydrate - Mock agent context hydration
• POST /mock/agent/update-order - Mock order updates
• GET /mock/admin/events - View mock event log

Full API documentation available at /swagger when running locally or in development mode.

---

Configuration

Environment Variables

Required:

• DATABASE_URL - PostgreSQL connection string (Heroku format)

Optional:

• ALLOWED_ORIGINS - CORS allowed origins (default: localhost:3000, localhost:5173)
• FEATURE_MOCK_AGENT - Enable mock agent endpoints (default: false)
• JWT_PRIVATE_KEY - RS256 private key (auto-generated in development)
• JWT_PUBLIC_KEY - RS256 public key (auto-generated in development)

Heroku-Specific Variables

When deploying to Heroku with AppLink:

• HEROKU_APP_ID - Auto-set by Heroku
• HEROKU_APPLINK_SERVICE_MESH_ACKNOWLEDGE_RISK_BYPASS - Set to true for bypass routes
• APP_PORT - Used by AppLink service mesh wrapper

See SETUP.md for complete Heroku deployment configuration.

---

Demo Data & Customization

The API includes seed data for demonstration:

• Default user: Marvella (demo/demo credentials)
• Menu items: 8 classic tacos + custom creation option
• Ingredients: ~20 ingredients with allergen data
• Allergy protocols: Gluten, dairy, nuts, soy, shellfish, eggs

Customization:

• Edit seed data in Data/DbInitializer.cs
• Modifications take effect on next database initialization

Development Helpers:

• POST /api/demo/config - Update demo configuration
• POST /api/demo/orders/generate - Generate sample orders
• POST /api/demo/inventory/reset - Reset inventory to defaults

---

Deployment

Quick Deploy to Heroku

If you already have Heroku + Salesforce + AppLink configured:

# Add Heroku remote
heroku git:remote -a <your-api-app>

# Deploy
git push heroku main

Complete System Setup

First time setting up Heroku, Salesforce, AppLink, and Agentforce?

See SETUP.md for the complete end-to-end setup guide including:

• Heroku app creation and AppLink addon
• Salesforce Connected App and External Service configuration
• Agent metadata deployment
• UI deployment and configuration
• Troubleshooting common issues

---

Development

Running Tests

dotnet test

Code Formatting

# Check formatting
dotnet format --verify-no-changes

# Apply formatting
dotnet format

---

Technology Stack

• .NET 9
• ASP.NET Core Web API
• Entity Framework Core with PostgreSQL
• JWT Bearer Authentication (RS256)
• SignalR (for real-time updates, polling fallback for AppLink environments)
• Heroku AppLink for Salesforce integration
• Swagger/OpenAPI for API documentation