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/              # 63 feature docs (Azure-indexed)
│   ├── integrations/          # 11 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/             # 19 developer docs (NOT Azure-indexed)
│       ├── architecture/      # Backend, proxy, data model, frontends
│       ├── api/               # Endpoints, auth, webhooks
│       ├── patterns/          # Service-orchestrator, payment flow, jobs
│       ├── integrations/      # Per-integration developer notes
│       └── debugging/         # Common errors, payment debugging
├── merchant/
│   └── onboarding/            # 10 merchant onboarding flows (Azure-indexed)
├── reseller/
│   └── onboarding/            # 9 reseller onboarding flows (Azure-indexed)
├── docs/                      # 4 system docs (Azure-indexed into the shared index)
├── 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	63	All Upvendo features with 6 structured sections each
Integrations	11	Square, Deliveroo, Uber Eats, Hendrickx, Vanhoutte, MPlus, Lightspeed, Shopify, ShopCaisse, etc.
Developer	19	Architecture, API, patterns, debugging, integrations (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	4	Overview, requirements, indexing process, accuracy audit
Troubleshooting	1	Error messages and solutions
Total	135	~48,100 lines

Azure AI Search Indexes

Index	Source	Content
emily-kb-shared-{env}	shared/ (excl. developer/) + docs/	Features, integrations, fields, guides, relations, and the repo's own meta-docs
emily-kb-merchant-{env}	merchant/	Merchant onboarding
emily-kb-reseller-{env}	reseller/	Reseller onboarding
emily-kb-admin-{env}	global-admin/	Admin docs — the directory does not exist yet; the index name and routing are pre-configured for it
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
POS	upvendo-pos
Kitchen Display	upvendo-kds
Field Ops	upvendo-field
Code Repair	upforge-backend