Technical overview

How HarbourMaster AI turns marina enquiries into visible staff workflows. Built for traceable answers, rate-card pricing, and human review.

HarbourMaster AI is a Cloudflare-native front-desk app for voice, SMS, email, and web enquiries. It combines conversational intake with approved marina knowledge, deterministic pricing, tenant-scoped records, and a dashboard staff can inspect.

Omnichannel intake
Voice, SMS, email, web

Every enquiry can enter one shared workflow.

Controlled commitments
Rate-card pricing

Quotes come from deterministic tools, not guesswork.

Staff evidence
Audit trail

Transcripts, tool calls, and outcomes remain reviewable.

Platform Architecture

Every inbound request enters through Hono on Cloudflare Pages, then flows through deterministic tools and D1-backed audit records. Roadmap services are marked directly in the diagram.

Ingress Channels
Twilio Voice
Voice calls
CF Email / Resend
Inbound email
Twilio SMS
Text messages
Web Chat
Browser widget
Webhooks
Worker Layer
Channel Router
Hono middleware
KV Guardrails
Caps / Idempotency
Agent Memory
Retrieve D1 chunks
Agent Router
Hono + Workers AI
Function Calling
AI + Tool Chain
Kimi K2.6
LLM Inference
Memory Context
Policies / FAQs
Whisper (roadmap)
Raw audio STT
ElevenLabs
TTS
check_availability
Tool
quote_price
Tool
book_slip
Tool
Read / Write
Storage Layer
D1
Relational (SQLite)
D1 Memory
Docs & chunks
KV
Config & rate cards
R2 (roadmap)
Contracts & recordings
Vectorize (roadmap)
Semantic RAG
Queues (roadmap)
Async tasks

Current product path

Inbound enquiries are captured, normalized, checked against approved tools, and saved for staff review.

Live
Interest Registration D1 write

Prospective marina teams can leave details for follow-up.

Workers AI Agent

Kimi K2.6 powers the agent reasoning and tool-calling path.

D1 Database DB binding

Marinas, slips, rate cards, inquiries, bookings, events, leads, and Agent Memory.

Workers KV KV binding

Request caps, payload guardrails, idempotency, and edge-ready config.

Cloudflare Email Email Worker

Companion Worker supports inbound email and staff-visible follow-up.

Twilio Voice + SMS Webhook

Webhook paths support the phone and text message channels.

Roadmap services

Important, but not claimed as live until bindings and code prove it.

Roadmap
Durable Objects Planned

Stateful sessions per marina and conversation for richer multi-turn calls.

R2 Storage Planned

Contracts, call recordings, transcripts, and attachments.

Vectorize Planned

Semantic retrieval upgrade for larger policy and historical corpora.

AI Gateway / Queues Planned

AI observability, caching, provider fallback, async sync, and retries.

AI Stack

The agent combines Kimi reasoning, staff-approved D1 memory, speech input, and voice output without letting retrieved text override deterministic tools.

Kimi K2.6

@cf/moonshotai/kimi-k2.6

Primary reasoning model. MoE architecture activates only relevant expert sub-networks per token, keeping inference cost low at high volume.

Architecture MoE: 1T total, ~32B active
Context 128K tokens
Function calling Native (not prompt-injected)
Temperature 0.4 (bounded creativity for customer service)
Tool chain 5 tools in booking sequence
Fallback Graceful apology response if Workers AI fails

Agent Memory

D1 + toMarkdown

Live retrieval layer for marina policies, procedures, amenities, and FAQs. Staff upload PDFs or paste text, then enabled chunks are injected into every channel.

Upload types PDF, TXT, Markdown, CSV
Conversion Workers AI Markdown Conversion
Retrieval Keyword-ranked D1 chunks
Safety Cannot override pricing or availability

Whisper Large v3 Turbo

@cf/openai/whisper-large-v3-turbo

Roadmap speech-to-text layer. The current voice path accepts Twilio Gather speech transcripts and routes them into the same Kimi K2.6 loop.

Latency < 300ms per chunk
Languages 99+ (English primary)
Current input Twilio SpeechResult / call transcript
Features Timestamps, confidence scores
Runs on Cloudflare Workers AI GPU

ElevenLabs TTS

Primary + Workers AI fallback

Text-to-speech for voice responses. ElevenLabs for production-quality voices; Workers AI MeloTTS as a zero-latency fallback.

Primary ElevenLabs (configurable voice)
Fallback Workers AI MeloTTS
Current output MP3 via /api/tts/speak for Twilio
Voice IDs Per-marina configurable
Live knowledge retrieval

Agent Memory: upload docs, answer from policy

Agent Memory is the live RAG path for marina operations. Original files are not retained; the app stores extracted Markdown, document metadata, and retrieval chunks in D1, then injects up to four relevant enabled snippets into each Kimi K2.6 request.

