Skip to content

prd.md

Latest commit

 

History

History
408 lines (313 loc) · 19.4 KB

prd.md

File metadata and controls

408 lines (313 loc) · 19.4 KB
Raw

DabljaAR Product Requirements Document

Version: 1.0
Date: July 2026
Status: Draft — based on product readiness audit of backend, frontend, and documentation

Table of Contents

  1. Current State Summary
  2. Gap Analysis — General App Software Readiness
  3. Documentation Audit — Outdated & Missing
  4. Product Requirements
  5. Immediate Next Steps

1. Current State Summary

DabljaAR is an AI video dubbing platform (English/Spanish/Italian → Arabic) with an event-driven microservices backend and a React SPA frontend.

flowchart LR
    subgraph ready [Production-Ready Core]
        Upload[Upload / YouTube / Record]
        Pipeline[STT → NMT → TTS → Merge]
        Dashboard[Job tracking + History]
        Voices[Custom voice library]
    end
    subgraph gaps [Product Gaps]
        OAuth[Google OAuth - demo only]
        Billing[Credits / Stripe - UI only]
        Notify[Notifications - prefs only]
        Onboard[User onboarding - none]
        Reset[Forgot password - unwired]
    end
    User --> Upload --> Pipeline --> Dashboard
    User -.-> gaps
Loading
Layer Maturity Key files
AI pipeline High orchestrator/, stt-service/, nmt-service/, tts-service/, media-service/
Backend API Medium backend/app/main.py, backend/app/api/media_routers.py
Frontend UX Medium frontend/src/pages/Dashboard/Dashboard.jsx, frontend/src/pages/Profile/Profile.jsx
Auth & account Low–Medium JWT email/password works; OAuth, reset, email verification missing
Monetization Low CRUD APIs exist; no Stripe, credits model, or enforcement
Documentation Mixed Production docs current; onboarding/architecture/API docs stale

2. Gap Analysis — General App Software Readiness

2.1 Authentication & Account (Critical)

Gap Current state Impact
Google OAuth UI buttons show demo toast only (frontend/src/pages/Login/Login.jsx); backend has GOOGLE_REDIRECT_URL / Auth0 env vars but no routes (backend/app/config.py) Users expect one-click sign-in; friction at signup
Forgot password Backend stub always returns success (backend/app/core/router.py); frontend page exists but no route, authService.forgotPassword undefined (frontend/src/pages/ForgotPassword/ForgotPassword.jsx) Account recovery broken
Email verification Not implemented Spam accounts, unverified email changes
Server-side logout No token blacklist; frontend clears local storage only Sessions cannot be revoked
Authorization bugs Avatar upload unauthenticated; any user can CRUD other users; is_active not enforced; RBAC model unused Security risk before public launch

2.2 Monetization & Usage (Critical for SaaS)

Gap Current state Impact
Credits system Hardcoded 25 in navbar (frontend/src/components/layout/Navbar.jsx); profile stats hardcoded (47 videos, 235 credits) Misleading UX; no usage limits
Stripe / checkout PaymentMethod.STRIPE enum exists; subscription/payment CRUD only — no webhooks or checkout Cannot charge users
Credit enforcement Jobs created without credit deduction Free unlimited usage
Free tier Marketing copy mentions "3 free credits on signup" (frontend/src/utils/translations.js) — not implemented Broken promise

2.3 Engagement & Retention (High)

Gap Current state Impact
User onboarding Zero matches for onboarding in frontend/src/ New users face complex dashboard cold-start
In-app notifications DB prefs (notif_completed, notif_credits, notif_marketing) saved; no delivery (email, push, or feed) Users miss job completion
Real-time progress 5s polling (frontend/src/hooks/useJobPolling.ts); README lists WebSocket/SSE as future work Feels sluggish on long jobs
Empty states History/voice library have them; dashboard JobList has no empty state (frontend/src/components/dashboard/JobList.jsx) Confusing first visit
Social / sharing None No viral loop
Gamification None Low stickiness

2.4 UX Polish (Medium)

Gap Current state
PWA Install prompt exists; no service worker; manifest references missing icons (frontend/public/manifest.json)
Accessibility Partial ARIA; hamburger is <div onClick>; no skip-nav; English-only ErrorBoundary
i18n EN/AR UI strings strong; error pages not fully translated
Demo features visible Google login button shown despite demo-only behavior

2.5 DevOps & Quality (Medium)

