# Agento AI by WebCore Studio — Full Machine-Readable Architectural & Integration Guide

## Overview
Agento AI is a production-grade multi-tenant AI Business Operating System engineered by WebCore Studio. It connects Meta's WhatsApp Cloud Business API directly to low-latency LLM models (Claude 3.5 Sonnet / Groq Llama 3) and custom business workflow engines.

- Canonical Domain: https://orderagentapp.webcorestudio.dev
- Developer Portal: https://orderagentapp.webcorestudio.dev/developers
- REST API Guide: https://orderagentapp.webcorestudio.dev/api-docs
- OpenAPI 3.1 Spec: https://orderagentapp.webcorestudio.dev/openapi.json
- Authentication Guide: https://orderagentapp.webcorestudio.dev/auth-docs
- MCP Server Spec: https://orderagentapp.webcorestudio.dev/mcp
- CLI Tool Guide: https://orderagentapp.webcorestudio.dev/cli
- Deprecation Policy: https://orderagentapp.webcorestudio.dev/deprecation
- Brand & Corporate NAP: https://orderagentapp.webcorestudio.dev/brand
- XML Sitemap: https://orderagentapp.webcorestudio.dev/sitemap.xml
- Agent Protocol: https://orderagentapp.webcorestudio.dev/.well-known/agent.json
- MCP Manifest: https://orderagentapp.webcorestudio.dev/.well-known/mcp.json

---

## Official CLI Tool & Installation
Developers and autonomous AI agents can interact with Agento AI using multiple package distributions:
```bash
# Instant runner via npx
npx @webcorestudio/agento-cli status

# Global installation via npm
npm install -g @webcorestudio/agento-cli

# macOS / Linux via Homebrew
brew tap webcorestudio/tap && brew install agento

# Linux / Unix automated shell installer
curl -sSL https://orderagentapp.webcorestudio.dev/install.sh | bash

# Query appointments
agento appointments list --business-id <UUID>

# Trigger background automations
agento cron trigger all --business-id <UUID>
```

---

## API Standards, Versioning & Deprecation Lifecycle

### Versioning Strategy
- Current Contract Version: `2026-09-01`
- Path-based routing: `/api/v1/...` (rewritten transparently to core API)
- Response Header: `X-API-Version: 2026-09-01`

### 180-Day Deprecation & Sunset Guarantee
Breaking changes are subject to a mandatory 180-day advance notice period communicated via:
- HTTP Response Header: `Sunset: <DATE>`
- HTTP Response Header: `Deprecation: <TIMESTAMP>`
- HTTP Response Header: `Link: <https://orderagentapp.webcorestudio.dev/deprecation>; rel="deprecation"`
- Policy URL: https://orderagentapp.webcorestudio.dev/deprecation

### Rate Limiting Headers (IETF RFC)
- `RateLimit-Limit`: `120`
- `RateLimit-Remaining`: `119`
- `RateLimit-Reset`: `60`
- `RateLimit-Policy`: `120;w=60`
- `Retry-After`: Returned with HTTP 429 when quota is exceeded.

### Structured Error Model (RFC 9457)
All error responses return structured JSON:
```json
{
  "type": "https://orderagentapp.webcorestudio.dev/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication required. Please provide valid credentials.",
  "instance": "/api/hospital/appointments",
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required. Please provide valid credentials.",
    "hint": "Include Authorization: Bearer <TOKEN> or x-business-id: <UUID> header."
  }
}
```

---

## Autonomous Workflows & Jobs

### 1. Hospital OPD Booking & Patient Care Workflow
- **Patient Interaction Flow**:
  1. Patient messages the hospital's WhatsApp number.
  2. The AI assistant answers department questions, presents doctor OPD schedules, and collects patient details.
  3. A new appointment token is allocated in `hospital_appointments`.
  4. The automated reminder engine scans upcoming slots every 15 minutes and sends 24-hour and 2-hour interactive reminders (with `1=Confirm`, `2=Reschedule`, `3=Cancel` action options).
  5. When a doctor completes the consultation, the survey engine automatically asks for a 1-5 star rating. 5-star ratings prompt an invitation to write a Google Review, while low ratings immediately escalate to the patient care desk.

### 2. CA Firm & Tax Consultancy Workflow
- **Client & Filing Flow**:
  1. CA firm registers corporate and individual clients in `ca_clients`.
  2. The compliance engine scans upcoming GST, TDS, and ITR deadlines every morning.
  3. If required documents are missing, WhatsApp chasing messages are dispatched with secure upload prompts.
  4. Clients upload PDF documents (Bank statements, Form 16, purchase invoices) directly to WhatsApp.
  5. Files are OCR processed, classified into `ca_client_documents`, and stored securely in Supabase Storage with signed tokens.

### 3. Retail & E-Commerce Order Flow
- **Order & Payment Flow**:
  1. Shopper browses product catalog via WhatsApp keywords or natural language.
  2. AI assembles line items, applies dynamic tax/discounts, and generates a live Razorpay UPI checkout link.
  3. Once paid, the Razorpay webhook verifies HMAC-SHA256 signatures, transitions the order to `paid`, generates a PDF invoice, and notifies the merchant.

---

## Contact & Governance
- Parent Organization: WebCore Studio
- Brand: Agento AI
- Support: support@webcorestudios.in
- Phone: +91 87798 41346
- Address: WebCore Studio Tech Hub, Mumbai, Maharashtra 400001, India
- License: Proprietary SaaS (All Rights Reserved)