1
Upload or paste

Staff add PDF, TXT, Markdown, CSV, or direct policy text from /agent-memory.

2
Convert to Markdown

Workers AI toMarkdown extracts readable text from PDFs and documents.

3
Chunk in D1

Markdown is normalized, capped, chunked, keyword-indexed, and scoped by marina_id.

4
Retrieve on every channel

Web, email, SMS, and voice retrieve policy snippets before the agent replies.

Memory boundary

Memory can answer policies, procedures, amenities, and operational FAQs. Pricing still flows through quote_price, and slip availability still flows through check_availability.

Memory-Aware 5-Tool Booking Chain

Before Kimi K2.6 answers, the Worker retrieves relevant enabled memory chunks. The model still calls these tools via native function-calling for operational state and customer commitments.

1
check_availability

Queries D1 for matching slips with date-overlap exclusion and vessel dimension filtering.

2
quote_price

Deterministic pricing engine: base × season × DOW × occupancy × events. Never LLM-generated.

3
draft_contract

Demo placeholder today. R2 PDF storage and DocuSign envelopes are roadmap.

4
take_payment

Payment-pending response today. Stripe Checkout is roadmap.

5
book_slip

Writes confirmed booking to D1 and keeps external PMS sync as roadmap.

Escape hatch: escalate_to_human

A 6th tool the agent can call at any point to route the conversation to a human. Triggered automatically when confidence drops below threshold, dollar cap is exceeded, or max turns is reached.

Data Layer: D1 Schema

9 tables, all scoped by marina_id for strict multi-tenant isolation.

marinas

Tenant root table. One row per marina property.

id TEXT PK
name TEXT
timezone TEXT
address TEXT
lat REAL / lng REAL
total_slips INTEGER
dm_api_endpoint TEXT
slips

Physical slip inventory with dimensions and amenities.

id TEXT PK
marina_id TEXT FK
slip_no TEXT
dock_section TEXT
length_ft / beam_ft / depth_ft
has_power_30a / has_power_50a
has_water / has_wifi
status ENUM
rate_cards

Pricing configuration with JSON curve definitions.

id TEXT PK
marina_id TEXT FK
base_rate_json
season_curve_json
dow_curve_json
event_premiums_json
occupancy_curve_json
cancellation_policy_json
agent_configs

Per-marina AI agent personality and guardrails.

marina_id TEXT FK
system_prompt TEXT
greeting_message TEXT
voice_id TEXT
dollar_cap_per_booking INT
confidence_threshold REAL
max_turns_before_escalation INT
escalation_rules_json
agent_memory_documents

Uploaded or pasted staff knowledge converted to Markdown.

id TEXT PK
marina_id TEXT FK
title TEXT
source_type ENUM
filename / mime_type / byte_size
extracted_markdown TEXT
status ENUM
chunk_count INT
agent_memory_chunks

Retrieval chunks automatically injected into Kimi context.

id TEXT PK
document_id TEXT FK
marina_id TEXT FK
chunk_index INT
heading TEXT
content TEXT
search_text TEXT
token_estimate INT
inquiries

Every inbound interaction across all channels.

id TEXT PK
marina_id TEXT FK
channel ENUM
caller_info TEXT
transcript_text TEXT
confidence_score REAL
status ENUM
assigned_to TEXT
bookings

Confirmed reservations with PMS sync status.

id TEXT PK
marina_id TEXT FK
slip_id TEXT FK
inquiry_id TEXT FK
guest_name / guest_email / vessel_name
start_ts / end_ts DATETIME
price_cents INT
dm_synced BOOLEAN
agent_attributed BOOLEAN
events

Full audit trail for every action the agent takes.

id INTEGER PK AUTOINCREMENT
marina_id TEXT FK
inquiry_id TEXT FK
event_type TEXT
actor TEXT
detail_json TEXT
ts DATETIME

Multi-Tenancy Rule

Every live D1 query and booking/inquiry/event path is scoped by marina_id. Roadmap storage surfaces like R2, Vectorize, Queues, and Durable Objects should keep the same tenant prefix rule when added.

Deterministic Pricing Engine

The LLM never generates prices. Every dollar amount comes from this formula, executed deterministically on the Worker.

// Final price calculation
total = base_rate × vessel_length × nights
        × season_multiplier
        × avg(dow_multipliers)
        × occupancy_multiplier
        × event_premium
        + add_ons
