Sola - Magma Electric AI assistant

# Sola - Magma Electric AI assistant

Rainier Labs demonstration for Magma Electric: its live website with Sola, an English/French AI assistant with internet-based Retell voice calls. Requests are saved to the protected demo dashboard only, not sent to Magma.

Deployed service: https://magma.rainierlabs.io/ (admin: `/admin`). Railway alternate: https://magma-web-production.up.railway.app/.

The custom hostname uses Railway-managed HTTPS and these GoDaddy DNS records:

| Type | Name | Value |
|---|---|---|
| CNAME | `magma` | `urpfeokp.up.railway.app` |
| TXT | `_railway-verify.magma` | `railway-verify=db1f8d44c36c5a090ff0bfa67e1b30b5e7c289001eac25bf005be6ae55d50c30` |

Production `PUBLIC_BASE_URL` and the dedicated Retell agent's tools/webhook use `https://magma.rainierlabs.io`. Preserve both DNS records for domain ownership verification and routing.

## Website and assistant

`/` displays `https://magma-electric.com/` in a sandboxed full-page iframe. The bottom-right orange/pink assistant remains outside the iframe as visitors navigate. This is not a static copy and does not change Magma's original website. Original forms, WhatsApp and telephone links contact Magma directly; assistant forms do not.

Sola's header and "Talk to Sola" launcher use the supplied button design's white-circle mark with three rounded orange waveform bars. The bars animate as an equalizer only during Retell's agent-speaking events, not when the caller speaks or a call is merely connected. They stop during silence, call end or error; reduced-motion preferences disable the animation. The launcher label remains visible on mobile when closed. The design is integrated with this application's existing server-mediated call flow, not the sample's public-key client or demo-call mode.

The widget provides eight bilingual welcome suggestions, English/French switching, panel expansion, drag/keyboard resizing from an invisible upper-left corner handle, a vertically resizable message box, a clear-conversation bin button, an inline request form and browser voice controls. The panel uses the full screen on small mobile viewports. Chat context survives minimizing the panel; clearing immediately starts a separate conversation without a confirmation dialog. This clears the screen, not stored records; use `/privacy` for data deletion. An active call remains visibly indicated when minimized, and must be ended before clearing.

Browser calls use Wi-Fi/mobile data, not a telephone number. There are no international telephone charges from the demo, but visitors may pay for data and the account owner pays Retell/Azure usage. No US number is purchased or bound. No outbound calls, SMS, email delivery, CRM, live transfers or appointments are implemented.

## Architecture and routes

One TypeScript/Express service hosts the shell, assistant, API and staff dashboard. Customer code is bundled with esbuild.

| Route | Purpose |
|---|---|
| `/` | Original Magma site and assistant launcher |
| `/assistant` | Full-page/embedded bilingual assistant |
| `/privacy` | AI processing, retention and self-service data deletion |
| `/admin` | Protected conversations, browser calls and routed requests |
| `/admin/sources` | Knowledge coverage, source previews, review and sync history |
| `/readme` | This technical overview |
| `/healthz` | Database/knowledge readiness |

Azure OpenAI generates answers using approved knowledge and recent conversation history. Document authority takes precedence over website text. Source validation remains server-side; customer replies do not display citation chips. Postgres/pgvector provides vector retrieval alongside multilingual keyword matching. Local development/tests can use PGlite with explicit keyword-only retrieval; production requires Postgres.

Retell's dedicated Magma agent introduces itself as Sola and uses Willa, a British female ElevenLabs voice, with warm, friendly delivery instructions. It uses signed backend tools for approved answers and consented lead saving. The browser SDK uses a strict backend call-start route; private provider credentials never enter browser code. The backend fixes the agent/version and rejects arbitrary agent IDs and overrides. SDK v3 connection fields are schema-validated.

## Knowledge and limitations

Approved public company facts were curated from the supplied Word knowledge base. The raw document mixes public and restricted material and is never committed, served or uploaded wholesale. Internal instructions become server-side policy, not retrievable facts.

The importer discovers Magma's page/service/news sitemaps. The initial audit found 29 content pages. Website content is initially pending review; unrelated content and template legal text are excluded. Only approved sources enter retrieval. Fetch failure preserves existing approved knowledge. Changed content requires review.

The website exposes unrelated gambling-themed tags and an unrelated link/template remnants in legal text. These are source-quality concerns, not a determination that the site is compromised. The owner should review them. The live frame still displays what the original site serves; we do not control or repair that site.

The authoritative company record describes the Ethiopia embassy project as completed with 350 kWp. Its storage unit is ambiguous and that specification is withheld. Manufacturer authorization, guarantees and unverified departmental addresses are not invented. General enquiries may use `info@magma-electric.com`; departmental mailbox publication requires verification.

Chat/voice are demonstrations and may make mistakes. They cannot provide engineering sign-off, guaranteed pricing, savings, autonomy or warranty terms. Electrical hazards require approved onsite emergency procedures and qualified personnel, never DIY live-electrical instructions.

## Requests and dashboard

A request requires explicit contact consent, a name, and either email or an international phone number. Djibouti `+253` and email-only contact are supported; no US ZIP is required. Project details are optional and requests may be classified as sales, engineering or mixed.

Server-controlled saving returns an honest demo-only acknowledgement. Extraction from ordinary chat cannot itself create a lead. Voice saving requires affirmative user-consent evidence in the signed call transcript. There is no caller telephone number on a browser call.

