MinbarLive — Technical Architecture

MinbarLive

Technical Architecture & Implementation

Tehnička Arhitektura i Implementacija

Building Real-Time
Multilingual Sermon
Delivery Izgradnja Real-Time
Višejezičnog Sistema
Isporuke Hutbe

A deep-dive into the architecture, AI pipeline, and infrastructure powering live khutbah captions for mosques worldwide.

Detaljan pregled arhitekture, AI pipeline-a i infrastrukture koja pokreće live titlove hutbe za džamije širom svijeta.

VersionVerzija2026-03

AudiencePublikaDevelopers / IT ManagersDeveloperi / IT Menadžeri

URLminbarlive.com

System Overview

Pregled Sistema

What MinbarLive Is Technically

Šta je MinbarLive Tehnički

A shared web + mobile platform for live sermon captions with real-time AI transcription, multilingual translation, and persistent archive.

Dijeljeni web + mobile platforma za live titlove hutbe s real-time AI transkripcijom, višejezičnim prijevodom i trajnom arhivom.

Public Surface

Javna Površina

Global directory

Globalni direktorij

Live reader

Live čitač

Core Technologies

Ključne Tehnologije

Frontend

Expo SDK 54 React Native Web Expo Router TypeScript

Backend

FastAPI (Python) Socket.IO WebSockets

Data & Auth

Podaci i Auth

Supabase (PostgreSQL) Supabase Auth Supabase Realtime

AI / ML

Deepgram STT OpenAI GPT-4 Dynamic prompts Keyword boosting

Session & State

Sesija i Stanje

Redis TTL sessions ZSET rate limiting Job tracking

Infrastructure

Infrastruktura

SendGrid (email) Correlation IDs Audit log

Architecture

Arhitektura

System Architecture Diagram

Dijagram Sistemske Arhitekture

Client Layer — Audience Web/Mobile

Klijentski Sloj — Audience Web/Mobile

Public API calls

Public API pozivi

Supabase Realtime subscription

Supabase Realtime pretplata

Heartbeat polling

↑ ↓

Admin Web/Mobile

Admin API (auth, stream, transcript, billing)

Admin API (auth, stream, transkript, naplata)

Ingest Gateway (browser/phone/mixer)

Ingest Gateway (browser/telefon/mikser)

Socket.IO (audio chunks)

Socket.IO (audio chunk-ovi)

↑ ↓

Backend Services (FastAPI)

Backend Servisi (FastAPI)

Audio pipeline (STT orchestration)

Audio pipeline (STT orkestracija)

Translation service

Servis prijevoda

Transcript service

Servis transkripta

Billing engine

AI Providers

AI Provajderi

Deepgram (STT — 20 lang)

OpenAI GPT-4 (translation + transcript)

↑ ↓

Core Data Layer

Centralni Sloj Podataka

Supabase PostgreSQL

Supabase Auth

Local file storage (config)

Lokalni fajlovi (config)

Session & Runtime State

Sesija i Runtime Stanje

Redis (sessions)

Redis (rate limit)

Redis (audio registry)

Redis (job tracking)

Core Pipeline

Centralni Pipeline

Audio Processing Flow

1

Audio Capture

Snimanje Zvuka

Browser mic (ScriptProcessorNode), phone upload, or external mixer. Admin selects ingest mode at session start.

Browser mikrofon (ScriptProcessorNode), upload s telefona, ili eksterni mikser. Admin bira mode pri startu sesije.

2

Chunked Streaming

Audio chunks sent via Socket.IO to backend. Smart buffering + segmentation for smooth subtitle display.

Audio chunk-ovi šalju se putem Socket.IO na backend. Smart buffering + segmentacija za glatki prikaz titlova.

3

Deepgram STT

Real-time speech-to-text via Deepgram WebSocket streaming. 20 source languages + auto-detect. Islamic vocabulary keyword boosting for BS/HR/SR.

Real-time speech-to-text putem Deepgram WebSocket streaminga. 20 izvornih jezika + auto-detekcija. Keyword boosting islamskog rječnika za BS/HR/SR.

4

AI Translation

AI Prijevod

OpenAI GPT-4 translates only into languages with active listeners. Dynamic per-stream prompts. Tuned for Islamic terminology and subtitle brevity.

OpenAI GPT-4 prevodi samo u jezike aktivnih slušalaca. Dinamički per-stream promptovi. Prilagođeno islamskoj terminologiji i kratkim titlovima.