Gap Current state
Frontend CI Workflow disabled (.github/disabled-workflows/frontend-tests.yml)
Integration tests Skipped in backend CI (@pytest.mark.skip)
E2E tests None (no Playwright/Cypress)
Native dev path start.sh starts Celery workers, not RabbitMQ microservices — contradicts root README

3. Documentation Audit — Outdated & Missing

3.1 Docs to treat as canonical (current)

3.2 Docs requiring major rewrite

Doc Outdated content Should say
architecture.md Celery + Redis monolith, MMS TTS, Vite 4, 3 Alembic revisions Microservices + RabbitMQ + OmniVoice; link to LLD
onboarding.md docker compose up postgres redis, Celery workers, Flower docker compose up --build; RabbitMQ + orchestrator path
docker_setup.md 3-service stack, docker-compose.prod.yml Full microservices compose + docker-compose.microservices.prod.yml
media.md "Async via Celery" BackgroundTasks preprocess + RabbitMQ job.created
runbook.md §1–3 Celery/Flower troubleshooting RabbitMQ DLQ, orchestrator, worker logs
pipeline.md Celery queue names (ai_stt, etc.) RabbitMQ routing keys (job.start.stt, etc.)

3.3 Docs requiring targeted updates

Doc Specific mismatches
api.md GET /me → actual: GET /auth/me; PATCH /me → PUT /users/{id}; access TTL "15 min" vs 300 min default; /docs → /api/docs; text upload "no Job" is wrong; missing /voices/*, /tasks/*, billing CRUD
frontend/README.md Claims Prettier format script (not in package.json); offline service worker (none exists); features/ folder (missing)
orchestrator/README.md Workers labeled "not yet built" — they exist in compose
gpu_setup.md "Known gaps" section fixed in code but not in doc
microservices_lld.md TTS still called "SILMA" in places; phase table inconsistent
backend/.env.example SILMA TTS vars, Celery/Redis, missing RABBITMQ_URL; Auth0 vars imply working OAuth

3.4 Missing documentation topics

  1. Unified environment variable reference (all services)
  2. Per-service READMEs (stt-service, nmt-service, tts-service, media-service, libs/dablja-worker)
  3. Clear separation: Docker microservices dev vs legacy Celery start.sh path
  4. Complete API reference (voices, tasks, subscriptions)
  5. Security doc (worker callback auth, ownership rules)
  6. CONTRIBUTING.md + CI behavior
  7. Current database ERD (video_tasks, voices, notification prefs)
  8. User-facing help / FAQ (none exists)

3.5 Recommended doc actions (priority)

  1. Add deprecation banner to architecture.md → point to root README + microservices_lld.md
  2. Rewrite onboarding.md for docker compose up --build as primary path
  3. Regenerate or manually fix api.md against live OpenAPI at /api/docs
  4. Archive backend/SILMA_*, DIALECT_GUIDE.md as historical
  5. Create docs/env-reference.md from .env.production.example + config.py

4. Product Requirements

4.1 Product vision

DabljaAR enables creators, educators, and media teams to dub video content into natural Arabic in minutes — without studios, voice actors, or manual translation. The product must feel as easy as "upload → choose voice → download," while building trust through reliable auth, transparent usage, and timely feedback.

4.2 Target users

Persona Goal Success metric
Content creator Dub YouTube/social clips to Arabic audience First dubbed video in <15 min
Educator Translate lecture videos with captions Accurate transcript + downloadable SRT
SMB media team Batch-process client content Team accounts, usage tracking
Casual visitor Try before buying Guest preview or free credits

4.3 Product principles

  1. Trust first — real auth, real billing, no demo buttons in production
  2. Progressive disclosure — simple default path; advanced options (voice clone, trim, reprocess) available but not blocking
  3. Feedback loops — users always know job status and when results are ready
  4. Bilingual by default — EN/AR UI with RTL support maintained

4.4 Must-have use cases (P0 — launch blockers)

UC-01: Sign up and sign in with email

  • Actor: New or returning user
  • Flow: Register with email/password → receive JWT → land on dashboard
  • Acceptance: Form validation, rate limiting, remember-me, protected routes work
  • Gap: Core works; fix authz on user CRUD and avatar upload

UC-02: Sign in with Google (OAuth)

  • Actor: User preferring social login
  • Flow: Click "Continue with Google" → OAuth consent → account created/linked → dashboard
  • Acceptance: No demo toast; backend issues same JWT pair; existing email accounts can link
  • Gap: Not implemented (frontend demo + backend config stubs only)

UC-03: Reset forgotten password

  • Actor: User who forgot password
  • Flow: Login → Forgot password → email with reset link → set new password → login
  • Acceptance: Token expires in 1h; email not enumerable; link works once
  • Gap: Not implemented (stub endpoint + unwired frontend)

UC-04: Complete first dubbing job (happy path)

  • Actor: Authenticated user
  • Flow: Upload video → select output mode + voice → submit → see progress → download/play result
  • Acceptance: Job completes via microservices pipeline; errors shown clearly; history entry created
  • Gap: Pipeline works; needs onboarding guidance for first-time users

UC-05: Track job progress

  • Actor: User with active jobs
  • Flow: Dashboard shows queue; status updates as stages complete; notification on completion
  • Acceptance: Status reflects STT/NMT/TTS/merge phases; failed jobs show actionable error
  • Gap: Polling works; no email/in-app notification delivery

UC-06: Manage profile and preferences

  • Actor: Authenticated user
  • Flow: Update name, avatar, default voice/language, notification prefs, change password, delete account
  • Acceptance: Changes persist; deletion removes media from storage
  • Gap: Mostly works; avatar upload needs auth; stats are hardcoded

UC-07: Understand and manage usage (credits)

  • Actor: Paying or free-tier user
  • Flow: See credit balance → job shows cost before submit → credits deducted on success → buy more
  • Acceptance: Balance accurate; insufficient credits block submit with upgrade CTA
  • Gap: Not implemented — all UI is hardcoded

UC-08: Subscribe or purchase credits

  • Actor: User ready to pay
  • Flow: Choose plan → Stripe checkout → webhook activates subscription/credits → reflected in profile
  • Acceptance: PCI-compliant (Stripe hosted); invoices available; cancel anytime
  • Gap: Not implemented — demo toasts only

4.5 Should-have use cases (P1 — engagement & retention)

ID Use case Requirement
UC-09 First-run onboarding 3-step wizard: upload sample → pick mode → watch progress
UC-10 Email notifications Job complete, low credits, marketing (opt-in) via SendGrid/SES
UC-11 In-app notification center Bell icon with unread count; links to completed jobs
UC-12 Re-dub from history Reprocess with new voice/settings (partially exists via RedubModal)
UC-13 YouTube import Paste URL → process (exists; needs clearer UX + error handling)
UC-14 Custom voice clone Record/upload sample → use in pipeline (API exists; needs guided UX)
UC-15 Guest try-it-now Limited preview on landing without full account (or explicit signup gate)
UC-16 Real-time job updates WebSocket/SSE replacing 5s polling

4.6 Nice-to-have use cases (P2 — growth)

ID Use case
UC-17 Share dubbed video via public link
UC-18 Team/workspace with shared credit pool
UC-19 API keys for programmatic upload
UC-20 Multilingual output beyond Arabic MSA
UC-21 Mobile-optimized PWA with offline viewing of completed jobs
UC-22 Referral program (credits for invites)

4.7 Functional requirements (by domain)

Authentication (FR-AUTH)

ID Requirement Priority
FR-AUTH-01 Email/password signup and login with JWT access + refresh tokens P0 (done)
FR-AUTH-02 Google OAuth 2.0 sign-in and account linking P0
FR-AUTH-03 Password reset via email with time-limited token P0
FR-AUTH-04 Email verification on signup and email change P1
FR-AUTH-05 Enforce resource ownership (users can only access own data) P0
FR-AUTH-06 Protect avatar upload endpoint P0
FR-AUTH-07 Optional: Apple/Microsoft OAuth P2

Billing & credits (FR-BILL)

ID Requirement Priority
FR-BILL-01 Credits balance per user in database P0
FR-BILL-02 Credit cost per output mode (configurable) P0
FR-BILL-03 Deduct credits on successful job completion; refund on failure P0
FR-BILL-04 Free tier: N credits on signup P0
FR-BILL-05 Stripe Checkout for credit packs and subscriptions P0
FR-BILL-06 Stripe webhooks for payment confirmation P0
FR-BILL-07 Usage history and invoices in profile P1

Core dubbing (FR-CORE)

ID Requirement Priority
FR-CORE-01 Upload video, audio, text; YouTube URL import P0 (done)
FR-CORE-02 Four output modes: captions, translation, TTS, full dub P0 (done)
FR-CORE-03 Video trim before processing P0 (done)
FR-CORE-04 Voice selection including custom cloned voices P0 (done)
FR-CORE-05 Job history with filters, preview, download P0 (done)
FR-CORE-06 Reprocess existing media with new settings P0 (done)
FR-CORE-07 Clear error messages per pipeline stage P1

Notifications (FR-NOTIF)

ID Requirement Priority
FR-NOTIF-01 Email on job completion (respects notif_completed) P1
FR-NOTIF-02 Email on low credits (respects notif_credits) P1
FR-NOTIF-03 In-app notification feed P1
FR-NOTIF-04 Browser push (optional, PWA) P2

Onboarding & UX (FR-UX)

ID Requirement Priority
FR-UX-01 First-login onboarding checklist (upload → configure → download) P1
FR-UX-02 Empty states on dashboard recent jobs P1
FR-UX-03 Remove or hide demo-only UI (Google, upgrade buttons) until wired P0
FR-UX-04 Credit cost shown before job submit P0
FR-UX-05 WCAG 2.1 AA baseline (keyboard nav, focus trap, skip link) P1
FR-UX-06 Wire forgot-password route (/forgot-password) P0

4.8 Non-functional requirements

ID Requirement Target
NFR-01 API availability 99.5% uptime (production)
NFR-02 Job status latency <10s perceived update (polling ≤5s or SSE)
NFR-03 Upload limit Documented max file size/duration per plan
NFR-04 Security OWASP top 10; no default SECRET_KEY in prod; HTTPS only
NFR-05 Data privacy GDPR-style account deletion removes S3 objects
NFR-06 i18n EN + AR for all user-facing strings including errors
NFR-07 Mobile Responsive layouts on 375px+ viewports
NFR-08 Observability Job failure alerts in Grafana; user-facing error IDs
NFR-09 Test coverage E2E happy path in CI; frontend CI re-enabled

4.9 Recommended implementation phases

gantt
    title Product Launch Phases
    dateFormat YYYY-MM-DD
    section Phase1_LaunchBlockers
    Fix authz and security           :p1a, 2026-07-01, 2w
    Wire forgot password plus email    :p1b, after p1a, 2w
    Credits model and enforcement    :p1c, after p1a, 3w
    Stripe checkout and webhooks     :p1d, after p1c, 3w
    Google OAuth                     :p1e, after p1a, 2w
    Remove demo UI hide broken flows :p1f, after p1c, 1w
    section Phase2_Engagement
    Onboarding wizard                :p2a, after p1f, 2w
    Email notifications              :p2b, after p1b, 2w
    In app notification center       :p2c, after p2b, 2w
    Doc rewrite onboarding api       :p2d, after p1f, 2w
    section Phase3_Growth
    Real time job updates SSE        :p3a, after p2c, 3w
    Share links and teams            :p3b, after p3a, 4w
Loading

Phase 1 — Launch blockers (P0): Security fixes, OAuth, password reset, credits + Stripe, remove misleading demo UI, wire /forgot-password.

Phase 2 — Engagement (P1): Onboarding, email/in-app notifications, doc overhaul, empty states, a11y pass.

Phase 3 — Growth (P2): SSE/WebSocket, sharing, teams, API keys, multilingual expansion.

4.10 Success metrics (KPIs)

Metric Target (90 days post-launch)
Signup → first job completion ≥ 40%
OAuth vs email signup ratio Track; target ≥ 30% OAuth
Job success rate ≥ 95%
Time to first dubbed video < 20 minutes median
Paid conversion (free → paid) ≥ 5%
D7 retention ≥ 25%
Support tickets per 100 jobs < 5

4.11 Out of scope (v1)

  • Kubernetes / KEDA autoscaling (listed in README future work)
  • Database-per-service (Phase 3 architecture)
  • Live captioning
  • Native mobile apps
  • Gamification / leaderboards

5. Immediate Next Steps

  1. Security hardening — ownership checks, avatar auth, is_active enforcement in backend/app/core/router.py
  2. Hide demo surfaces — Google OAuth button, upgrade/credits CTAs until backend exists
  3. Credits data model — Alembic migration + deduct on job completion
  4. Google OAuth — backend callback route + frontend redirect flow
  5. Doc sprint — rewrite docs/onboarding.md and docs/api.md; deprecate docs/architecture.md
  6. Re-enable frontend CI — move workflow out of disabled-workflows/