hoanganh8389/bizcity-twin-ai

Bizcity Twin AI – A WordPress‑based AI “Twin” platform

One brain for every channel – the project turns a WordPress site into a unified, AI‑enabled knowledge hub for a business. It ingests data from many communication channels (Facebook, Zalo, email, web‑chat, Telegram, TikTok, etc.), builds a knowledge‑graph (KG) hub, and exposes the data to large‑language‑model assistants (Claude, ChatGPT, …) through a Managed‑Control‑Plane (MCP). The core provides the shared “brain” (identity, KG, memory, inference, logging, automation, permissions). Functionality is extended via plugins that add domain‑specific actions, new channel adapters, or UI views without touching the core.

---

What it does

Area	What the core supplies	How plugins extend it
Channel gateway	Normalises inbound/outbound messages, ties them to a tenant‑wide identity, and routes them to the CRM or the reasoning engine.	channel plugins add new sources (e.g., a TikTok webhook) or custom routing rules.
Twin CRM	Unified inbox, contacts, conversations, and campaign reporting.	act plugins can create orders, update records, or push notifications.
TwinBrain / MPR	Multi‑step reasoning, tool selection and orchestration for each turn.	act plugins expose typed tools (e.g., “create‑invoice”) that the brain can call.
KG Hub	Stores entities, passages, provenance, and provides graph‑search with citations.	source plugins feed new documents (product catalogs, legal docs, POS logs) into the KG.
Automation & Scheduler	User‑configured workflows (triggers, conditions, actions) with approval gates.	act/view plugins supply the concrete actions used in those workflows.
MCP	Policy‑driven API that lets external LLMs (Claude, ChatGPT) query the KG or invoke tools under strict access control.	Plugins can expose additional endpoints that respect the same policy layer.
TwinShell / Twin GPT	Built‑in chat UI (/gpt/) and admin console for internal users.	view plugins add dashboards, reports, or custom admin pages.

---

Key concepts (the “three‑axis” architecture)

1. Horizontal axis – Channel gateway – gathers raw messages from every external channel and normalises them into a common data package.
2. Vertical axis – Specialty plugins – each plugin contributes a domain (sales, finance, legal, content, …) without duplicating core services.
3. Knowledge‑graph layer – a single KG hub stores all facts with provenance; the brain queries it for evidence‑based answers.

---

Typical use‑cases

Use‑case	Flow (simplified)
Multichannel sales assistant	Customer message → Channel gateway → Twin CRM inbox → KG (product + customer context) → TwinBrain selects a reply tool → (optional) human approval → response sent back through the same channel.
Customer‑insight dashboard	Periodic ETL from CRM/POS → source plugin pushes passages to KG → analytics tool reads KG with citations → view plugin renders a dashboard showing confidence‑scored insights.
Internal operations bot (Telegram/Zalo)	Admin command → Channel gateway (zone 2) → Identity check → TwinBrain runs a workflow (e.g., generate report, trigger CI) → result posted back to the bot.
Content creation for TikTok	Trend research → KG‑based retrieval → video‑generation tool → approval step → TikTok publishing adapter (new channel plugin).

---

Technology stack

Component	Technology
Platform	WordPress ≥ 6.0 (PHP 7.4+) – the core is a regular WP plugin, so any WP host can run it.
Core language	PHP (object‑oriented, Composer for dependencies).
Knowledge graph	Stored in the WP database; passages are indexed for fast vector/graph search (the platform supplies the index and retrieval API).
LLM integration	MCP abstracts providers; built‑in client classes talk to Claude, OpenAI ChatGPT, etc., via HTTP.
CLI / scaffolding	WP‑CLI commands (wp bizcity make:*, wp bizcity health, wp bizcity plugin lint).
Logging & audit	JSONL files with a central bizcity_log_index; logs contain provenance but never raw secrets or PII.
Automation	DAG‑based workflow engine built into the core; plugins supply blocks that declare inputs, outputs, idempotency, and retry policy.

---

Project health & maturity

• Version: 1.3.7 (as shown by the badge).
• License: GPL‑2.0‑or‑later – fully open source.
• Documentation: Detailed developer guide (docs/vibe/README.md), contribution guide, and a public development checklist.
• Demo instances: Live demo sites for the admin console, GPT UI, and CRM are provided (libedemo.bizcity.vn).
• Testing: Built‑in linting (wp bizcity plugin lint), diagnostics, and a “probe” command that runs a plugin in a narrow sandbox to verify contracts.
• Roadmap: Ongoing work to move more specialty capabilities out of the core, improve selective KG ingestion, and finish the TikTok customer‑messaging adapter.

---

Getting started (quick‑start steps)

# 1. Install on a WordPress site (must be 6.0+ and PHP 7.4+)
cd wp-content/plugins
git clone https://github.com/hoanganh8389/bizcity-twin-ai.git
cd bizcity-twin-ai
composer install   # pulls PHP deps
wp plugin activate bizcity-twin-ai

# 2. Add your LLM/API key in the WP admin panel (BizCity AI → LLM Settings).

# 3. Verify the installation
wp bizcity health --format=json   # health check
wp bizcity sdk-check --format=json # core‑SDK compatibility

# 4. Scaffold a new plugin (example: customer‑insight)
wp bizcity make:plugin customer-insight --name="Customer Insight"
wp bizcity make:source crm --plugin=customer-insight
wp bizcity make:tool analyze-customer --plugin=customer-insight
wp bizcity make:event insight-created --plugin=customer-insight
wp bizcity make:diagnostic runtime --plugin=customer-insight

# 5. Fill the generated TODOs with your business logic, then run lint & probe
wp bizcity plugin lint customer-insight --json --strict
wp bizcity probe --id=plugins.customer_insight.runtime --format=json

The scaffolding creates a manifest, typed contracts, diagnostics, and an uninstall guard, so developers only need to implement the domain‑specific code.

---

Who might use it?

• SMEs or mid‑size enterprises that already run WordPress and want a single, auditable AI “brain” for sales, support, and internal ops.
• Developers building custom AI‑enhanced CRMs – they can focus on domain plugins while re‑using the core’s KG, reasoning, and security layers.
• AI‑ops teams that need strict provenance (graph citations, JSONL audit) when exposing internal data to external LLMs.

---

Bottom line

Bizcity Twin AI is a genuine, open‑source platform that combines omni‑channel data ingestion, knowledge‑graph‑backed retrieval, LLM‑driven reasoning, and plug‑in‑first extensibility on top of WordPress. It is positioned as a “digital twin” for a business, letting developers create AI‑powered CRM, sales, support, and automation tools while keeping data governance and auditability under control.