Skip to main content

Epic 1 - TTS Submission and Get Link

Objective​

Deliver a complete text-to-speech platform with client submission system, admin backoffice, and public playback functionality.

Core Flow:

Text Submission → Admin Processing → Manual Audio Upload → Shareable Link

What Users Get:

  • Submit text requests with voice selection
  • Audio file (MP3) stored in S3 and accessible via URL
  • Unique playback URL (e.g., micdots.com/play/happy-birthday-john)
  • Request tracking and history
  • Email notifications (3 emails: confirmation + processing + completion)

What Admins Get:

  • Dashboard displaying all client requests (with filtering and sorting)
  • Status update controls (pending → processing → completed)
  • Manual audio upload capability via pre-signed S3 URLs
  • Request monitoring (analytics deferred to Epic 2)
Manual Processing Workflow

Epic 1 follows a manual admin-driven workflow. Users submit text requests and admins manually process them by obtaining audio files externally and uploading them to the system.

Priorities Covered​

  • P1: Manual Text-to-Speech Processing with Admin Upload
  • P2: Voice Gallery (Read-only voice selection)
  • P3: Shareable Audio Playback Links (Slug-based URLs)
  • P4: User Authentication and Authorization (JWT-based, role-based access)
  • P5: S3 Audio Storage with Pre-signed URLs
  • P6: Request Management System (Client and Admin views)
  • P7: Email Notification System (Status change triggers)
  • P8: Admin Backoffice Dashboard (displays request list with filtering/sorting)

Sample Pages & Flow​

View the complete user and admin flows with visual mockups:

Client-Facing Pages​

Admin Backoffice Pages​

Dashboard = Request List

In Epic 1, the "Dashboard" IS the request list page. There is no separate requests page. The dashboard shows all client requests with filtering, sorting, and status updates. Advanced analytics and stats cards are deferred to Epic 2.

Workflow Overview​

For detailed step-by-step workflow with sequence diagrams and email flows, see Epic 1 - User Flow.

Client Workflow​

Account Setup

Client accounts are created manually by developers. Clients receive their login credentials (email/password) from developers before they can access the system.

  1. Client visits site → Landing page (public access)
  2. Client browses voices → Voice gallery with previews (no login required)
  3. Client logs in → Email/password authentication (credentials provided by developers)
  4. Client enters text → Submission form (max 1000 characters)
  5. Client selects voice → Choose from voice gallery
  6. Client submits → Click "Submit Request"
  7. System creates request → Request saved (status: pending)
  8. System sends email → Confirmation email sent to client
  9. Client waits → Admin processes request manually (1-24 hours)
  10. Client receives email → Processing email when admin starts
  11. Admin completes request → Uploads audio file, status changes to completed
  12. Client receives email → Completion email with playback link
  13. Client accesses audio → Click playback link from email or request details
  14. Client shares link → Send to recipients via any channel

Admin Workflow​

  1. Admin logs in → Backoffice authentication (separate from client)
  2. Admin views dashboard → Dashboard displays full request list with filtering and sorting
  3. Admin selects request → Click request from dashboard list to view details
  4. Admin updates status → Change status to "processing" (triggers processing email)
  5. Admin generates audio → Obtain audio file externally (outside system)
  6. Admin uploads audio → Upload MP3 file to system via pre-signed S3 URL
  7. System processes upload → Upload to S3, update status to "completed"
  8. System sends email → Completion email sent to client with playback link

Key Features​

For Clients​

  • ✅ Browse voice gallery with voice previews (no login required)
  • ✅ Login with email/password authentication (required for submission)
  • ✅ Submit text requests (up to 1000 characters)
  • ✅ View all personal requests with status tracking
  • ✅ Receive email notifications (3 emails: confirmation when submitted + processing when admin starts + completion when audio is ready)
  • ✅ Access individual request details with audio player
  • ✅ Download audio file (MP3 format)
  • ✅ Get shareable playback URL (slug-based)
  • ✅ Pagination for request history

For Admins​

  • ✅ Separate admin authentication
  • ✅ Dashboard displaying all client requests (statistics deferred to Epic 2)
  • ✅ View all client requests across all users with filtering and sorting
  • ✅ Update request status (pending → processing → completed)
  • ✅ Upload audio files manually via pre-signed S3 URLs
  • ✅ Monitor request activity and status changes
  • ✅ Email notification triggers (confirmation + processing + completion)

