YBA Empire — Architecture v3.4

What changed since v2: Captain defined Flow as an AI agent suite for SMEs (8 always-on agents per tenant, BYOK or concierge delivery). Five specialists re-thought the architecture. The shape got simpler, not more complex.

What changed in v3.4 (later same evening): Captain locked in two more decisions — (a) the per-tenant brain uses the exact Richards Brain pattern (markdown wiki, file-system-based, no DB middleware for knowledge), and (b) on top of the 8 universal agents, each vertical has its own specialist agent layer with its own skill list and SOP.

Companion document: the detailed step-by-step development plan to take this architecture from today’s state to first paying Med tenant lives at YBA Empire Development Plan v1 — 9 phases, engineering plan, allocation, week-by-week first-90-days playbook, living-document system.

The Big Shifts vs v2

1. Flow is now a PRODUCT, not a holding-company badge. It’s the AI agent suite. Sold to real customers.
2. Edge / Terra / Med / Realty collapse from “4 parallel products” to “4 vertical configurations of Flow.” Customers still see them as separate brands (a doctor never sees the word “Flow”), but underneath they all run the same engine with different config bundles.
3. A third engine is added: the Agent Runtime. Not a new framework — just n8n (already running) + a small custom Node service (“Flow Core”) + an LLM router. The 8 agents live here.
4. (v3.4) Tenant brain = markdown wiki, exactly like Richards Brain. Postgres + pgvector for transactional data only — NEVER for knowledge. The wiki IS the brain.
5. (v3.4) Agents are three layers, not one. Foundation (8 universal) + Vertical Specialists (different per product) + Tenant Brain (markdown wiki).

The Picture (v3.4)

                          YBA SYSTEMS (the VPS)
              Coolify · Docker · Postgres · Redis · n8n
                                 |
   ┌─────────────────────────────┼─────────────────────────────┐
   │                             │                             │
┌─────────┐               ┌─────────────┐              ┌──────────────┐
│ ENGINE 1│               │  ENGINE 2   │              │   ENGINE 3   │
│BACK-OFC │               │  CONTENT    │              │   AGENTS     │
│ ERPNext │ ←—reads/writes│  Postiz +   │ ←—called by──│  Flow Core + │
│ books,  │               │  n8n + Hono │   agents     │  LLM router  │
│ CRM, HR │               │  landings   │              │  (NEW)       │
│ (txn)   │               │             │              │              │
└─────────┘               └─────────────┘              └──────────────┘
                                                              ▲
                                                              │
                                ┌─────────────────────────────┴────────────────────────────┐
                                │      PER-TENANT BRAIN (markdown wiki — Richards Brain)   │
                                │      /opt/flow/tenants/<id>/                             │
                                │      ├── CLAUDE.md  (tenant schema)                      │
                                │      ├── index.md   (catalog)                            │
                                │      ├── log.md     (chronological)                      │
                                │      ├── raw/       (source docs)                        │
                                │      └── wiki/      (sources/entities/concepts/analyses) │
                                │      Obsidian-compatible · file-system source of truth   │
                                └──────────────────────────────────────────────────────────┘
                                                              ▲
                                              ┌───────────────┴───────────────┐
                                              │  YBA FLOW (the product)       │
                                              │  8 universal foundation agents│
                                              │  + per-vertical specialists   │
                                              │  per tenant                   │
                                              └───────────────────────────────┘
                                                              ▲
                                              ┌───────────────┴───────────────┐
                                              │   Vertical configs / brands   │
                                              │   Edge · Terra · Med · Realty │
                                              │   + Flow direct (BYOK tier)   │
                                              └───────────────────────────────┘

The Three-Layer Agent Architecture (v3.4)

Captain confirmed every product needs different specialist agents on top of the universal foundation. So the agent architecture is now three layers:

┌─────────────────────────────────────────────────────────────────────┐
│  LAYER 3 — PER-TENANT BRAIN  (every tenant's own wiki)              │
│  Markdown vault, Obsidian-compatible, Richards Brain pattern.       │
│  Same structure as /opt/claude-workspace/projects/richards-brain.   │
│  Cheap, effective, owner can browse it themselves.                  │
└─────────────────────────────────────────────────────────────────────┘
                                  ▲
┌─────────────────────────────────┴───────────────────────────────────┐
│  LAYER 2 — VERTICAL SPECIALIST AGENTS  (different per product)      │
│                                                                      │
│  Edge:    brand-voice · content-clipper · per-platform social ·     │
│           engagement-monitor · analytics                            │
│                                                                      │
│  Terra:   agronomist · livestock · irrigation/water ·               │
│           commodity-prices · equipment-maintenance                  │
│                                                                      │
│  Med:     claims-processing · clinical-notes · NAPPI/ICD-10 ·       │
│           patient-triage · medical-aid liaison                      │
│                                                                      │
│  Realty:  listing-syndication · buyer-matching · deeds-tracker ·    │
│           valuation · FICA-compliance                               │
│                                                                      │
│  Each vertical's specialist list + skill set + SOP locks in when    │
│  Captain provides that product's vision document.                   │
└─────────────────────────────────────────────────────────────────────┘
                                  ▲
┌─────────────────────────────────┴───────────────────────────────────┐
│  LAYER 1 — FOUNDATION (8 universal agents — every tenant)           │
│                                                                      │
│  1. Infrastructure & Security    5. Front Desk                      │
│  2. Development                  6. Customer Care                   │
│  3. HR Executive Assistant       7. Call Transcription & Follow-up  │
│  4. Accounts                     8. Executive Assistant             │
└─────────────────────────────────────────────────────────────────────┘

Why this works: - Layer 1 is universal because every business has the same admin spine — HR, Accounts, Front Desk, Customer Care. Build once, ship to every tenant. - Layer 2 is what makes each product VALUABLE to its industry — the specialist knowledge a doctor or farmer or estate agent actually pays for. - Layer 3 is the customer’s competitive memory — their data, their voice, their processes. The thing they can’t move and won’t churn from.

Vertical specialist agents are defined when each vision lands. Edge specialists are roughly known from the Edge vision doc. Terra / Med / Realty get their full Layer 2 definition when Captain provides those visions — at which point the empire architecture goes to v4 / v5.

The Per-Tenant Brain (Layer 3) — exactly like Richards Brain

Every tenant gets a knowledge brain built using the exact same structure as Richards Brain:

/opt/flow/tenants/<tenant-id>/
├── CLAUDE.md           # the tenant's schema + house rules
├── index.md            # catalog of every page in the brain
├── log.md              # chronological record of operations
├── raw/                # source documents the business uploads
└── wiki/
    ├── sources/        # one summary per ingested source
    ├── entities/       # people, suppliers, customers, tools
    ├── concepts/       # ideas, processes, frameworks
    ├── analyses/       # synthesised answers
    └── meta/           # health/dashboards

Every page is markdown with YAML frontmatter and [[wikilinks]] for cross-references. Obsidian-compatible — the owner can open their own brain in Obsidian and read it like a second brain.

Why markdown-only: 1. Cheap. Files on disk. Near-zero per-tenant storage cost vs running a database per tenant. 2. Effective. Markdown is the format LLMs read best. Agents read/write directly to the vault — no ORM, no DB middleware, no schema migrations. 3. Same as ours. Captain has already proven this pattern works on his own second brain. Dogfood = product. 4. Auditable. The owner can browse their brain themselves at any time. No black box.

What Postgres is still for: transactional data only — bookings, customer rows that need fast lookup, billing events. NOT knowledge. The wiki IS the knowledge.

pgvector (semantic search) is OPTIONAL — built as a derived index over the markdown if a tenant needs it. The markdown is always the source of truth. Lose the index, rebuild it from the files.

The 8 Agents (the foundation — Layer 1)

Every business gets the same 8 agents. Each agent has its own role, its own knowledge base, and its own LLM model picked per-task:

The model is per-task, not per-agent. The same agent can run cheap tasks on Haiku and accuracy-critical tasks on Opus. Captain swaps models by editing one config file — never by touching agent code.

Cost per tenant (moderate use, ~5-15 staff): ~R2,700/month in LLM + voice spend. At 5 tenants total ~R13,500/month in API costs against R90k+ in concierge revenue.

The Five Decisions (re-picked for v3)

1. How is the engine built?

v3 pick: Three engines — back-office (ERPNext) + content (Postiz/n8n/Hono) + agent runtime (Flow Core).

Reject: LangGraph, CrewAI, AutoGen — none solve the hard problem (multi-tenant + scheduling + integrations to ERPNext/Postiz/Twilio). They solve “structure one agent’s reasoning,” which n8n + a small Node service already covers.

Pick: n8n (scheduler + triggers, already running) + Flow Core (~2-3k lines of custom code, the only new thing we write) + LiteLLM for LLM provider abstraction + FastAPI thin layer for tenant lookup, BYOK, and cost logging.

2. What’s special about each product?

v3 pick: Edge / Terra / Med / Realty are CONFIGURATIONS of Flow, not parallel products.

Each vertical brand gets: - Industry-tuned agent prompts (HR knows HPCSA for Med; Front Desk knows FICA for Realty) - Industry-specific data feeds (medical-aid claim codes, agricultural commodity prices, Lightstone property data) - Vertical-specific integrations (Healthbridge for Med, Property24 syndication for Realty) - Branded front door (ybamed.co.za, ybarealty.co.za, etc.)

Customers buy the vertical brand, never see “Flow.” Flow is the engine; Med / Edge / Terra / Realty are the products. Same engine, four paint jobs.

The unlock: the 8 agents are universal. New verticals become weeks of work (knowledge pack + branded front door), not months of rebuilding.

3. How does YBA Flow present itself?

v3 pick: Flow becomes a customer brand at one specific spot — the BYOK direct tier. Everywhere else, customers buy a vertical brand.

The v2 call (“Flow is internal-only”) was right for v2’s empire shape. v3 makes Flow a product — but only the BYOK direct buyer sees it.

4. Where do you start?

v3 pick: Concierge first. Sell, not build. The R6k Flow concierge client already signed = Flow concierge tier client #1.

Concrete sequence:

Concierge funds BYOK. R20k/mo × 10 concierge = R2.4m/year — that pays for the engineering work to make BYOK self-serve. Don’t sell more concierge than Captain can deliver (~15 client ceiling before he must hire help).

5. What technology runs the engine?

v3 pick: Hybrid stack with Flow Core as the only new code.

Five of seven pieces already on the VPS. Adds: Flow Core code, Twilio account, voice provider account. That’s it.

Where the 5 Specialists Agreed (v3)

Every specialist independently arrived at the same shape:

1. Three engines — back-office (ERPNext) + content (Postiz/n8n) + agent runtime (Flow Core). No frameworks like LangGraph or CrewAI.
2. Flow IS a customer-facing product — but verticals (Med, Edge, Terra, Realty) wear their own brands as the front door.
3. Per-task LLM routing — not per-agent, not per-tenant. Each task declares accuracy_critical / consistency_critical / cost_critical / balanced; the router picks.
4. Concierge launches first. Sell to 5-10 SMEs at R20k/mo while BYOK is built quietly in the background. Ship BYOK at month 7-9.
5. SA compliance is a 3-layer system — static prompt for hot rates (VAT, PAYE) + RAG over full law text (BCEA, LRA, SARS guides) + live data feed (SARS API). Annual February sprint with paid SAIPA + IR consultant review.

SA Compliance — the Plan

The hard rule: agents draft, humans submit. No agent ever auto-files a VAT return or POPIA-relevant document. SARS e-Filing credentials stay with the human owner. This collapses most legal liability.

Three layers:

Vertical add-on packs: - flow-compliance-core — every tenant (BCEA, LRA, SARS, POPIA) - flow-compliance-medical — YBA Med tenants (HPCSA, BHF, NHA) - flow-compliance-realty — YBA Realty tenants (PPRA, EAAB, FICA-enhanced) - flow-compliance-agri — YBA Terra tenants - flow-compliance-legal — legal practices

Compliance budget (rand/month):

Add ~R800/month per active vertical pack. By full-empire (4 verticals): ~R7,000/month all-in. That’s a junior bookkeeper’s salary spread across every paying tenant.

Concierge vs BYOK — the Two Tiers

Critical: concierge needs ~R8k/month professional indemnity insurance from day one (R8m cover). Don’t sign concierge without it.

What This Looks Like in Practice (90 days)

Realistic capacity: ~18 hrs/week at night.

Weeks 1-2: Lawyer drafts MSA + DPA. Niki sets up Flow Core skeleton (multi-tenant Postgres schemas, n8n org-per-tenant, LiteLLM router stub). The R6k Flow concierge client = first concierge tenant in shadow mode (agents answer but don’t act).

Weeks 3-4: First 3 of the 8 agents go live for client #1 — Front Desk, Customer Care, Executive Assistant. Captain runs his own 2-3 brands through the same platform. Twilio + Cartesia voice provider live.

Weeks 5-8: Remaining 5 agents activate. 1-2 more concierge clients sign (R45k setup + R20k/mo each). Multi-tenant hardening — every cross-tenant boundary audited.

Weeks 9-13: 3-5 concierge clients live (R60-100k+ MRR). Captain has 5-7 of his own brands on the platform (Edge stage 1 progress). Healthbridge paperwork started in background. BYOK self-serve dashboard scoped.

What we DON’T do in 90 days: YBA Med vertical pack, Terra, Realty, BYOK launch, custom Frappe apps. All months 4+.

Watchpoints

1. Concierge delivery quality. Captain’s hours are the bottleneck. ~15 concierge clients = hard ceiling before he hires. Don’t oversell.
2. Multi-tenant correctness. A bug that lets one tenant see another’s data is catastrophic — POPIA breach + reputation destruction. Niki audits every cross-tenant boundary on every release.
3. The compliance feeds going stale. February budget speech changes are mandatory updates within 24 hours. Set the calendar reminder now.
4. Professional indemnity insurance signed before concierge client #1 onboards.
5. LLM cost runaway. A buggy agent in a loop can burn R5,000 in a night. Per-tenant monthly cap + per-task cost guards must be hard-enforced from day 1.
6. The “Flow concierge” name is now obsolete. Use “Flow concierge” internally; client never sees either name — they see “Edge” or “Med” or whichever vertical brand sold them.

What I’d Like You to Decide

Three things, when you’re ready:

1. Confirm v3 shape: three engines, Flow as platform, vertical brands as front doors, concierge first / BYOK at month 7-9. Yes / no / push back on a specific bit.
2. Pricing: R45k setup + R18.5k/mo base for concierge — comfortable, or do you want different numbers? BYOK at R3.5k/mo — same question.
3. Professional indemnity insurance. R8m cover, ~R8k/month premium. Authorise Niki to get 3 quotes (Hollard / Santam / specialist broker) for review.

YBA Med — Layer 2 Specialist Agents (the first vertical fully designed)

Five research specialists designed the full vertical agent fleet for a SA medical practice on 2026-05-02. 42 specialist agents in 5 teams, sitting on top of the 8 Layer 1 universal agents — total 50 agents per Med tenant. Full per-agent design (skills, SOPs, hard NEVER rules, Layer 1 interactions) lives at [[yba-med-layer2-2026-05-02]].

The 5 Teams

Highlight agents (the moats per team)

• Team 1 — Clinical Scribe + Diagnosis Co-Pilot + Prescription Drafter — doctor types nothing for an entire consultation. NAPPI / ICD-10 / drug interactions ALWAYS from verified lookups, never LLM-generated.
• Team 2 — Rejection Auto-Fix Agent — classifies rejections into ~30 categories, auto-fixes admin issues, re-submits. Trust ratchets up per claim type (200 successful auto-submits → unlocked). Recovers R20-40k/month previously written off.
• Team 3 — WhatsApp Portal + Triage Agent — WhatsApp Business API (360dialog), multi-language, opt-out enforcement. Triage detects “chest pain” / “bleeding” / etc., kills auto-replies, alerts human in 30 seconds. Weekly synthetic test messages.
• Team 4 — Records Custodian — 6-year HPCSA retention auto-enforced, encrypted at rest, audit log is append-only (even agents can’t edit), POPIA breach notification drafted in 4 hours.
• Team 5 — Locum Coordinator + Stock & Cold-Chain Sentinel + Building Officer — 90-min locum find/vet/contract/brief; vaccine fridge sensor (15-min excursion alert); EskomSePush integration so load-shedding never wipes the fridge.

Coverage map — every aspect of running a SA medical practice

Hard safety rails (universal across all 5 Med teams)

1. No autonomous clinical action. Every diagnosis, prescription, referral is doctor-signed before action.
2. NAPPI / ICD-10 / drug-interactions from verified lookups only. Never LLM-generated.
3. Red-flag triage is uninterruptible. No code path, prompt, or instruction can disable it.
4. Patient never sees a result before the doctor has reviewed it.
5. POPIA special-category rigour. Tighter than ordinary PII. Per-record audit trail.
6. HPCSA records retention auto-enforced. 6 yrs adult, until 21 for minors.
7. Audit log is append-only. Even agents can’t edit it.
8. Multi-tenant isolation. Practice A’s brain never leaks to Practice B.
9. No agent ever auto-submits to a regulator. Doctor signs.
10. Practice owner has a single kill-switch. Tested monthly.

What a Med tenant subscription pays for itself with

For a 2-doctor GP practice (~1,500 claims/month, R600k monthly billings):

Concierge subscription should price at R25-35k/month for a multi-doctor practice — multiple times the LLM/voice cost (~R3-6k) and pays back inside the first month.

The Path to Market — see Strategy page

The full path-to-market plan — Edge as the empire’s discovery engine, the 7 measurable gates, kill triggers, the YBA Meta-Brain, top 3 risks, and the 5 de-risk experiments — moved to its own document on 2026-05-02 per the documentation audit. Read empire-strategy.html for the full picture.

The 30-second summary: Edge is built first as Captain’s own portfolio platform (stage 1) → sold as Concierge to clients (stage 2) → packaged as BYOK SaaS (stage 3). Customer interactions become signal that informs Med, Terra, Realty designs. Each new vertical needs its own real practitioner-client to dogfood with. 7 measurable gates govern progression — no calendar dates, only triggers.

┌──────────────────────────────────────────────────────────────────┐
│ STAGE 1 — Captain dogfoods Edge on his own 10 portfolio brands   │
│  Spec is written by living it. He IS the first customer.         │
└──────────────────────────────┬───────────────────────────────────┘
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│ STAGE 2 — Same tools sold as Concierge to agency-sector clients  │
│  R45k setup + R18.5k/mo. 5-15 client ceiling. Cashflow + signal. │
│  Every client interaction = customer-discovery research.         │
└────────┬─────────────────────────────────────────────┬───────────┘
         │                                             │
         ▼ (Edge stage 3 unlock)                       ▼ (Empire signal)
┌─────────────────────────┐                 ┌─────────────────────────┐
│ STAGE 3 — Edge BYOK     │                 │ Patterns extracted into │
│ self-serve SaaS         │                 │ the YBA Meta-Brain      │
│ R3.5k/mo, public.       │                 │ (anonymised, POPIA-safe)│
└─────────────────────────┘                 └────────┬────────────────┘
                                                     │
                                                     ▼
                                  ┌──────────────────────────────────┐
                                  │ Med, Terra, Realty designs are   │
                                  │ grounded in real Edge customer   │
                                  │ patterns, not specialist guesses │
                                  └──────────────────────────────────┘

yba-meta-brain/
├── CLAUDE.md          # POPIA-strict variant of Richards Brain schema
├── index.md
├── log.md
├── raw/               # anonymised intake (sanitised excerpts only)
└── wiki/
    ├── patterns/      # NEW — one page per cross-tenant pattern
    │   ├── universal/   # patterns that hold across ALL verticals (Layer 1 candidates)
    │   ├── edge/
    │   ├── med/
    │   ├── terra/
    │   └── realty/
    ├── decisions/     # NEW — every empire design call, links the patterns that drove it
    ├── verticals/     # one page per vertical — rolled-up state
    ├── concepts/      # cross-cutting concepts (e.g. "WhatsApp 24hr window")
    ├── analyses/      # "Layer 1 v2 readiness," etc.
    └── meta/

Pending Vision Documents

Captain will provide visions for YBA Terra (and possibly Realty) next. v4 of the architecture will integrate those — and each gets its own Layer 2 specialist sweep just like Med got today. Med Layer 2 is the template; Terra/Realty get their own 5 teams sized to their domain.

— Synthesised by Niki on 2026-05-02 from 5 parallel specialist sweeps with Captain’s Flow vision baked in.