CatyAI — Architecture Knowledge Base

Version: v3.0 | Date: June 2026 | Author: Adrian Vitan Lopes, Chief Architect

1. Core Paradigm Shift

Dimension	Web 2.0	Agentic Web (CatyAI v3)
Consumer	Human browser	LLM agent / AI crawler
Interface	HTML frontend	Structured data endpoints
Discovery	SEO keywords	Semantic + semiotic signals
Commerce	Click-to-buy	Deterministic pipeline
Architecture	Reactive / semantic	Predictive / semiotic
Trust model	HTTPS	ECC-signed offers (Zero-Trust)

Key insight: Traditional semantic architectures store definitions ("what a product is"). Semiotic architecture intercepts signals ("what the market intends right now"). CatyAI sits at the signal layer.

2. The Four Pillars

2.1 NAP V3 (Native AI Protocol)

What it is: The machine-readable discovery layer that exposes verified, structured business data directly to AI crawlers — without requiring HTML rendering.

Core components:

Endpoint	Path	Purpose
llms.txt	`GET /geo/v2/llms.txt?domain=X`	NAP V3 protocol document for AI agents
Well-known	`/.well-known/*`	Standard discovery for AI crawlers
GEO Answer	`POST /geo/v2/answer`	EdDSA-signed query response
JWKS	`GET /.well-known/jwks.json`	Public key for signature verification

How it works:

AI crawler (GPTBot, ClaudeBot, GoogleOther, etc.) hits /.well-known or llms.txt
System detects crawler type via src/middleware/ai-crawler-detection.js
Returns structured NAP document with verified product/business data
Every response is EdDSA-signed (key ID catyai-akl-v2-2026-05-05)

Code references:

src/api/geo/llms-txt-v2.js — NAP V3 llms.txt generator
src/api/geo/answer-v2.js — GEO signed answer endpoint
src/middleware/ai-crawler-detection.js — AI crawler fingerprinting
src/services/sentinel-v2/signing.js — Ed25519 signing (NAP V2 internal name)

Supported AI crawlers: GPTBot, ChatGPT-User, ClaudeBot, anthropic-ai, PerplexityBot, Google-Extended, GoogleOther, BingPreview, FacebookBot, Bytespider, cohere-ai, Applebot-Extended.

2.2 Predictive Intent Engine (The Scout)

What it is: A decoupled market intelligence system that pre-computes buying intent signals before queries arrive, reducing query-time vector search from O(N) to O(K) complexity.

Why it matters: With 4,500+ GoMag merchants, per-query market analysis would be O(N) per request. The Scout pre-processes intent asynchronously, so each widget query hits an already-enriched vector space.

Flow:

Market Intelligence Worker (cron 04:00 UTC / every 4h)
     │
     ▼
DeepSeek API ──► Fetch top-3 urgency intents per industry
     │           (Fashion, Automotive, Electronics, etc.)
     ▼
AWS SNS: caty-intent-global.fifo ──► Fan-out to all subscribers
     │
     ▼
AWS SQS: caty-intent-global.fifo ──► Queued for processing
     │
     ▼
AutoSEO Intent Worker (ECS Fargate)
     │   ├── Embed intent_text via OpenAI text-embedding-3-small (1536-dim)
     │   ├── Semantic search for matching products in Qdrant
     │   └── Hot-update product metadata with TTL (12–48h)
     ▼
Qdrant Vector DB ──► Enriched product space ready for queries

Complexity reduction:

Before: O(N) — per-query market analysis for every widget
After:  O(K) — K = number of industries (fixed, ~10-20 verticals)

DeepSeek prompt contract: Returns JSON array with intent_text, urgency_score (0–1), ttl_hours (12–48), reason. Zero hardcoded intents — LLM generates dynamically from current date context.

Fallback: When SNS is not configured (SNS_INTENT_GLOBAL_ARN unset), Scout calls processIntentDirect() and writes to Qdrant inline without queuing.

Code references:

src/services/predictive-intent.js — Scout service, DeepSeek integration, SNS publish
src/workers/autoseo-intent-worker.js — SQS consumer, embedding, Qdrant hot-update
src/workers/market-intelligence-worker.js — Cron scheduler (triggers intent cycle)
infrastructure/intent-topics.tf — SNS/SQS Terraform configuration

2.3 Cameleon Semantic Lens

What it is: A vertical detection and payload normalization layer that converts raw platform data (Shopify, WooCommerce, GoMag, WA messages) into a UnifiedSemanticContext consumed by AKL V2 and the brain.

