Architecture Overview

Loquent is a fullstack Rust application built with Dioxus 0.7 (SSR + WASM) and Axum as the HTTP server. It compiles two targets from a single codebase: a native server binary and a WASM client bundle.

Boot Sequence

main.rs
  → Load .env (dotenv)
  → Start cron scheduler (AsyncCron, Eastern timezone)
  → Register background jobs (report + todo jobs)
  → Build Dioxus router (serves pages + server functions + WASM)
  → Append custom Axum routes (Twilio WebSocket, webhooks, recordings)
  → Bind 0.0.0.0:8080, start Axum with graceful shutdown (SIGTERM/Ctrl-C)

In dev mode, dx serve manages the server lifecycle with hot reload. In production, the app binds directly via TcpListener.

Request Routing

Loquent handles three types of requests through a single Axum router:

1. Page Routes (Dioxus SSR + WASM)

All UI pages are defined in routes.rs using Dioxus routing. Two layout wrappers:

• PrivateLayout — outer wrapper, handles auth gating
• AppLayout — inner wrapper, provides the navigation shell

Path	View
/login, /signup	Public auth views
/	Dashboard
/agents, /agents/create, /agents/:id	Agent management
/calls, /calls/:id	Call history and details
/phones, /phones/buy, /phones/:id	Phone number management
/knowledge, /knowledge/create, /knowledge/:id	Knowledge bases
/analyzers, /analyzers/create, /analyzers/:id	Analyzer config
/contacts, /contacts/create, /contacts/:id	Contact management
/todo-types, /todo-types/create, /todo-types/:id	To-do type config
/todos	To-do list

2. API Routes (Dioxus Server Functions)

Server functions are defined with #[get], #[post], #[put], #[delete] macros inside each module’s api/ directory. Dioxus auto-registers them on the router. Examples:

• GET /api/agents → agent::get_agents_api
• POST /api/agents → agent::create_agent_api
• GET /api/calls/:id → call::get_call_details_api

3. Custom Axum Routes

Four routes are appended manually to the Dioxus router for Twilio integration and file serving:

Path	Method	Handler	Purpose
/twilio/stream	GET (WSS)	twilio::twilio_stream	Real-time audio WebSocket
/twilio/voice	POST	twilio::twilio_voice	Incoming call webhook (returns TwiML)
/twilio/recording	POST	twilio::twilio_recording	Recording status webhook
/recordings/:call_sid	GET	call::serve_recording	Serve MP3 recording files

Layer Architecture

ui  →  shared  →  bases  →  mods

Dependencies flow strictly left to right. No layer imports from a layer to its left.

Layer	Path	Purpose	Compiles To
ui	src/ui/	UI primitives (Button, Card, Input, Select, Spinner, etc.)	Both
shared	src/shared/	Cross-cutting types, layouts, context, constants	Both
bases	src/bases/	Infrastructure (DB, auth, config, email, error, jobs)	Mostly server
mods	src/mods/	Feature modules — each a vertical slice	Both

Server-only code is gated with #[cfg(not(target_family = "wasm"))] throughout bases and mods.

Dual-Target Compilation

The codebase compiles to two targets simultaneously:

Target	What	Contains
Native (server)	Axum HTTP server	DB queries, auth, Twilio WebSocket, AI sessions, file I/O
WASM (client)	Browser bundle	UI components, client-side routing, server function stubs

cargo check only verifies the native target. Use dx build for a full check across both.

Background Jobs

Two job types are registered at startup via app::app_jobs():

• Report jobs (mods::report) — scheduled email reports
• Todo jobs (mods::todo) — scheduled to-do processing

Jobs implement the JobTrait (cron expression + async work function) and run on the AsyncCron scheduler in Eastern timezone.

Call Processing Pipeline

The core flow from incoming call to post-call automation:

Incoming call (Twilio)
  → /twilio/voice → TwiML: start recording + open WebSocket
  → /twilio/stream (WSS)
    → Resolve phone number → agent → realtime config
    → Open AI session (OpenAI Realtime or Gemini Live)
    → Bidirectional audio streaming
    → Tool execution (knowledge queries, client lookup)
  → Call ends
  → /twilio/recording (async)
    → Download MP3 → Transcribe (GPT-4o) → Save
    → Contact enrichment
    → Analyzer execution
    → To-do extraction
    → Email report