5

Real-time Delivery

Real-time Isporuka

Translated segments pushed to Supabase. Audience receives via Supabase Realtime subscription + polling fallback.

Prevedeni segmenti guraju se u Supabase. Publika prima putem Supabase Realtime pretplate + polling fallback.

6

Archive & Transcript

Arhiva i Transkript

Session ends → transcript generation triggered (background thread, Redis job tracking). Export available per language.

Sesija završi → generacija transkripta pokreće se (background thread, Redis job tracking). Export dostupan po jeziku.

Access Control

Kontrola Pristupa

User Role Model

Model Korisničkih Uloga

Owner

Single account. Full platform access. Approvals, rejections, user governance, cross-org oversight.

Jedan account. Puni pristup platformi. Odobravanja, odbijanja, upravljanje korisnicima.

Full access Puni pristup

Super Admin

Scoped to managed_organization_ids. Manages multiple orgs, billing, analytics, admins. No owner-only actions.

Scoped na managed_organization_ids. Upravlja više org, billing, analitika, admini. Bez owner-only akcija.

Scoped multi-org Scoped multi-org

Admin

Single organization. Controls session, capture, archive, billing view for their mosque.

Jedna organizacija. Kontroliše sesiju, snimanje, arhivu, billing pregled za svoju džamiju.

Single org Jedna org

Public

Korisnik

No authentication needed. QR scan → join live session → read transcripts. Anonymous.

Bez autentifikacije. QR scan → join live sesiju → čitanje transkripta. Anonimno.

No auth Bez auth

Auth Implementation

Implementacija Auth-a

• Supabase Auth (email/password + Google OAuth) Supabase Auth (email/lozinka + Google OAuth)

• Session tokens stored in Redis with TTL auto-expiry Session token-i u Redisu s TTL auto-expiryjem

• Supabase fallback when Redis unavailable Supabase fallback kad Redis nije dostupan

• Rate limiting via Redis ZSET sliding window Rate limiting putem Redis ZSET sliding window-a

• Registration requires privacy + terms consent Registracija zahtijeva pristanak na privacy + terms

Organization Hierarchy

Hijerarhija Organizacija

Master org Master org Child orgs Child org managed_organization_ids

Codebase

Key Modules & Files

Ključni Moduli i Fajlovi

Backend (FastAPI + Python)

›server.py — app assembly, Socket.IO wiring (1050 lines)sklapanje app-a, Socket.IO wiring (1050 linija)

›audio_pipeline.py — STT orchestration (513 lines, ↓59%)STT orkestracija (513 linija, ↓59%)

›transcript_service.py — transcript lifecyclelifecycle transkripta

›session_store.py — Redis-backed session storeRedis-backed session store

›auth_helpers.py — auth/session/access helpersauth/session/access helperi

›routers/admin.py — 1026 lines (modularization target)1026 linija (cilj modularizacije)

›costing/ — 6 billing modules (~1621 lines)6 billing modula (~1621 linija)

Frontend (Expo / React Native Web)

›app/admin.tsx — 1053 lines (was 2776, ↓62%)1053 linija (bilo 2776, ↓62%)

›app/index.tsx — 956 lines (was 1257, ↓24%)956 linija (bilo 1257, ↓24%)

›app/super-admin.tsx — 1323 lines (billing section extracted)1323 linija (billing sekcija izvučena)

›lib/adminAuth.ts — admin API client + auth sessionadmin API klijent + auth sesija

›lib/adminAccess.ts — role-based frontend access logicrole-based frontend access logika

›21 extracted components — 6 extracted hooks from admin6 izvučenih hookova iz admin-a

Security & Observability

Sigurnost i Observabilnost

Security & Monitoring

Sigurnost i Praćenje

Security Controls

Sigurnosne Kontrole

✓Redis session store with TTL auto-expiryRedis session store s TTL auto-expiryjem

✓Rate limiting via ZSET sliding window (per IP/user)Rate limiting putem ZSET sliding window-a

✓Privileged action audit log (JSONL)Audit log privilegiranih akcija (JSONL)

✓Consent checkboxes on registrationConsent checkboxovi pri registraciji

✓Supabase Row Level Security (RLS)Supabase Row Level Security (RLS)

⚠Audit log not yet cluster-safe (local JSONL)Audit log nije cluster-safe (lokalni JSONL)

⚠No formal key rotation / secrets managementBez formalnog key rotation / secrets management-a