The dashboard follows the reference demos' gradient header, cream background, insights, persistent metrics, date filters, selectable results and staff actions. Reporting uses `Africa/Djibouti` (UTC+3). Staff status is independent of qualification and does not restore withdrawn consent. Source previews/review and raw conversation details are admin-only.

## Privacy and cost controls

An AI/privacy acknowledgement is required before chat or voice. Contact saving requires separate consent. The signed HttpOnly SameSite session cookie binds conversation access to the visitor; conversation IDs alone are insufficient.

Demo transcripts, leads, summaries, consent and associated personal data are deleted after 30 days. A recurring maintenance job runs after startup and every 30 seconds. Provider call deletion precedes local deletion, failures remain retryable, and tombstones/ownership checks prevent late webhooks from recreating removed records. `/privacy` offers browser-scoped deletion and contact-consent withdrawal.

Retell uses `basic_attributes_only`: provider-stored recordings/transcripts/logs are disabled, with 30-day retention for retained basic attributes. Signed webhook transcripts can be retained locally for 30 days. Retell still processes live audio and its speech/model providers are involved. Azure processes chat and embeddings; Railway hosts the app/database. Processing can occur outside Djibouti. Infrastructure/backup retention follows provider schedules.

Voice limits are persistent and enforced server-side:

- 300 seconds maximum per call, also configured on the Retell agent.
- Three starts per signed visitor session per rolling hour, with additional IP abuse limits.
- 1,800 seconds total daily allocation, using Djibouti calendar days.
- Atomic five-minute reservations include pending/active calls. Reconciled actual usage releases unused allocation. An ambiguous provider timeout retains its allocation rather than assuming no paid call exists.

An unknown reservation can intentionally keep the demo budget unavailable pending operator reconciliation. Browser sessions are not verified human identities. These controls reduce abuse; they are not an absolute account-wide billing ceiling against activity outside this app.

Call-record/privacy deletion does not reset spending counters. The separate quota ledger retains no conversation content; its visitor/IP hashes expire after one hour, and completed aggregate entries expire after two days.

## Development

Requires Node.js 22 or newer.

```powershell
npm ci
Copy-Item .env.example .env
# Set a unique SESSION_SECRET (at least 32 characters), ADMIN_PASSWORD and provider configuration privately.
npm run dev
```

Without `DATABASE_URL`, nonproduction uses persistent PGlite in `.pglite`. Production startup fails without a dedicated database, admin password, session secret, HTTPS base URL and Azure configuration.

Environment variables are documented in `.env.example`. Reuse only approved provider credentials from the reference projects. Never reuse their databases, agent IDs, phone numbers, admin passwords or application secrets. `.env` and local databases are ignored.

```powershell
npm run sync
npm run retell:sync -- --dry-run
# Set PUBLIC_BASE_URL to the deployed HTTPS origin before publishing:
npm run retell:sync
npm run check
npm test
npm run build
npm run test:browser
npm run secret-scan
```

The Retell script creates/updates only an ownership-checked Magma agent/LLM, publishes it, and verifies persisted privacy/duration settings. It never purchases or binds phone numbers. The browser SDK is pinned by the lockfile; provider/API compatibility must be checked when upgrading.

## Deployment and operations

Use a dedicated Railway app and pgvector-enabled Postgres service with a persistent volume. Set production variables privately; do not upload `.env`. `railway.json` builds the app and checks `/healthz`. Import reviewed knowledge and publish the Magma Retell agent using exact deployed tool/webhook URLs.

Add only the Railway-generated DNS records for `magma.rainierlabs.io`; preserve the root and other demos. Verify HTTPS before enabling microphone calls. Enable `VOICE_ENABLED=true` only after the agent settings and endpoint connection are verified.

Use `/admin/sources` to refresh and approve website content. Refresh errors are shown in sync history. Review company facts with Magma before relying on them commercially. Check ambiguous storage units and departmental mailboxes separately. Keep website source concerns visible to its owner.

For rollback, redeploy the previous validated application deployment while preserving the dedicated database and retained consent. Do not silently reset data or quota reservations. Keep agent versions aligned with the selected app's tool contract.

To investigate quota/retention failures, inspect structured server errors and protected records without exporting transcripts into logs. Provider keys/tokens are never logged. Provider failures are shown to visitors; saving, delivery and voice success are never fabricated.

## Later installation on the original WordPress site

An authorized WordPress editor can install:

```html
<script src="https://magma.rainierlabs.io/widget.js" defer></script>
```

Then explicitly allow `https://magma-electric.com` in `WIDGET_EMBED_ORIGINS` and verify the host's CSP and microphone Permissions Policy/delegation. This requires authorized site editing; access to a public URL alone is insufficient. Nothing is installed on the original site by this project.

## Verification boundaries

Automated tests exercise backend persistence, source isolation, international contacts, consent, session/CSRF boundaries, signed events, concurrent exact quota thresholds and retention failure/retry behavior. Browser tests cover desktop/mobile UI, original-site rendering/navigation and mocked voice interaction. Mock tests are not evidence of audible provider voice quality or connectivity from Djibouti.

Deployed acceptance included 30 real English/French Azure-backed questions and real Retell browser connections. Synthetic spoken input verified speech recognition, grounded tool calls, spoken responses and dashboard transcripts in both selected languages; the French run used an English-spoken question and verified a French answer. Synthetic test records were deleted afterward.

Human microphone quality, native French recognition/pronunciation, connectivity from Djibouti, and company approval of outstanding facts still require live/client verification. Deployment/domain status must be checked rather than inferred from a successful build.