How zineb-kbyla/audio works
Project type and purpose
• This is a CLI-based Node.js/TypeScript utility whose job is to generate audio files for flashcards and quizzes (questions, responses, feedback), upload them to AWS S3, and update a PostgreSQL database with the resulting URLs. It also includes scripts to clear audio files and update story metadata. A Jest test suite covers each of these behaviors using Sinon and axios-mock-adapter.
File structure
• Entry point: src/index.ts
• Command dispatch & argument parsing: src/util/parseArgv.ts
• Scripts folder (src/scripts): one script per feature:
• flashcardsQuestions.ts
• flashcardsResponses.ts
• quizzesQuestions.ts
• quizzesFeedback.ts
• clearAudio.ts
• updateStories.ts
• Utilities (src/util):
• db.ts – manages PostgreSQL connection and CRUD operations
• tts.ts – wraps the ElevenLabs TTS API call
• getTTSParams.ts – builds language-specific TTS parameters using src/enums
• s3.ts – handles AWS S3 uploads and deletes
• sleep.ts – rate-limiting delay helper
• Type definitions: src/interfaces & src/enums
• Configuration: .env, tsconfig.json
• Tests: _tests_/*.test.ts verifying each integration and failure mode
README for architecture hints
• Emphasis on four major interactions:
1. TTS API (ElevenLabs)
2. AWS S3
3. PostgreSQL DB
4. Transaction rollbacks & error handling
Main components and relationships
a. User CLI
• User runs yarn start --script <feature> --level <level>.
• src/index.ts → parseArgv → selects correct script under src/scripts.
b. Script
• Reads questions or feedback from the database (via db.ts).
• For each text item:
• Build TTS parameters (getTTSParams.ts)
• Call ElevenLabs TTS API (tts.ts)
• Receive audio stream/buffer
• Upload to S3 (s3.ts), get back URL
• Update the database record with the S3 URL (db.ts), inside a transaction
• Special scripts like clearAudio.ts or updateStories.ts use S3 deletes or JSON file operations (stories.json).
c. External services
• ElevenLabs API (HTTP REST)
• AWS S3 (SDK calls)
• PostgreSQL (SQL over TCP via a client library)
Important architectural patterns and design principles
• Separation of concerns:
• src/index.ts only dispatches commands
• Each script implements one feature
• Utilities encapsulate third-party integration
• Modularity: clear folder boundaries (scripts vs. util vs. interfaces)
• Robust error handling: each external call has retry or rollback logic
• Testability: utilities are easily mockable (axios-mock-adapter, Sinon)
Final checklist
• Clear component names matching file names (e.g., “FlashcardsQuestions Script”)
• Configuration sources (.env, stories.json) shown as input to the CLI or scripts