Observability

Observabilnost

✓RequestCorrelationMiddleware (X-Correlation-ID)

✓Structured request loggingStrukturirani request logging

✓Deep health endpoint (degraded/healthy status)Deep health endpoint (degraded/healthy status)

✓Operator notification ring bufferOperator notification ring buffer

✓Capture health strip (admin UI)Capture health strip (admin UI)

✓14 smoke tests (backend/tests/smoke_test.py)

✓Event timeline in admin control panelEvent timeline u admin control panelu

Billing / Cost Tracking

Billing / Praćenje Troškova

6-module billing engine: fixed costs, usage events (Deepgram + OpenAI), org allocation (equal/custom), daily breakdowns, monthly reports, markup separation.

6-modularni billing engine: fiksni troškovi, usage eventi (Deepgram + OpenAI), org alokacija (jednaka/custom), dnevni pregledi, mjesečni izvještaji, markup odvajanje.

Current Status

Trenutni Status

Implementation Progress

Napredak Implementacije

Phase 1 — Stabilization

Env-driven config, no hardcoded fallbacksEnv-driven config, bez hardcoded fallbacksDONEGOTOVO

Remove silent failures, surface errorsUklanjanje tihih grešakaDONEGOTOVO

Smoke/integration tests (14 tests)Smoke/integration testovi (14)DONEGOTOVO

Canonical documentationKanonska dokumentacijaDONEGOTOVO

Phase 2 — Optimization

admin.tsx 2776→1053 lines (−62%)DONEGOTOVO

audio_pipeline.py 1253→513 (−59%)DONEGOTOVO

Translation cachingCaching prijevodaPLANNEDPLANIRANO

Phase 3 — Scaling

Redis for sessions/rate limiting/registryRedis za sesije/rate limiting/registryDONEGOTOVO

Durable job queue for transcriptsDurable job queue za transkriptePARTIALDJELIMIČNO

File-backed config → DB migrationMigracija config fajlova → DBPLANNEDPLANIRANO

Phase 4 — Enterprise

Billing/cost tracking foundationOsnova billing/cost trackingaDONEGOTOVO

White-label + custom domainsWhite-label + custom domenePLANNEDPLANIRANO

AudioWorklet capture (replaces deprecated API)AudioWorklet snimanjePLANNEDPLANIRANO

Technical Roadmap

Tehnički Roadmap

Next Workstreams

Sljedeći Radni Tokovi

W1 — Backend Owner Flag

Replace email-based owner truth with explicit is_owner backend field. Clean governance policy.

Zamjena email-based owner truth-a s eksplicitnim is_owner backend poljem.

W2 — Organization Hierarchy UX

Organization switcher for scoped super admin. Master/child org UX. Scope badge.

Organization switcher za scoped super admin. Master/child org UX. Scope badge.

W3 — Durable Transcript Queue

ARQ + Redis Streams. Retry + dead-letter handling. Transcript job survives restarts.

ARQ + Redis Streams. Retry + dead-letter handling. Transcript job preživi restart.

W4 — Public Realtime Path

Backend SSE/Socket.IO namespace. Remove frontend direct Supabase subscriptions.

Backend SSE/Socket.IO namespace. Ukloniti direktne Supabase pretplate iz frontenda.

W5 — Billing Completion

W5 — Dovršetak Billinga

Real daily/monthly aggregates. PDF export. Invoice generation. Email dispatch.

Stvarni dnevni/mjesečni agregati. PDF export. Generacija faktura. Email dispatch.

W6 — White-label Web Platform

W6 — White-label Web Platforma

custom_domains + brand_settings model. Tenant resolution by Host header. Host-aware link generation.

custom_domains + brand_settings model. Tenant resolution po Host headeru.

W7 — HR Full Polish

W7 — Potpuni HR Polish

Final sweep: copy, error states, empty states, diacritics (č, ć, ž, š, đ).

Završni sweep: copy, error stanja, prazna stanja, dijakritika.

W8 — Decomposition & Instrumentation

W8 — Dekompozicija i Instrumentacija

Router modularization. Deployment health score. Session health reporting.

Modularizacija routera. Deployment health score. Session health izvještavanje.

CTO Assessment: "The product is viable. The architecture is now partially investable." — CTO Audit 2026-03-24

CTO Procjena: "Proizvod je viabilan. Arhitektura je sada djelimično investabilna." — CTO Audit 2026-03-24