Decizii Arhitecturale — VirtualMeetings

Log-ul deciziilor tehnice și de produs importante. Format: Decizie → De ce → Alternativele respinse → Trade-offs. Util pentru: onboarding co-fondator, audit retrospectiv, evitarea reenventării roții.

D1. grammar_mode = “batch” (mai 2026)

Decizia: Claude rulează 1× pe întregul discurs al vorbitorului anterior când se face n <next>, NU per chunk de 5s live.

De ce: Calitate mult superioară — Claude vede contextul complet, nu fragmente. Primul test live (2026-05-12) a arătat că “live” pierdea chunks în coadă la rate-limit CLI (1 worker).

Alternative respinse: - Live per chunk: latență mică dar calitate slabă + drops frecvente la 4 workeri paraleli (rate-limit 29s/call) - Streaming Claude: nu adaugă valoare pentru grammar (nu e chat, e analiză)

Trade-off acceptat: Feedback vine după ce vorbitorul termină (30s-1min delay), nu în timp real. Acceptabil pentru rolul Gramatician› (feedback oral e și el post-discurs).

D2. Audio mic > Zoom Process Tap (mai 2026)

Decizia: Config câștigătoare = audio mic + speakers Mac active (NU Process Tap pe Zoom, NU căști).

De ce: Evidență empirică clară (deep analysis 2026-05-16): - audio_mic: 0 halucinații, 17/17 chunks transcrise, avg_logprob -0.44 - audio_zoom: ~40% halucinații, loop collapse, avg_logprob -0.57 la RMS mai mare

Cauza: Zoom audio engine aplică Echo Cancellation + AGC + Noise Gate agresiv → spectru low-pass, 50% energie sub 891 Hz → Whisper halucinează YouTube outros.

Alternative respinse: - audio system (BlackHole): SIGABRT pe M1 (MLX-Metal + PyTorch-JIT contention). Dezactivat până la fix post-2026-05-20. - Dezactivat echo cancel Zoom: parțial ajută, dar procesarea rămâne activă la alte niveluri.

Trade-off acceptat: Pavel capturează și propria voce (e gramatician, nu vorbitor — OK). Volumul speakers trebuie reglat la RMS 4-8%.

D3. Architecture-first ≠ Platform-first (mai 2026)

Decizia: Nu construim „Zoom mai bun” general-purpose. Construim orchestrare 22 roluri TM ca module software cu validare umană. Video conferencing = layer fungibil.

De ce: Clarificare Pavel: „Rolurile trebuie definite și integrate în software — îndeplinite de tehnică, coordonate și validate uman.” Asta inversează complet problema.

Alternative respinse: - Build Zoom replacement: 80% efort pe video stack (nereplicabil în 6 luni solo), 20% pe diferențiator - Fork Jitsi: inertă React + Java mods frustrating, overkill pentru 25 useri - LiveKit acum: prematur — nu ai module mature pentru a justifica migrarea clubului

Trade-off acceptat: Rămânem pe Zoom ca companion app mai mult timp. Câștig: fiecare modul e testabil incremental, fără dependency pe migrare platformă.

D4. Markdown ca sursă de adevăr (mai 2026)

Decizia: TM Knowledge Hub e markdown. HTML e artifact generat la publicare via build_html.py.

De ce: VS Code preview nativ, diff granular, edit cu Edit tool, no CDN, offline. „Wow factor” HTML e pentru oameni din afară, nu pentru uz intern.

Alternative respinse: - HTML wow inline: hard to edit, diff mare la orice schimbare mică, rebuild frecvent - Notion / Confluence: cloud, nu offline, vendor lock-in, nu se integrează cu codul

Trade-off acceptat: Pentru lansare externă (Iteration 3), generezi HTML din markdown cu build_html.py --open. Nu e nevoie să menții două surse.

D5. num_grammar_workers = 1 (mai 2026)

Decizia: Un singur worker grammar async, NU 4 paralele.

De ce: 4 workers paraleli la CLI Claude = rate-limit intern la 29s/call (confirmat live). 1 worker = stable 30s/call fără drops.

Alternative respinse: - 4 workers: par mai rapizi teoretic, dar practic toți blochează pe același rate-limiter OAuth - API directă: pay-per-token vs $0 pe Max subscription

Trade-off acceptat: Coada de grammar analysis crește la ședințe lungi (10+ vorbitori). Mitigare: dacă coada > 5 → activezi local_llm_only=True (Ollama Aya 8B offline).

D6. Fire-and-forget pentru filler repair (mai 2026)

Decizia: Filler repair AI (suggest_filler_repair) rulează DUPĂ ce audit-ul a fost emis la UI, ca asyncio.create_task separat.

De ce: Audit response trebuie livrat <100ms (filler count + transcript). Repair AI (Claude call, ~3-8s) nu poate bloca asta.

Alternative respinse: - Repair în același call grammar: mărește latența per chunk, pierde feedback rapid - Repair sincron în audit worker: blochează ceilalți chunks din coadă

Trade-off acceptat: Repair ajunge cu 1-3s delay față de audit — UI actualizează în două etape (mai întâi count, apoi sugestia). Imperceptibil în practică.

D7. Human-in-the-Loop ca pattern fundamental (mai 2026)

Decizia: Software face 80% din muncă (detection, transcript, analysis). Omul validează 20% care contează (accept/reject issue, +1 manual filler, notițe col 4).

De ce: TM e despre oameni — feedback uman e mai valoros decât automatie pură. Modelele AI greșesc. Un Gramatician uman care vede un calc subtil pe care Claude nu l-a prins e mai valoros decât 100% automatie cu 5% erori.

Alternativele respinse: - Full automatie: erori nedetectate ajung în raport → credibilitate zero - Full manual: tool nu adaugă valoare față de pix și hârtie

Trade-off acceptat: Necesită atenție umană în timpul ședinței (Pavel nu poate să adoarmă). Câștig: rapoarte de calitate ridicată, validabile.

D8. Extend întâi, build mai târziu (mai 2026)

Decizia: Extindem VirtualMeetings ca companion Zoom + role modules. NU construim platformă proprie până la 5+ module mature și semnal real de adopție extern.

De ce: Network effects imposibile fără capital. Zoom e gratuit. Niciun club nu migrează fără funcționalități pe care Zoom nu le are — iar noi nu le avem pe toate încă.

Timeline: Companion app → 5+ module → alt club → own platform (LiveKit, $50/mo).

Alternative respinse: - Build own platform acum: 80% efort pe video infra, 20% pe diferențiator. Greșeală clasică. - Zoom bot (Otter-style): risk policy ridicat (Zoom blochează bots), cluburi neîncrezătoare, cost lunar.

D9. RTMS Zoom — wait (mai 2026)

Decizia: Nu integrăm Zoom RTMS (Real-Time Media Streams) acum.

De ce: GA junho 2025 = feature nou, pricing nepublic (contact sales), community forum minimal, posibil deprecat sau repriced oricând.

Reconsidera când: Pricing transparent + 6 luni community feedback + pricing < $100/lună pentru 25 useri.

D10. Java from scratch = respins explicit (mai 2026)

Decizia: NU construim media path (SFU, audio processing) în Java.

De ce: GC pauses 50-200ms rup RTT <30ms necesar audio real-time. Niciun SFU modern serios nu e Java (mediasoup = Node.js/C++, LiveKit = Go, Janus = C).

Java OK pentru: business backend (Spring Boot), baze de date, REST API. Java NU pentru: media path real-time, audio processing, low-latency networking.