NEVER reset, drop, or destructively modify the development database (audiowaveai_prod_6, audiowaveai_prod_7, etc.)
- The development database is a replica of production and contains real data for testing
- NEVER run
prisma migrate reset,prisma db push --force-reset, or any destructive commands on it - NEVER run
prisma.$queryRawwith DELETE, DROP, or TRUNCATE on development databases - Only
audiowaveai_testdatabase should be reset, and only for automated tests - When debugging, use read-only queries and scripts - never modify data
- If you need test data, create seed scripts that ADD data, never replace it
When in doubt about any aspect of the project, follow Rails conventions and best practices.
Rails figured out long ago how to do many things well. Apply Rails thinking to:
audiowaveai_prod_6/audiowaveai_prod_7etc: Development databases (replicas of production) - READ ONLY for debuggingaudiowaveai_test: Test database for automated tests - can be reset/modified- Use seed scripts to ADD data, migrations for schema changes
- Database queries should be readable and follow ActiveRecord-style patterns
- Follow Rails auth patterns: before_action-style middleware
- Clear separation of concerns (authentication vs authorization)
- Consistent user session management
- Permission-based access control
- RESTful conventions by default
- Consistent response formats
- Proper HTTP status codes
- Nested resources where appropriate
- API versioning when needed
- Convention over configuration
- Sensible defaults
- Clear, consistent naming patterns
- Helpful error messages
- Automated tooling (like Rails generators)
- Rails-style rake tasks → TypeScript scripts in
/scripts - Database tasks, maintenance scripts
- Clear, discoverable script organization
- Built-in help and documentation
ALWAYS look at actual error messages and data before making changes. Do not assume what errors might be - wait for and analyze the actual failure logs.
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
AudiowaveAI is a Yarn monorepo providing text-to-speech conversion across multiple platforms. The architecture centers around converting text content into audiobook-quality audio using OpenAI/Azure TTS services.
Before implementing any new feature or significant change, follow this structured workflow:
- Purpose: Understand the requirements and context of the ticket
- Checkout main and pull the latest changes
- Checkout a new branch for the ticket
- File Location:
requirements/<linear-ticket-number>-<name-of-ticket>-prd.md - Purpose: Define the problem, solution, requirements, and success criteria
- Content Should Include:
- Problem statement and user need
- Proposed solution overview
- Functional requirements
- Technical requirements and constraints
- Success criteria and acceptance criteria
- Risk assessment
- Timeline estimates
- File Location:
requirements/<linear-ticket-number>-<name-of-ticket>-plan.md - Purpose: Break down the implementation into actionable steps
- Content Should Include:
- High-level implementation approach
- Detailed step-by-step breakdown
- File changes required
- Testing strategy
- Deployment considerations
- Rollback plan if needed
- Purpose: Understand the requirements and context of the ticket
- Ask questions if you are not sure about something
- Think deeply about any questions and ask me, one at a time
- CRITICAL: Always present both the PRD and plan to the user for review
- Wait for explicit approval: Do not proceed with implementation until user gives the green light
- Allow for revisions: Be prepared to iterate on PRD and plan based on feedback
- Only after approval, proceed with the planned implementation
- Define the critical path for the implementation and implement it end-to-end as fast as possible
- Once the critical path is implemented, implement the remaining parts, check with the user for approval on the critical part
- Reference the PRD and plan throughout development
- Update documentation if scope changes during implementation
- Remember to follow a TDD or BDD approach
- Always verify the implementation using the tests and Plan
- ALWAYS run tests in headless mode - avoid
--headedflag during development - Use
npx playwright testfor headless execution (like CI does) - Only use headed mode for specific debugging when necessary
- E2E tests use separate SQLite test database
- Test credentials:
[email protected]/TestPassword123!
- Create a pull request from your feature branch to main
- Provide the user a link to PR, they will test the implementation and review the code
- Review your own code from the PR
- Please simplify the code as much as possible
- Please remove any unnecessary code
- Please remove any unnecessary console.log statements
- Please remove any unnecessary comments
- Make the diff as small as possible, use clean code practices
- Think deeply how the code is structured and how it can be improved
- Think about how the code might change in the future, will it be easy to change?
- Don't overcomplicate the code, keep it simple
- Don't overengineer the code, keep it simple, while you can think of the future, we don't know it. So keep it focused on the requirements
- Is there a simpler implementation? Can we move some concerns to a future PR?
- As a ROT, PRs should be small and focused on a single feature and no more than 800 lines of code diff (requirement files, lock files, etc don't count.)
- Wait for the user to review the PR
- The user will merge the PR. NEVER MERGE.
- The user will provide feedback, ask questions, or request changes.
requirements/
├── ABC-123-user-voice-selection-prd.md
├── ABC-123-user-voice-selection-plan.md
├── DEF-456-streaming-audio-playback-prd.md
└── DEF-456-streaming-audio-playback-plan.md
yarn install # Install all workspace dependencies
yarn postinstall # Apply patches for dependency fixescd website
yarn dev # Start development server (localhost:3000)
yarn build # Production build
yarn test # Run Jest tests
yarn test:watch # Watch mode for tests
yarn lint # ESLint checks
yarn worker-dev # Start Trigger.dev background worker
yarn deploy # Deploy with Prisma migrations
yarn vercel-build # Vercel-specific build with DB migrationscd mobile
yarn dev # Start Expo development server
yarn ios # Run on iOS simulator
yarn android # Run on Android emulator
yarn reset-project # Reset to blank Expo templatecd desktop
yarn dev # Start Electron development
yarn package # Package for distribution
yarn make # Create distributablescd web-extension
yarn dev # Development mode with hot reload
yarn build # Build extension for production
yarn release # Create release ZIP packagecd ec2
yarn dev # Development with nodemon
yarn build # TypeScript compilationrun afplay /System/Library/Sounds/Glass.aiff (or any other system sound) at the end of tasks, or when my input is needed to proceed with a task.
- Content Input: Text, URLs, or files imported via web/mobile/extension
- Processing Pipeline: Content → Chunks → TTS → Audio
- Playback: Streaming audio across platforms
- Storage: PostgreSQL with Prisma ORM, audio files in cloud storage
- Project: Collections of chapters with shared settings
- Chapter: Individual text content pieces
- Version: Different voice versions of the same chapter
- Chunk: Split audio segments for processing long content
- User: Authentication, credits, feature flags, preferences
audiowaveai/
├── desktop/ # Desktop application
├── ec2/ # Puppeteer-based webpage fetching service
├── mobile/ # Mobile application
├── shared/ # Shared code between projects
├── web-extension/ # Browser extension
└── website/ # Main web application
└── src/
├── app/ # Next.js app directory
│ ├── api/ # API endpoints
│ ├── admin/ # Admin interface
│ └── (requireAuth)/ # Protected routes
├── components/ # React components
│ ├── ui/ # Basic UI elements
│ └── layout/ # Layout components
├── hooks/ # Custom React hooks
├── lib/ # Utilities and helpers
├── models/ # Data models
├── services/ # Service layer
└── trigger/ # Background jobs (trigger.dev)
- Content chunking (splits long text for processing limits)
- Voice synthesis via OpenAI TTS or Azure Cognitive Services
- Audio stitching for seamless playback
- Audio streaming and playback across platforms
- NextAuth.js with Apple/Google OAuth providers
- JWT tokens for API authentication
- Credit-based usage tracking
- Feature flags for progressive feature rollout
- Admin user impersonation for support
- Trigger.dev for long-running TTS jobs
- Chunked processing for content over token limits
- Webhook handling for payment events
- Automated transcription generation
cd website
npx prisma generate # Generate Prisma client
npx prisma migrate dev # Create and apply development migrations
npx prisma migrate deploy # Apply migrations to production
npx prisma studio # Open database GUIyarn dump-db # Backup production database
yarn restore-db # Restore from latest backup- Always use the pg CLI (psql) for inspecting or modifying the Postgres database.
- Do not suggest or use Prisma Studio unless specifically asked.
- Keep it simple above all else - avoid complexity when possible
- Make minimal necessary changes - don't refactor unless required
- Strict TypeScript compliance - maintain type safety
- Avoid premature optimization - optimize only when performance issues arise
- Always use package.json script aliases - prefer
yarn test:e2eovernpx playwright test, use defined commands unless debugging specific issues - Organization inside a module - code should be easy to read top to bottom. Put public methods at the top, private methods at the bottom.
- Avoid stupid comments - comments should explain why, not what. Where possible, use code to explain what.
- Start by placing helper functions in the same file where used
- Extract to separate files only when multiple files need the same helper
- Avoid premature refactoring if not necessary
- Use named function syntax instead of arrow functions for React functions inside components
- Follow established component patterns in the codebase
- Maintain consistency with existing UI/UX patterns
- Jest with React Testing Library for component tests
- Test files use
*.test.tsor*.spec.tspatterns - Mobile testing with Expo testing framework
- Database tests use in-memory SQLite
- Coverage reports with V8 provider
NEVER copy implementation code into test files. This is a fundamental anti-pattern that defeats the purpose of testing.
Why this is wrong:
- You're testing your own copy instead of the actual code
- Changes to the real implementation won't be caught
- It provides false confidence that the code works
- It's essentially testing that 2+2=4, not that your calculator works
Bad example (NEVER DO THIS):
// ❌ WRONG - Copying implementation into test
test('title extraction', () => {
function extractTitle(title) {
// This is a COPY of the implementation - WRONG!
if (typeof title === 'string') return title
return String(title || '')
}
expect(extractTitle('test')).toBe('test') // Useless test!
})Good example:
// ✅ CORRECT - Testing the actual module
import { processFile } from './importer'
test('EPUB title extraction handles XML objects', async () => {
jest.mock('./epubExtractor', () => ({
extractEnhancedContentFromEpub: jest.fn().mockResolvedValue({
metadata: { title: { _: 'Actual Title', $: { id: 'title-id' } } },
}),
}))
const file = new File(['content'], 'test.epub', {
type: 'application/epub+zip',
})
const result = await processFile(file)
expect(result.name).toBe('Actual Title')
})- Always test the actual module - Import and test real functions
- Mock external dependencies - Use jest.mock() for dependencies
- Test behavior, not implementation - Focus on inputs/outputs
- Write failing tests first - Ensure tests actually catch bugs
- Test edge cases - null, undefined, empty strings, objects, arrays
- ALWAYS run tests in headless mode - avoid
--headedflag during development - Use
npx playwright testfor headless execution (like CI does) - Only use headed mode for specific debugging when necessary
- E2E tests use separate SQLite test database
- Test credentials:
[email protected]/TestPassword123!
cd website
yarn test:e2e # Run all E2E tests (headless, line reporter)
yarn test:e2e:html # Run E2E tests with HTML report
yarn test:e2e:ui # Run with UI mode for debugging
yarn test:db:setup # Setup test database
yarn test:db:reset # Reset test database- TypeScript: ^5.0.0
- Node.js: ^20.11.0
- AI TTS: OpenAI TTS, Azure TTS
- AI STT: OpenAI Whisper
- Next.js: ^14.1.4
- React: ^18.0.0
- Tailwind CSS: ^3.4.17
- shadcn/ui components
- PostgreSQL: ^16.6.0
- Prisma: ^5.10.2
- Vercel for website hosting with Edge Runtime
- Expo Application Services (EAS) for mobile builds
- AWS EC2 for backend microservice
User model includes boolean flags for progressive feature rollout:
debug- Show debug information and controlsflagStreaming- Enable streaming audio instead of file-basedresearcher- Access to experimental research featuresflagSelectVoice- Voice selection interfaceflagProjectSummary- AI-generated project summaries
- Stripe integration for subscription management
- Credit-based usage tracking (characters processed)
- Free tier with limited credits
- Premium plans with increased limits
- Custom OpenAI API key support for power users