Season Curve
Peak (Dec-Mar): 1.55×
Shoulder (Apr-May, Oct-Nov): 1.20×
Off-Peak (Jun-Sep): 0.80×
Day of Week
Mon-Wed: 1.00×
Thu: 1.05× / Fri: 1.15×
Sat: 1.25× / Sun: 1.10×
Occupancy
> 90%: 1.35×
> 80%: 1.15× / > 70%: 1.00×
< 60%: 0.85× (fill incentive)
Events
FLIBS: 2.00× (Oct)
Winterfest Parade: 1.50× (Dec)
July 4th: 1.40×
Base Rates
Nightly: $2.75/ft
Weekly: $16.50/ft
Monthly: $45.00/ft
Add-Ons
30A power: $15/night
50A power: $25/night
WiFi: $8 / Pump-out: $50

Why deterministic?

LLMs are great at conversation but unreliable at arithmetic. A hallucinated price creates legal liability and erodes guest trust. By running pricing as a pure function on the Worker, the agent can confidently quote exact rates that match your published rate card.

Guardrails & Security

Production AI needs more than vibes. These are hard constraints, not suggestions.

Agent Guardrails

Dollar cap Max booking value before auto-escalation. Default: $15,000.
Confidence threshold Below this score, the agent escalates. Default: 0.75.
Max turns Turn limit before forcing human handoff. Default: 20.
Deterministic pricing Prices always from rate card function, never LLM-generated.
Availability check D1 query checks date overlaps before any reservation write.
Agent Memory boundary Retrieved policy text can inform answers, but cannot set prices, discounts, availability, or payment status.
Out-of-policy detection Liveaboards, groups, and insurance requests are routed to staff.

Infrastructure Security

Google OAuth SSO Google OAuth 2.0 with JWT session cookies on all dashboard routes.
API tokens as secrets Twilio, ElevenLabs, email, and future vendor keys stored as Cloudflare Secrets.
Tenant isolation All data paths include marina_id. No shared-namespace leaks.
KV request guardrails Lead capture and channel routes have payload caps, request caps, and idempotency where KV is bound.
Audit trail Every agent action logged with actor, timestamp, and detail JSON.
Webhook verification Provider signatures can be checked before channel requests are trusted.
Channel rate controls Phone, SMS, email, web, and interest forms have payload and request caps.
Roadmap AI Gateway AI request logs, caching, rate controls, and provider fallback come after live-channel reliability.

Voice Pipeline

The voice path is designed around Twilio webhooks, speech transcripts, tool-backed answers, and staff-visible records.

TWI
Twilio

Guest calls or texts the marina number.

Channel
WOR
Worker

Hono validates the request and applies guardrails.

Runtime
KIM
Kimi K2.6

Transcript → reasoning → tool calls → customer-safe response.

Agent
D1
D1

Inquiry metadata, transcript, events, and outcomes are saved.

Record
VOI
Voice reply

TwiML returns the next prompt or spoken answer.

Response
STA
Staff review

The dashboard shows the trace and handoff state.

Dashboard
Design principle: callers get help, and staff can see exactly what happened. Raw audio streaming remains a later production upgrade.

Full Stack Reference

Everything that powers HarbourMaster AI, in one table.

Layer Technology Purpose
Framework Hono 4 Lightweight, fast web framework for Workers
Build Vite + @hono/vite-build SSR bundle for Cloudflare Pages
Runtime Cloudflare Workers V8 isolates at 300+ global PoPs
LLM Kimi K2.6 (MoE) Reasoning + native function-calling
STT Twilio SpeechResult live; Whisper roadmap Transcript input now, raw audio STT later
TTS ElevenLabs / MeloTTS Natural voice synthesis
Database Cloudflare D1 (SQLite) Relational data, multi-tenant
Agent Memory D1 chunks + Workers AI Markdown Conversion PDF/text policy retrieval
KV Store Cloudflare Workers KV Request caps, payload caps, idempotency, and edge config
Object Storage Cloudflare R2 (roadmap) Contracts, recordings, attachments
Vector DB Cloudflare Vectorize (roadmap) Semantic RAG upgrade for larger corpora
Sessions Durable Objects (roadmap) Stateful multi-turn agent sessions
Gateway Cloudflare AI Gateway (roadmap) LLM caching, rate limits, fallback
Queues Cloudflare Queues (roadmap) Async PMS sync, notifications
Auth Google OAuth 2.0 + JWT SSO for dashboard with session cookies
Voice Twilio webhooks live; Media Streams roadmap Telephony ingress/egress
Email Cloudflare Email Service + Resend fallback Native inbound/outbound email path
SMS Twilio Messaging Text message channel
Payments Stripe Checkout (roadmap) Guest payment collection
Contracts DocuSign (roadmap) E-signature for rental agreements
PMS DockMaster API (roadmap) Property management sync
Alerts Slack API (roadmap) Staff notifications & escalations
Frontend Tailwind CSS + Space Grotesk Utility-first styling, Abyssal Intelligence theme
TypeScript ES2022 target Type-safe Workers code

Interested in HarbourMaster AI?

Register your interest and I will follow up directly.

Register interest Home Sign in