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 the backend's Postgres KB
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 (indexed)
│   ├── integrations/          # 11 integration docs (indexed)
│   ├── fields/                # 3 field reference docs (indexed)
│   ├── guides/                # 7 guides (indexed)
│   ├── relations/             # 3 cross-feature dependency maps (indexed)
│   ├── troubleshooting/       # 1 error reference (indexed)
│   └── developer/             # 19 developer docs (NOT 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 (indexed)
├── reseller/
│   └── onboarding/            # 9 reseller onboarding flows (indexed)
├── docs/                      # 4 system docs (indexed as `shared`)
├── scripts/                   # Extract + backend ingest pipeline, validators
├── azure-export/              # Historical snapshot of the Azure AI Search index definitions (Azure exit, 2026-09-28)
├── .github/workflows/         # CI/CD: KB sync on push, validation on PR
├── _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 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

Knowledge store

Content is synced to upvendo-backend's Postgres KB (scripts/ingest-to-backend.js → /api/internal/kb/ingest); the backend embeds and serves search. Each chunk carries an audience:

Audience	Source	Content
shared	shared/ (excl. developer/) + docs/	Features, integrations, fields, guides, relations, and the repo's own meta-docs
merchant	merchant/	Merchant onboarding
reseller	reseller/	Reseller onboarding
admin	global-admin/	Admin-only docs (e.g. the SUNMI DMP runbook) — queried only by global-admin Emily

{env} is test (branch testing) or prod (branch production). The shared/developer/ section is intentionally excluded from 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. Ingest changed/deleted files into the backend Postgres KB (the backend embeds)
3. Invalidate proxy cache
4. Notify Slack

Manual full sync available via GitHub Actions workflow_dispatch. See docs/indexing-process.md.

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