Upvendo Knowledge Base

Central source of truth for ALL Upvendo knowledge — merchant-facing, developer-facing, and AI-agent-facing.

Purpose

This repository serves as the single source of truth for the entire Upvendo platform. Multiple consumers access different slices:

1. Emily (merchant AI assistant) — reads features, integrations, guides via Azure AI Search
2. Upforge (autonomous code repair) — reads the full KB including developer docs for context
3. Claude Code (developer sessions) — reads the full KB for architecture and business rules
4. Developers — human reference for architecture, patterns, and debugging

Structure

upvendo-kb/
├── shared/
│   ├── features/              # 60 feature docs (Azure-indexed)
│   ├── integrations/          # 12 integration docs (Azure-indexed)
│   ├── fields/                # 3 field reference docs (Azure-indexed)
│   ├── guides/                # 7 guides (Azure-indexed)
│   ├── relations/             # 3 cross-feature dependency maps (Azure-indexed)
│   ├── troubleshooting/       # 1 error reference (Azure-indexed)
│   └── developer/             # 13 developer docs (NOT Azure-indexed)
│       ├── architecture/      # Backend, proxy, data model, frontends
│       ├── api/               # Endpoints, auth, webhooks
│       ├── patterns/          # Service-orchestrator, payment flow, jobs
│       └── debugging/         # Common errors, payment debugging
├── merchant/
│   └── onboarding/            # 10 merchant onboarding flows (Azure-indexed)
├── reseller/
│   └── onboarding/            # 9 reseller onboarding flows (Azure-indexed)
├── docs/                      # 3 system docs
├── scripts/                   # Azure AI Search pipeline
├── .github/workflows/         # CI/CD for auto-indexing on push
├── _template.md               # Tier 1 / Tier 2 templates
└── README.md

Statistics

Category	Files	Content
Features	60	All Upvendo features with 6 structured sections each
Integrations	12	Square, Deliveroo, Uber Eats, Hendrickx, MPlus, Lightspeed, Shopify, Kassanet, etc.
Developer	13	Architecture, API, patterns, debugging (NOT Azure-indexed)
Guides	7	How-to, FAQ, glossary, permissions, payment setup, integration comparison
Fields	3	150+ fields, options, validation rules
Relations	3	Cross-feature dependencies, backoffice-to-OO, backoffice-to-kiosk
Onboarding	19	Merchant (10) + Reseller (9) onboarding flows
Docs	3	Overview, requirements, indexing process
Troubleshooting	1	Error messages and solutions
Total	~124	~41,700 lines

Azure AI Search Indexes

Index	Source	Content
emily-kb-shared-{env}	shared/ (excl. developer/)	Features, integrations, fields, guides, relations
emily-kb-merchant-{env}	merchant/	Merchant onboarding
emily-kb-reseller-{env}	reseller/	Reseller onboarding
emily-kb-admin-{env}	global-admin/	Admin docs
emily-kb-ordering-{env}	Auto-managed by proxy	Menu data (DO NOT TOUCH)

The shared/developer/ section is intentionally excluded from Azure indexing — it's consumed directly by Upforge and Claude Code.

Feature Documentation Standard

Every feature file includes 6 actively-parsed sections that Emily uses for structured responses:

1. ## Purpose — one sentence describing what the page does
2. ## Key Concepts — 5 key terms with definitions
3. ## Actions — what users can do (create, edit, delete, etc.)
4. ## Business Rules — constraints and requirements
5. ## FAQs — common questions and answers
6. ## Troubleshooting — problem and solution pairs

CI/CD

Pushing to testing or production automatically triggers:

1. Extract knowledge from changed markdown files
2. Generate embeddings via Azure OpenAI
3. Upload to Azure AI Search indexes
4. Invalidate proxy cache
5. Notify Slack

Manual full reindex available via GitHub Actions workflow_dispatch.

Source Repositories

System	Repository
Backend	upvendo-backend
Backoffice	upvendo-backoffice
Online Ordering	zestidoo-online-ordering
Kiosk	upvendo-kiosk
Backend Proxy	upvendo-backend-proxy
Code Repair	upforge-backend