Technical Features​

  • ✅ Manual audio processing workflow
  • ✅ AWS S3 storage with pre-signed URLs
  • ✅ Unique slug generation for shareable URLs
  • ✅ JWT-based authentication with role-based access (admin/client roles)
  • ✅ Email notification system (SMTP/SendGrid/AWS SES)
  • ✅ RESTful API endpoints
  • ✅ Admin audio upload functionality
  • ✅ Public playback page (no authentication required)

Technical Details​

Data Storage​

Each TTS submission stores:

  • ID: Unique identifier (UUID)
  • Client ID: Authenticated user who created submission
  • Text: Original text input (up to 1000 chars)
  • Voice ID: Selected voice from gallery
  • Status: pending, processing, completed (Epic 1) | failed (MVP 2)
  • Audio URL: S3 link to MP3 file
  • Slug: URL-friendly identifier (e.g., happy-birthday-john-1706882400)
  • Character Count: Number of characters in text
  • Processing Time: Time taken to process (admin processing + upload time)
  • Created At: Submission timestamp
  • Updated At: Last status update timestamp
  • Created By: User ID and name from JWT token

Example Playback URL: https://micdots.com/play/happy-birthday-john-1706882400

Status Flow​

pending → processing → completed

Status Definitions:

  • pending: Request received, waiting for admin to process
  • processing: Admin is working on the request (generating/obtaining audio externally)
  • completed: Audio uploaded by admin and stored in S3
Failed Status

The failed status and error handling workflow will be implemented in MVP 2.

Email Notifications Sent On:

  • Request submitted (status: pending) - Confirmation email
  • Status change to processing - Processing notification
  • Status change to completed - Audio ready with playback link

Complete User Flow​

For detailed step-by-step workflow including sequence diagrams and email flows, see:

Epic 1 - User Flow - Complete client and admin journey with detailed diagrams

Read-Only Voice Gallery

The voice gallery is publicly accessible (no authentication required). Users can view and select voices for their TTS submissions.

Public Access:

  • ✅ View all published voices (GET /api/v1/voice-gallery)
  • ✅ Listen to voice samples
  • ✅ No login required to browse voices
  • ✅ Select voice for TTS submission (login required for submission)

Voice Management:

Email Notification System​

Automated Email Notifications

Epic 1 includes an automated email notification system that sends emails to clients when request status changes.

Email Triggers:

  • Request submitted (status: pending) - Confirmation email
  • Processing started (status: processing) - Processing notification
  • Audio ready (status: completed) - Completion email with playback link

Email Content:

  • Request ID and status
  • Text preview
  • Voice selection
  • Shareable playback link (when completed)
  • Call-to-action button

Technical Implementation:

Access Management​

Role-Based Access Control​

Account Management in Epic 1
  • Client accounts: Must be created manually by developers (no self-service registration)
  • Password resets: Must be handled manually by developers (no self-service reset)
  • Admin accounts: Created and managed by developers

Self-service registration and password reset flows are deferred to MVP 2.

Client Role:

  • Login with email/password authentication (required for submission)
  • Create TTS submissions
  • View own submissions only
  • Access audio files via shareable links
  • Receive email notifications (confirmation + processing)

Admin Role:

  • Separate admin login
  • View all client requests
  • Update request status
  • Upload audio files manually
  • Access backoffice dashboard
  • Monitor system activity

Public Access​

No Authentication Required:

  • Audio playback via shareable link (/play/{slug})
  • Voice gallery access (GET all published voices)
  • Anyone with the link can listen to audio
  • No user data exposed on public pages

Backoffice Features​

Admin Dashboard (Epic 1)​

Dashboard = Request List in Epic 1

In Epic 1, the dashboard IS the request management page. It displays the full list of all client requests with filtering, sorting, and pagination. Stats and analytics cards are deferred to Epic 2.

Epic 1 Dashboard Features:

  • Display all client requests in a table/list view
  • Filter by status (pending, processing, completed)
  • Sort by date, status, client
  • Search by request ID, text content, or client
  • Pagination for large request lists
  • Click any request to view details and manage
  • Quick status update actions

