You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Install all dependencies
npm ci
# Run worker locally
npm run worker:dev
# Run UI dev server
npm run ui:dev
# Run all tests
npm test# Typecheck everything
npm run typecheck
# Infrastructure (provision D1, KV, R2, Queues, Access, Rate Limits)cd infra && make init && make plan && make apply
# Inject Terraform outputs into wrangler.jsonc
make inject
# Deploy worker to Cloudflarecd ../packages/worker && npx wrangler deploy
CI/CD
GitHub Actions runs ci.yml on pushes and PRs to main. It typechecks all packages, runs tests, builds the UI, and checks Prettier only on changed ts, tsx, json, and md files so unrelated historical formatting drift does not block focused changes. Deployment jobs run only from main pushes.
infrastructure.yml is currently manual-only (workflow_dispatch); automatic push/PR triggers are disabled for now. A manual run can still validate Terraform without R2 backend credentials by running terraform init -backend=false; full backend terraform plan requires configured R2/Cloudflare secrets. Production apply is intentionally not triggered by the current manual workflow because the apply job is still gated to main push events.
Use .env.example as the environment variable inventory for GitHub Actions secrets, Worker secrets, UI env vars, and Terraform variables. Keep real values in GitHub/Netlify/Cloudflare secret stores, not in committed files.
Deployed Environment
Environment
Worker URL
Development (sandbox)
https://concierge-ai.pmutua.workers.dev
Admin Portal (UI)
The admin portal is a React SPA (packages/ui) for hotel owners to manage their AI concierge assistant and supervise autonomous agent workflows.
Pages
Page
Route
Description
Login
/login
Email-only login; matches to tenant, redirects to dashboard or onboarding
Onboarding
/onboarding
5-step wizard to create a new tenant
Dashboard
/dashboard
KPI cards with tooltips (customers, conversations, payments, response time) + SSE live indicator + actionable insights bar + setup checklist for new tenants
Agent Chat
/agent
Direct streaming chat with Concierge AI; inline tool-call visualization; workflow progress; approval cards
Workflows
/workflows
Scalable workflow list (150+ items): Load More pagination, search, 4 filter tabs, stats bar, compact rows with step progress bars, priority sorting
Tabbed: Business Info, Assistant config (tone, language, escalation sensitivity, max auto-payment), Branding, Notifications (with save)
Landing
/
Public marketing page with guest chat widget — visitors can book rooms without login via floating chat bubble
Hotel Demo
/demo
Public hotel booking showcase: room cards, amenities, embedded chat, CTA — demonstrates the guest booking experience end-to-end
Key UI Features
Agentic Chat — Owner chats directly with AI, sees tool calls (availability check, payment processing) rendered as inline cards
Workflow Visualization — 150+ active booking pipelines with Load More pagination, search, filters, compact collapsible rows with step progress bars
Human-in-the-Loop Approvals — AI escalates high-value decisions (payments > threshold, refunds, complaints) to scalable owner queue with risk badges, AI recommendations, and contextual tooltips
Live Activity Feed — Real-time SSE events from event-bridge showing bookings, payments, messages with connection status indicator (Live/Connecting/Offline)
Actionable Dashboard Insights — Contextual nudges when metrics need attention (low payment success rate, high escalations, low AI resolution) with direct links to fix
Contextual Tooltips — Every KPI card and metric explains what it means and when to act (via Radix tooltip on hover)
Guest Chat Widget — Floating chat bubble on landing page — guests book rooms without login, identify by phone number for M-Pesa
React Error Boundary — App-level error boundary in Shell catches crashes gracefully with reload option
VITE_API_URL=https://concierge-ai.pmutua.workers.dev # Or leave empty for local proxy
Codex Multi-Agent Workflow
This project uses OpenAI Codex with custom subagents for exploration, review, tests, documentation lookup, and Git/CI workflow support. Configuration lives in .codex/.
Read-only codebase exploration and context gathering
docs_researcher
.codex/agents/docs-researcher.toml
Up-to-date docs lookup for Hono, Cloudflare Workers, Vitest, React, and Tailwind
gitops
.codex/agents/gitops.toml
Safe Git workflow, commit, PR readiness, and CI/CD troubleshooting
How to Use (in Codex CLI or IDE)
# Review your current changes
Spawn the reviewer agent to review packages/worker/src/features/
# Add tests for a feature
Use the test_writer agent to add tests for the receipt-generator
# Understand code before changing it
Use the explorer agent to find how M-Pesa flows from webhook to database
# Verify library or platform docs
Use the docs_researcher agent to verify the correct D1 batch API for Workers
# Prepare Git workflow and PR handoff
Use the gitops agent to prepare a safe commit and PR description for the current changes
# Parallel multi-agent review (advanced)
Spawn one agent per concern: security (reviewer), tests (test_writer), architecture (explorer)
Automatic Quality Gates
Stop hook (.codex/hooks/stop_verify.py) — Reminds Codex to run typecheck + tests before finishing
No password required — email-only login matches tenant by admin_email.
Admin Panel (Next.js — separate deploy)
Variable
Value
NEXT_PUBLIC_API_URL
https://concierge-ai.pmutua.workers.dev/api
NEXT_PUBLIC_ADMIN_TOKEN
Set in Netlify env vars (use dev-token locally)
Admin panel uses token-based auth via Authorization: Bearer <token>. The token is set as a build-time env var.
End-to-End Test Steps
Connect via deep link — Tap the Savanna Hotel deep link in Telegram
Verify session — Send /status to confirm connected
Book a room — Send "I need a room for 2 nights"
Pay via M-Pesa — Confirm STK push flow
Web chat — Visit https://concierge-ai.pmutua.workers.dev/api/chat/savanna-hotel/info
API Verification
# Health checkInvoke-RestMethod-Uri "https://concierge-ai.pmutua.workers.dev/api/health"# Verify hotel tenantInvoke-RestMethod-Uri "https://concierge-ai.pmutua.workers.dev/api/chat/savanna-hotel/info"
---
## Roadmap: Prototype → Production (Next 30 Days)
| Week | Milestone | Deliverable |
|------|-----------|-------------|
| 1 | WhatsApp Business API | Meta-verified business number, webhook integration, message templates |
| 2 | Pilot deployment | 3 hotels in Nairobi (Westlands, CBD, Karen) on production Cloudflare |
| 3 | Payment reconciliation | Real-time M-Pesa settlement dashboard, daily KES reports |
| 4 | Multi-language expansion | Sheng + Kikuyu intent detection, language auto-detect |
### Beyond 30 Days
- **Horizontal scaling:** Queue-based booking engine for 100+ concurrent hotels
- **Revenue model:** KES 2,000/month per hotel (freemium tier: 50 bookings/month free)
- **Open-source Codex config:** Fork-friendly `.codex/` setup for clinics, restaurants, salons
- **Kenya Tourism Authority integration:** Auto-report occupancy rates
---
## License
Proprietary — All rights reserved.
About
AI-powered hotel concierge for East African SMEs, it automates room bookings and guest queries via WhatsApp(wip), Telegram, and Web(wip), featuring integrated M-Pesa payment processing.