Helel.ai — Real-Time AI Video Companion

The provider-agnostic core is the spine of the system. Rather than calling a language-model SDK or an avatar-video SDK directly from feature code, every feature talks to an internal interface — a companion 'brain' port and an avatar 'session' port — and each concrete vendor is one adapter behind that port. Selecting a vendor is a configuration value read at startup, not a code path sprinkled through the app, so swapping the model provider or the avatar vendor is a config change plus a new adapter rather than a rewrite of the product. This also made the text fallback natural to build: it is simply another implementation of the same conversation contract the video path uses.

Consent-gated memory is modelled as an explicit lifecycle rather than an implicit side effect of chatting. Content the user shares stays ephemeral until they approve it for memory; on approval it is chunked, embedded, and written to the vector store as durable profile chunks tied to that user. On un-approval those chunks are deleted, not flagged — the retrieval layer can only ever see what is currently approved, so 'forget this' genuinely removes it from what the companion can recall. Retrieval itself is RAG over the approved chunks: the relevant pieces of the profile are pulled by vector similarity and handed to the companion as grounding for the current turn, which keeps responses tied to what the person actually told it.

The personality onboarding is a save-and-resume assessment, because a first-time user should be able to leave halfway and come back without losing progress. Answers are persisted as they go and assembled into a structured profile that briefs the companion at session start. Keeping the profile structured — rather than a free-text blob — is what lets the rest of the system reason about it: it feeds the initial session briefing, and the portions the user later approves become the seed of durable memory.

The real-time session lifecycle is treated as a state machine with a fallback built in from the start, not patched on. A session negotiates a live avatar stream through the vendor adapter; if that stream cannot be established or drops mid-conversation, the same conversation continues over the text fallback path against the identical brain contract, so context is not lost when the medium changes. Because both paths speak the same internal interface, the companion's behaviour and memory access are identical regardless of whether the user is on video or text.

Per-tenant data isolation is enforced at the database layer, on every table, rather than trusted to application code remembering to filter. Every row is scoped to its tenant and access is constrained at the data layer, so a query from one tenant structurally cannot return another tenant's rows — the isolation holds even if a feature forgets to add a WHERE clause. For a product built around private, personal memory across multiple tenants, that guarantee living in the database rather than in convention was a deliberate requirement.

Every boundary in the system is schema-validated in TypeScript: the shapes crossing between the client, the server routes, the database, and the vendor adapters are parsed and validated rather than assumed, so malformed or unexpected payloads fail loudly at the edge instead of corrupting state deep inside. The whole thing ships with CI running on every change and a documented go-live handover — architecture, configuration, and operational notes — so the client owns and can run the system outright rather than depending on the person who built it.