Architecture

Floor Walker runs in two places: inside your Twilio account (the Flex plugin, serverless functions and Flex configuration) and on one Linux server you operate (the backend, as Docker containers). Nothing runs on AWS or another cloud service besides Twilio and the AI providers.

Components

Component	Where it runs	Source	Role
Flex plugin	Twilio Flex (agent's browser)	plugin-tokin-flex/	Agent workspace, recording controls, CRM, wallboard editor, supervisor console, campaigns, reports inside Flex
Serverless functions	Twilio Functions	serverless-functions/	Twilio-specific work (Sync, Conversations, Content API, call recording and Event Streams webhooks) and a few proxies to tokin-api
Flex configuration	Twilio Flex ui_attributes	flex-config/	Which features are on and their settings, including the tokin-api URL
tokin-api	Backend server	tokin-api/	CRM, recordings, transcription, AI insights, calendars, wallboard, supervisor console, historical reports, demo mode
Dialer engine	Backend server (optional)	flex-dialer/engine/	Outbound campaigns, pacing, callbacks, messaging campaigns; also serves the dialer console at /dialer/
Postgres 16	Backend server	deploy/postgres/	Two databases: tokin (tokin-api) and dialer (dialer engine)
MinIO	Backend server	deploy/minio/	S3-compatible bucket for screen and call recordings and exports
Caddy	Backend server	deploy/Caddyfile	TLS (Let's Encrypt) and routing for every public path
Metabase	Backend server (optional)	docker-compose.yml, profile bi	Ad-hoc BI over the reporting schema, served at /bi/
Screen recorder	Agent's computer	flex-agent-screen-recorder/	Electron app that records the screen as HLS segments and uploads them to MinIO
Wallboard kiosk	TV browser	wallboard-kiosk/	TV page, served by tokin-api at /wallboard/
Reports and dialer consoles	Browser, outside Flex	dialer-console/	Reports console at /reports/ (tokin-api) and dialer console at /dialer/ (dialer engine)

How they talk

• Flex plugin to tokin-api. Most calls go straight to tokin-api with the agent's Flex token in the Authorization header. tokin-api validates the token with Twilio IAM and reads the agent's roles from it. The plugin finds the API at custom_data.common.tokin_api_url or custom_data.features.screen_recording.api_url in the Flex configuration.
• Flex plugin to serverless functions. Used for Twilio-only operations and a few proxies. Functions validate the Flex token, and call tokin-api with the service key (X-Api-Key).
• Plugin to the screen recorder. The plugin sends start, stop and task-switch commands to the desktop app over a local WebSocket, together with the API URL and the agent's token. The recorder then talks to tokin-api itself and uploads segments to MinIO with presigned URLs.
• Twilio to the backend. Event Streams posts TaskRouter and Studio events to a sink URL on tokin-api (wallboard, reports) and to the dialer engine's own sink. Voice webhooks for dialer calls go to the engine and are verified with the Twilio signature.
• tokin-api and the dialer engine. The engine reads business calendars from tokin-api; tokin-api reads the engine's dashboard for the wallboard's dialer tiles. Both use the shared service key on the internal network.
• Background work. tokin-api keeps a job queue in Postgres (transcription, insights, exports, report emails) and polls for task reminders, which it turns into TaskRouter tasks on the tokin channel.

One host, one certificate

Caddy serves everything on one hostname (API_SITE, for example api.example.com):

Path	Goes to
/<S3_BUCKET>/*	MinIO (presigned recording URLs)
/api/v1/*, /webhooks/twilio/*, /media/ringback.wav, /dialer/*	Dialer engine
/bi/*	Metabase (profile bi)
everything else	tokin-api, including /wallboard/ and /reports/

A second hostname for the dialer (DIALER_SITE) is optional. See Backend deployment.

In this section

• Backend deployment: the server, DNS, TLS and the first deploy.
• Operations: logs, backups, upgrades and disk.
• Configuration reference: every backend environment variable.
• Flex deployment: the plugin, serverless functions and Flex configuration.
• CI/CD: the GitHub Actions workflows and environments.
• Authentication and security: tokens, keys, roles and secrets.
• Demo mode: a simulated contact centre for demonstrations.
• Website: hosting the docs and the landing page.