Why it matters: CatyAI serves multiple verticals. Without normalization, every downstream component would need platform-specific logic. Cameleon abstracts this at the intake layer.

Vertical detection:

Vertical	Entity types	Platform examples
`retail`	order, product, customer, cart	Shopify, WooCommerce, GoMag
`real-estate`	property, lead, inquiry, agent	Custom CRMs
`medical`	patient, appointment, consultation	Healthcare platforms
`finance`	invoice, transaction, tax_document	Billing systems
`unknown`	unknown	Fallback

UnifiedSemanticContext shape:

{
  vertical: 'retail',
  entity_type: 'order',
  primary_id: '<stable-id>',
  primary_name: '<human-label>',
  attributes: { /* vertical-specific */ },
  metadata: {
    source_platform: 'gomag',
    normalized_at: '<ISO timestamp>',
    raw_keys: [...],
    detection_method: 'rule-based' | 'widget-vertical' | 'fallback'
  }
}

Code references:

src/core/cameleon/schema.js — UnifiedSemanticContext typedef + VERTICALS + ENTITY_TYPES
src/core/cameleon/adapters/retail.js — Retail adapter (Shopify, WooCommerce, GoMag, Generic)
src/core/tools/cameleon-lite.js — Lightweight version for MCP tools

2.4 AKL V2 (AI Knowledge Layer)

What it is: A per-widget isolated AI response layer that signs every outbound response with Ed25519, exposes structured actions (add-to-cart, order-tracking, etc.), and provides a deterministic API surface for AI agents.

Per-client isolation: Each widget has its own Qdrant collection (1536-dim), its own knowledge base, and its own AKL response envelope. Brain instances are ephemeral — state lives in the vector DB.

AKL Response Envelope:

json

{
  "answer": "<LLM response>",
  "sources": [...],
  "content_hash": "<SHA256>",
  "ttl": 86400,
  "nap": { "widget_id": "...", "domain": "...", "verified": true },
  "available_actions": {
    "add_to_cart": { "type": "commerce", ... },
    "track_order": { "type": "support", ... }
  },
  "signature": {
    "alg": "EdDSA",
    "kid": "catyai-akl-v2-2026-05-05",
    "sig": "..."
  },
  "jwks_uri": "https://api.caty.ai/.well-known/jwks.json"
}

Signing details:

Algorithm: Ed25519 (RFC 8032 / RFC 8037) via @noble/ed25519
Canonicalization: RFC 8785 JCS via canonicalize package
Key storage: AWS Secrets Manager caty/production/akl-private-key
Key ID: catyai-akl-v2-2026-05-05

TTL strategy (by confidence):

Confidence	TTL
≥ 0.75	86400s (24h)
≥ 0.50	3600s (1h)
≥ 0.30	600s (10min)
< 0.30	60s (1min)

Code references:

src/services/akl/response-builder.js — AKL envelope builder
src/services/akl/signature.js — V1 signing (Node native crypto, legacy)
src/services/sentinel-v2/signing.js — V2 signing (Ed25519, production)
src/services/akl/action-schema.js — Available commerce/support actions
src/core/brain/v2-brain.js — V2 brain integration with AKL signing
src/core/brain/index.js — V1 brain integration with AKL signing

3. Zero-Trust Transaction Protocol

Problem: In the Agentic Web, an autonomous LLM agent could hallucinate a 90% discount at checkout. Without deterministic price verification, any AI-to-AI commerce pipeline is financially unsafe.

Solution — Three-layer Zero-Trust:

Layer 1: Price Sealing
  ├── Every offer published via NAP V3 is signed with Ed25519
  └── Signature covers: product_id + price + currency + timestamp

Layer 2: Transaction Validation
  ├── Agent submits transaction with offer signature
  ├── Backend verifies signature deterministically
  └── Rejects any transaction with mismatched or missing signature

Layer 3: Frontend Independence
  ├── Entire pipeline works without HTML frontend
  └── AI agent → /geo/v2/answer → action execution → order confirmed

Verification flow:

AI Agent
  │  POST /geo/v2/answer (query product)
  ▼
GEO Gateway
  │  Returns signed product offer (EdDSA sig + content_hash)
  ▼
AI Agent validates signature via JWKS URI
  │  jwks_uri: /.well-known/jwks.json
  ▼
AI Agent executes purchase action
  │  Submits original signed offer
  ▼
Backend verifies signature ──► Order confirmed

Code references:

src/services/sentinel-v2/signing.js — EdDSA sign/verify
src/api/geo/answer-v2.js — Signed offer generation
src/services/akl/response-builder.js — Envelope + content_hash

4. Scalability Architecture

[Market Intelligence Worker]
         │
         ▼
  SNS: caty-intent-global.fifo
         │
         ├──► SQS: caty-intent-global.fifo ──► ECS: autoseo-intent-worker
         │        (universal queue, industry from payload)
         │
         └──► Future subscribers (analytics, billing, alerts)

Key design decision: Single universal SNS topic with industry encoded in payload. Previous design had per-industry topics (intent.fashion, intent.automotive) — migrated to single topic to eliminate Terraform changes when adding new verticals.

ECS Auto-scaling Workers

Service	Type	Trigger
`caty-api`	ECS Fargate	ALB request count
`autoseo-intent-worker`	ECS Fargate	SQS queue depth
`crawler-worker`	ECS Fargate	SQS crawl jobs queue

Fault Tolerance

SQS provides at-least-once delivery with visibility timeout
Failed intent processing leaves message in queue for retry
Qdrant writes are idempotent (upsert by product_id)
TTL metadata auto-expires, no manual cleanup needed

5. Data Flow Diagrams

User / AI Agent
     │  POST /api/widget/chat
     ▼
AI Crawler Detection (middleware)
     │  Sets req.geoMode + req.crawlerType
     ▼
V2 Brain (src/core/brain/v2-brain.js)
     │
     ├── Cameleon Lens ──► UnifiedSemanticContext
     │
     ├── Qdrant Search ──► knowledge_results (1536-dim)
     │   (pre-enriched by Predictive Intent Engine)
     │
     ├── LLM Response (OpenAI / DeepSeek)
     │
     └── AKL V2 Signing ──► EdDSA envelope
          │
          ▼
     Response to caller (signed JSON)

Predictive Intent Cycle

cron (every 4h)
     │
     ▼
market-intelligence-worker.js
     │  runPredictiveIntentCycle()
     ▼
predictive-intent.js
     │  fetchMarketIntent(industry, date) ──► DeepSeek API
     │  [top-3 intents per industry, urgency + TTL]
     │
     ▼ (if SNS configured)
AWS SNS: caty-intent-global.fifo
     │  MessageGroupId = industry
     │  MessageDeduplicationId = uuid
     ▼
AWS SQS: caty-intent-global.fifo
     │
     ▼
autoseo-intent-worker.js (ECS)
     │  embedIntentText() ──► OpenAI text-embedding-3-small (1536-dim)
     │  searchSimilarProducts() ──► Qdrant
     │  hotUpdateQdrantMetadata() ──► TTL payload_update
     ▼
Qdrant (enriched product vectors ready for queries)

6. API Contracts

GEO Gateway

Method	Path	Auth	Description
`POST`	`/geo/v2/answer`	None (public)	Signed knowledge query
`GET`	`/geo/v2/llms.txt`	None (public)	NAP V3 machine-readable document
`GET`	`/geo/v2/catalog-v2`	None (public)	Product catalog for AI crawlers
`GET`	`/geo/v2/manifest`	None (public)	Widget capabilities manifest

POST /geo/v2/answer — Request:

json

{
  "widget_id": "<uuid>",
  "question": "<user query>",
  "language": "en|ro|es|de|fr|it"
}

POST /geo/v2/answer — Response:

json

{
  "answer": "...",
  "content_hash": "<sha256>",
  "ttl": 3600,
  "sources": [...],
  "signature": { "alg": "EdDSA", "kid": "...", "sig": "..." },
  "jwks_uri": "https://api.caty.ai/.well-known/jwks.json",
  "available_actions": { ... }
}

Method	Path	Auth	Description
`POST`	`/api/widget/chat`	API Key	Main chat endpoint

Admin — Predictive Intent

Method	Path	Auth	Description
`POST`	`/api/admin/system/predictive-intent`	Admin JWT	Trigger intent cycle manually

Well-Known (NAP Discovery)

Method	Path	Description
`GET`	`/.well-known/jwks.json`	EdDSA public key
`GET`	`/.well-known/ai-context`	Widget AI context manifest

7. Infrastructure Map

Region: AWS eu-west-1

Compute

Service	Name	Purpose
ECS Fargate	`caty-api`	Main API server
ECS Fargate	`autoseo-intent-worker`	Qdrant hot-update worker
ECS Fargate	`crawler-worker`	Product crawler
ECS Fargate	`market-intelligence-worker`	Scout / intent cron

Messaging

