Web App · AI
AlkebulanWeb
Status
In Development
Stack
[ THE THESIS ]
African businesses do not need another website builder that treats payments as a plugin.
AlkebulanWeb is an AI website builder designed around the way African businesses actually sell: mobile-first, local-payment-first, and fast to launch. The system breaks generation into isolated agents so planning, code, review, and payment wiring can fail independently instead of collapsing into one fragile AI black box.
MVP · three services running locally · Africa-first by design
SECTION 01 — PRODUCT THESIS
Coordination beats raw horsepower — payments win the continent
v0 and Lovable are incredible for US/EU markets. They cannot take money from an African freelancer. AlkebulanWeb can.
Prompt intelligence lives in markdown
AGENTS.md + skills/*.md + prompts/*.md. A human can improve generation quality by editing text, not Python. Intelligence is diffable, reviewable, shippable.
Repair is surgical, not regenerative
The Repair agent receives the QA issues list as input — not the original prompt. Passing files are preserved byte-for-byte. Only the flagged deltas get rewritten.
Locked output contract
Every agent outputs React 18 functional components + TS + Tailwind v3 + shadcn patterns. No HTML-only fallback. No CSS modules. No class components. The contract is enforced by the QA Reviewer.
Africa-first defaults
Mobile-first breakpoint. 44×44 touch targets. High-contrast for midday sun. Low-bandwidth-safe hero. Mobile-money checkout patterns. Hard-coded into every skill file.
SECTION 02 — THREE-SERVICE ARCHITECTURE
Each service does one thing well and talks over JSON
Landing
R3F 3D hero
Dashboard
projects + quota
Builder
split-pane · Sandpack
Pricing
token tiers
Auth
Passport + JWT + jwks-rsa
Projects
storage driver · local JSON ↔ Supabase
Ledger
pawaPay webhooks · token quota
Endpoints
- ▹ POST /generate
- ▹ POST /edit
- ▹ GET /health
- ▹ GET /providers/status
Model router + provider memory
- ▹ per-agent routing
- ▹ 429 cooldown
- ▹ quota-aware key rotation
- ▹ silent fallback
↓ calls ↓
Groq LLM Cloud
llama-3.3-70b · openai/gpt-oss-20b · qwen3-32b · llama-3.1-8b
SECTION 03 — THE 7-AGENT GENERATION PIPELINE
Sequential + parallel · QA-gated · auto-repaired
Interpreter
Reads the user prompt. Extracts structured JSON brief — site type, tone, audience, sections, style signals.
llama-3.1-8b-instant · fast + cheap
Planner
Converts the brief into a detailed build plan JSON — section order, layout, content direction, style direction.
llama-3.3-70b-versatile · big model, deep plan
Generatorparallel
First-pass React / TS / Tailwind file tree from the plan.
llama-3.3-70b-versatile
UI Enhancerparallel
Improves hierarchy, spacing, typography, polish. Merges with Generator output.
qwen/qwen3-32b
QA Reviewer
Scores output against the output contract. Flags missing sections, malformed files, weak structure. Returns pass/fail + issues + numeric score.
QA < 80 → auto-repair · 80–89 → ship with warnings · 90+ → production-ready
Repaironly on QA fail
Surgical fix — takes the QA issues list as input, not the original prompt. Passing files are preserved. Only the flagged deltas get rewritten.
qwen/qwen3-32b
Editor/edit flow
Applies user edits to saved projects without breaking unrelated code. Unchanged files are preserved byte-for-byte.
qwen/qwen3-32b
SECTION 04 — PER-AGENT MODEL ROUTING
Small + fast for narrow jobs · big for deep thinking · always a backup
SECTION 05 — ENGINEERING HIGHLIGHTS
Three decisions that make this architecture win
ORCHESTRATION
Parallel Generator + UI Enhancer halves wall-clock
The heaviest stage fans out to two agents running concurrently. Their outputs merge before QA. Latency drops without sacrificing quality.
→ ~2s p50 generation target
RELIABILITY
Provider memory + silent fallback
429s put a provider in 60-second cooldown. The router falls through primary → backup across four Groq models. The end user never sees 'AI failed, try again'.
→ 0 visible pipeline failures
SWAPPABILITY
Storage driver pattern in the backend
local-project-store.ts writes JSON to disk for MVP. A Supabase driver swaps in for production with zero controller changes. Deployable before any database account exists.
→ Supabase is optional in dev
SECTION 06 — CODE PROOF
The quality gate in ~20 lines
Verbatim from pipeline.py — the heart of the generator.
ai-service/pipeline.py
python
# ai-service/pipeline.py — excerpt
# The quality gate is the core control-flow decision.
async def run_generate_pipeline(prompt: str) -> Result:
brief = await interpreter.run(prompt)
plan = await planner.run(brief)
# Parallel fan-out: halve wall-clock on the heaviest stage.
generator_task = asyncio.create_task(generator.run(plan))
enhancer_task = asyncio.create_task(ui_enhancer.run(plan))
base_files, enhanced_files = await asyncio.gather(
generator_task, enhancer_task
)
files = merge(base_files, enhanced_files)
qa = await qa_reviewer.run(files)
if qa.score < 80:
# Surgical repair — pass the issues, NOT the original prompt.
files = await repair.run(files, issues=qa.issues)
return Result(files=files, qa_score=qa.score)