Request Management (From Dashboard)​

  • View request details by clicking from dashboard list
  • Update status manually (pending → processing → completed)
  • Upload audio files for manual processing via pre-signed S3 URLs
  • View client information
  • View text content and voice selection
  • Monitor processing status

Deferred to Epic 2:

  • Stats cards (total requests, pending count, completed today, etc.)
  • Trend indicators and analytics
  • Recent activity feed
  • Dashboard widgets
  • Fixed header with admin info
  • Collapsible sidebar navigation
  • Main content area
  • System status indicator
  • Footer with branding

Testing Strategy​

Manual Testing:

  • ✅ Manual testing with real audio files
  • ✅ Manual QA verification before production
  • ✅ Email notification testing
  • ✅ Audio upload and playback testing

Automated Testing:

  • ❌ No automated tests in Epic 1
  • Deferred to future releases for rapid MVP delivery

Success Criteria​

Epic 1 is complete when:

Client Journey​

  1. ✅ Client can browse voice gallery (no login required)
  2. ✅ Client can log in with email/password
  3. ✅ Client can submit text request with voice selection
  4. ✅ Client receives confirmation email (pending status)
  5. ✅ Client can view all personal requests with status
  6. ✅ Client receives processing email when admin starts
  7. ✅ Client checks "My Requests" to see completion status (no completion email in Epic 1)
  8. ✅ Client can play audio on request details page
  9. ✅ Client can access public playback page via ID
  10. ✅ Client can download audio file (MP3)

Admin Journey​

  1. ✅ Admin can log in to backoffice
  2. ✅ Admin can view dashboard displaying all client requests (stats deferred to Epic 2)
  3. ✅ Admin can filter, sort, and search requests from dashboard
  4. ✅ Admin can click any request to view details
  5. ✅ Admin can update request status to "processing" (triggers processing email)
  6. ✅ Admin can generate/obtain audio files externally
  7. ✅ Admin can upload audio files to system via pre-signed S3 URLs
  8. ✅ System uploads audio to S3 automatically
  9. ✅ Status updates trigger email notifications (confirmation + processing only in Epic 1)

Technical Requirements​

  1. ✅ Manual audio processing workflow functional
  2. ✅ Audio files uploaded to S3 with pre-signed URLs
  3. ✅ Unique slug generation functioning
  4. ✅ Public playback page accessible
  5. ✅ JWT authentication with role-based access
  6. ✅ Email notification system operational
  7. ✅ Manual testing completed
  8. ✅ Deployed to production

Timeline​

Duration: 6 weeks

PhaseFocusDeliverables
1Authentication & VoiceJWT auth, login, role-based access, voice gallery
2Request ManagementRequest submission, status tracking, admin backoffice
3Admin Processing & StorageAdmin audio upload, S3 storage, slug generation
4Email & PlaybackEmail notifications, public playback page, status workflow
5Testing & DeployManual QA, error handling, production deployment

Known Limitations​

Epic 1 Limitations

The following limitations are accepted for Epic 1:

User Experience​

  • No self-service registration: Client accounts must be created manually by developers (self-service registration in MVP 2)
  • No password reset flow: Password resets must be handled manually by developers (self-service password reset in MVP 2)
  • Character limit: Maximum 1000 characters per submission
  • Basic filtering: Limited filter options in "My Requests"
  • Manual processing: Admins manually process requests (1-24 hour wait time)
  • Automated email notifications: Users receive 3 emails (confirmation + processing + completion)

Admin Experience​

  • Dashboard displays request list only: Stats cards, analytics, and widgets deferred to Epic 2
  • Basic dashboard: Dashboard IS the request management page (no separate pages)

Technical​

  • Manual audio processing: Admins obtain audio files externally (no API integration)
  • No automatic audio generation: Deferred to future releases
  • No failed status: Error handling and failed status deferred to MVP 2
  • Basic error handling: Advanced error recovery deferred to MVP 2
  • No rate limiting: Accept risk for MVP
  • No monitoring/logging: Basic error logging only

Development​

  • No automated tests: Manual testing only

Action Items: These limitations should be reviewed and addressed in future epics.

Technical Documentation​

Authentication & User Management​

Text-to-Speech System​

Email Notification System​

User Flow​

  • User Flow - Complete client and admin journey

Sample Pages​

System Architecture​