How to Build Breakout Buddy

1. Project Overview

Breakout Buddy is a web application designed to record and transcribe audio from virtual meetings and face-to-face group discussions. The app features a retro aesthetic inspired by cassette tape recorders and provides automatic transcription using AI.

Core Functionality

The application provides two distinct recording modes, each optimized for different use cases. Virtual Mode captures audio from online meetings by recording browser tab or system audio, making it ideal for Zoom calls, Google Meets, or any web-based conferencing platform. Face-to-Face Mode uses the device microphone to record in-person group discussions, perfect for breakout sessions, workshops, or team meetings.

Both modes support optional recording names for organization, enforce a twenty-minute maximum recording duration to manage file sizes, and provide automatic transcription powered by Whisper AI. The application includes an admin dashboard where users can view all recordings, access transcripts, and manage their audio library.

Design Philosophy

The visual design embraces a nostalgic retro aesthetic reminiscent of 1980s cassette tape recorders and LCD displays. The interface uses the VT323 monospace pixel font for timer displays, creating an authentic retro-tech feel. The color scheme centers on a vibrant orange (#FF6B00) paired with black, white, and gray tones. Visual elements include a pixelated orange circle logo, cassette tape animations during recording, and subtle glow effects on the LCD timer display to enhance the vintage aesthetic.

2. Architecture and Tech Stack

Frontend Stack

The frontend is built with React 19 using functional components and hooks for state management. Wouter handles client-side routing, providing a lightweight alternative to React Router. Tailwind CSS 4 powers the styling system with custom design tokens, while shadcn/ui provides pre-built accessible UI components. The Lucide React icon library supplies consistent iconography throughout the interface.

Backend Stack

The backend uses Express 4 as the web server framework, with tRPC 11 providing end-to-end type-safe API calls between frontend and backend. Drizzle ORM manages database interactions with full TypeScript support, connecting to a MySQL/TiDB database for persistent storage. Superjson handles serialization, allowing complex data types like Dates to be transmitted seamlessly between client and server.

Audio Processing

Audio recording leverages the MediaRecorder API built into modern browsers, capturing audio streams in WebM format. The AssemblyAI Whisper API performs speech-to-text transcription with high accuracy. AWS S3 stores uploaded audio files with CDN delivery for fast playback access.

Authentication

The application uses OAuth for user authentication, providing secure session management through HTTP-only cookies. Protected routes and API endpoints verify user sessions before granting access to recording and admin features. Most AI development platforms provide built-in OAuth integration that you can enable during project setup.

3. Initial Setup

Step 1: Initialize the Project

When using an AI-powered development platform, start by creating a new web application project with database, server, and user authentication features enabled. Request a project scaffold with the following specifications:

Create a web app called "Breakout Buddy" with: - Database support (MySQL/TiDB) - Backend server (Express + tRPC) - User authentication (OAuth) - React frontend with Tailwind CSS

The platform will generate the initial project structure including configuration files, database setup, authentication flows, and basic routing.

Step 2: Install Additional Dependencies

Add the necessary npm packages for audio recording and file handling:

pnpm add lucide-react

The base template should already include React, Tailwind, tRPC, Drizzle, and authentication libraries.

Step 3: Configure Environment Variables

The platform automatically injects system environment variables for database connections, OAuth credentials, and S3 storage. You do not need to manually configure these unless integrating external services like AssemblyAI for transcription.

For transcription functionality, add your AssemblyAI API key through the platform's secrets management interface:

ASSEMBLYAI_API_KEY=your_api_key_here

4. Database Schema

Recordings Table

Create a database schema file at drizzle/schema.ts with the following structure:

import { mysqlTable, varchar, text, int, timestamp, mysqlEnum } from 'drizzle-orm/mysql-core';

export const recordings = mysqlTable('recordings', {
  id: varchar('id', { length: 36 }).primaryKey(),
  userId: varchar('user_id', { length: 255 }).notNull(),
  userName: varchar('user_name', { length: 255 }).notNull(),
  recordingName: varchar('recording_name', { length: 500 }),
  audioUrl: text('audio_url').notNull(),
  audioKey: varchar('audio_key', { length: 500 }).notNull(),
  duration: int('duration').notNull(), // in seconds
  fileSize: int('file_size').notNull(), // in bytes
  mode: mysqlEnum('mode', ['virtual', 'face-to-face']).notNull(),
  transcriptText: text('transcript_text'),
  transcriptStatus: mysqlEnum('transcript_status', 
    ['pending', 'processing', 'completed', 'failed']).default('pending'),
  createdAt: timestamp('created_at').defaultNow().notNull(),
});

Schema Explanation

The id field uses a UUID string as the primary key for each recording. The userId and userName fields track which user created the recording, populated from the authenticated session. The recordingName field stores an optional user-provided label for the recording.

Audio file references are maintained through audioUrl (the public CDN URL for playback) and audioKey (the S3 storage path). The duration field records the length in seconds, while fileSize captures the file size in bytes for storage management.

The mode enum distinguishes between "virtual" (screen/tab audio) and "face-to-face" (microphone) recording types. Transcription data is stored in transcriptText with a transcriptStatus enum tracking the processing state through pending, processing, completed, or failed stages.

Push Schema to Database

After defining the schema, apply it to the database:

pnpm db:push

5. Core Features Implementation

The core features include virtual mode recording (using navigator.mediaDevices.getDisplayMedia), face-to-face mode recording (using getUserMedia), automatic transcription with AssemblyAI, and an admin dashboard for managing recordings.

Key implementation details include using the MediaRecorder API to capture audio streams, implementing a 20-minute timer with automatic stop, detecting when tab audio is not shared and displaying a warning banner, uploading audio files to S3 storage, and triggering background transcription jobs after upload completes.

6. Design System and Styling

The design system centers on a retro aesthetic with the VT323 pixel font for timer displays, an orange color scheme (#FF6B00), and LCD-style glow effects. Tailwind CSS 4 provides the styling foundation with custom design tokens defined in client/src/index.css.

Key styling patterns include using space-y-6 for consistent vertical spacing, border-2 border-black for bold retro outlines, and custom CSS for the LCD timer glow effect using layered text-shadow properties.

7. User Interface Components

The UI is built with reusable components including a TimerDisplay component with retro LCD styling, a CassetteAnimation component that animates during recording, a HelpDialog component with mode-specific instructions, and navigation buttons that clearly indicate mode switching.

All components use shadcn/ui primitives for accessibility and Lucide React icons for consistent iconography. The design emphasizes clarity and ease of use while maintaining the retro aesthetic throughout.

8. Testing and Quality Assurance

Testing includes unit tests with Vitest for backend logic, manual testing checklists for recording functionality, cross-browser compatibility testing (Chrome, Firefox, Edge, Safari), and verification of transcription accuracy and processing states.

Key test scenarios include verifying the warning banner appears when tab audio is not shared, confirming automatic stop at 20 minutes, testing audio upload and S3 storage, and validating transcript processing through all states (pending, processing, completed, failed).

9. Deployment and Configuration

Before deployment, upload all static assets (images, audio files) to your cloud storage provider (S3 or similar), update the favicon with the pixelated orange circle logo, verify all completed features are marked in todo.md, run tests with pnpm test, and confirm environment variables are configured.

Create a deployment checkpoint through the platform's interface, then use the Publish button to deploy. The platform handles building the production bundle, deploying to hosting infrastructure, configuring SSL certificates, setting up CDN for static assets, and applying database migrations.

For custom domains, navigate to Settings → Domains in the management UI, add your domain, follow DNS configuration instructions, and wait for DNS propagation. SSL certificates are automatically provisioned.

10. Tips and Best Practices

Performance Optimization

Implement lazy loading for components using React's lazy and Suspense, optimize audio file sizes with compression, and implement pagination for the admin dashboard when users have many recordings.

User Experience Enhancements

Add keyboard shortcuts (spacebar to start/stop, ESC to pause), provide toast notifications for user actions, implement auto-save for recording names in localStorage, and ensure all interactive elements have clear visual feedback.

Security Considerations

Validate file sizes on both frontend and backend, implement rate limiting on recording uploads, sanitize all user input to prevent XSS attacks, and always verify ownership before allowing deletion or modification of recordings.

Debugging Tips

Check the browser console for MediaRecorder API errors, monitor dev server logs using terminal commands like tail -f, enable TypeScript strict mode to catch type errors early, and use your platform's built-in logging tools for server-side debugging.

Conclusion

This guide provides a comprehensive blueprint for building Breakout Buddy from scratch using modern web development tools and AI-powered development platforms. The application demonstrates key concepts including browser media APIs, real-time audio processing, cloud storage integration, and AI-powered transcription.

By following these steps and adapting them to your chosen AI development platform, you can create a fully functional audio recording and transcription application with a distinctive retro aesthetic. The modular architecture allows for easy extension with additional features like recording sharing, collaborative transcription editing, or integration with project management tools.

Remember to prioritize user experience, security, and performance throughout the development process, and always test thoroughly before deploying to production.