Service	Name	Pattern
AWS SNS	`caty-intent-global.fifo`	Fan-out publisher
AWS SQS	`caty-intent-global.fifo`	Intent processing queue
AWS SQS	`caty-crawl-jobs.fifo`	Crawl job queue

Storage

Service	Purpose	Details
Qdrant (self-hosted)	Vector DB	1536-dim (OpenAI text-embedding-3-small), per-widget collections
Redis	Cache + TTL intents	Intent expiry, session cache
MongoDB (DocumentDB)	Document store	Widget, CrawledProduct, Session models
AWS Secrets Manager	Key storage	`caty/production/akl-private-key` (Ed25519 seed)

Networking

Private subnets: subnet-0f43a83a818e150d5, subnet-0053d69b988070294
ECS Security Group: sg-085b48086aced22e4

8. Competitive Moat

Advantage	Technical Basis
Deterministic AI-to-AI commerce	EdDSA-signed offers, no hallucination possible
NAP V3 direct pipeline	AI crawlers get structured data without HTML parse
Predictive intent at scale	O(K) complexity, not O(N) — works at 4,500+ merchants
Per-client isolated brain	Qdrant collection per widget, no cross-contamination
Semiotic architecture	Intercepts market signals, not just product definitions

9. Key Dependencies

Package	Version	Purpose
`@noble/ed25519`	latest	Ed25519 signing (NAP V2 / AKL V2)
`canonicalize`	latest	RFC 8785 JCS canonicalization
`@aws-sdk/client-sns`	v3	SNS fan-out
`@aws-sdk/client-sqs`	v3	SQS message processing
`openai` (npm)	latest	Embeddings (1536-dim) + DeepSeek base URL
`isbot`	latest	Bot/crawler UA detection
`mongoose`	latest	DocumentDB models

Source: CatyAI Arhitectura Semiotică și Protocolul Zero-Trust (whitepaper, June 2026) + codebase inspection.

CatyAI — Architecture Knowledge Base

1. Core Paradigm Shift

2. The Four Pillars

2.1 NAP V3 (Native AI Protocol)

2.2 Predictive Intent Engine (The Scout)

2.3 Cameleon Semantic Lens

2.4 AKL V2 (AI Knowledge Layer)

3. Zero-Trust Transaction Protocol

4. Scalability Architecture

ECS Auto-scaling Workers

Fault Tolerance

5. Data Flow Diagrams

Widget Chat Flow (V2 Brain)

Predictive Intent Cycle

6. API Contracts

GEO Gateway

Widget Chat

Admin — Predictive Intent

Well-Known (NAP Discovery)

7. Infrastructure Map

Compute

Messaging

Storage

Networking

8. Competitive Moat

9. Key Dependencies

CatyAI — Architecture Knowledge Base ​

1. Core Paradigm Shift ​

2. The Four Pillars ​

2.1 NAP V3 (Native AI Protocol) ​

2.2 Predictive Intent Engine (The Scout) ​

2.3 Cameleon Semantic Lens ​

2.4 AKL V2 (AI Knowledge Layer) ​

3. Zero-Trust Transaction Protocol ​

4. Scalability Architecture ​

SNS Fan-out Pattern ​

ECS Auto-scaling Workers ​

Fault Tolerance ​

5. Data Flow Diagrams ​

Widget Chat Flow (V2 Brain) ​

Predictive Intent Cycle ​

6. API Contracts ​

GEO Gateway ​

Widget Chat ​

Admin — Predictive Intent ​

Well-Known (NAP Discovery) ​

7. Infrastructure Map ​

Compute ​

Messaging ​

Storage ​

Networking ​

8. Competitive Moat ​

9. Key Dependencies ​

CatyAI — Architecture Knowledge Base

1. Core Paradigm Shift

2. The Four Pillars

2.1 NAP V3 (Native AI Protocol)

2.2 Predictive Intent Engine (The Scout)

2.3 Cameleon Semantic Lens

2.4 AKL V2 (AI Knowledge Layer)

3. Zero-Trust Transaction Protocol

4. Scalability Architecture

SNS Fan-out Pattern

ECS Auto-scaling Workers

Fault Tolerance

5. Data Flow Diagrams

Widget Chat Flow (V2 Brain)

Predictive Intent Cycle

6. API Contracts

GEO Gateway

Widget Chat

Admin — Predictive Intent

Well-Known (NAP Discovery)

7. Infrastructure Map

Compute

Messaging

Storage

Networking

8. Competitive Moat

9. Key Dependencies