Skip to main content

Developer Guide

CODITECT Audio2Text​

This guide will help you set up your development environment and understand the codebase structure.

Prerequisites​

System Requirements​

  • OS: Linux (Ubuntu 20.04+ recommended)
  • Python: 3.8 or higher
  • Node.js: 18.x or higher
  • FFmpeg: 4.4 or higher
  • Git: For version control

Hardware Recommendations​

  • CPU: Multi-core processor (4+ cores recommended)
  • RAM: 8GB minimum, 16GB recommended
  • GPU: Optional but recommended for faster transcription (CUDA-compatible)
  • Storage: 20GB+ free space

Quick Start​

1. Clone the Repository​

git clone <repository-url>
cd coditect-audio2text

2. Setup Development Environment​

# Copy environment template
cp .env.example .env

# Edit .env with your settings
nano .env

# Install all dependencies
make install

3. Run Development Servers​

# Option 1: Using Make (runs both backend and frontend)
make dev

# Option 2: Run separately in different terminals
# Terminal 1 - Backend
cd backend
uvicorn src.main:app --reload

# Terminal 2 - Frontend
cd frontend
npm run dev

4. Access the Application​

Project Structure​

coditect-audio2text/
├── backend/              # FastAPI backend service
│   ├── src/
│   │   ├── api/         # API routes and endpoints
│   │   ├── services/    # Business logic services
│   │   ├── models/      # Data models and schemas
│   │   ├── config/      # Configuration management
│   │   ├── utils/       # Utility functions
│   │   └── main.py      # Application entry point
│   ├── tests/           # Backend tests
│   └── requirements.txt # Python dependencies
│
├── frontend/            # React frontend application
│   ├── src/
│   │   ├── components/  # Reusable UI components
│   │   ├── pages/       # Page components
│   │   ├── services/    # API client services
│   │   ├── styles/      # CSS and theme files
│   │   └── utils/       # Frontend utilities
│   ├── public/          # Static assets
│   └── package.json     # Node dependencies
│
├── core/                # Core processing library
│   ├── src/
│   │   ├── download/    # YouTube download logic
│   │   ├── transcription/ # Whisper transcription
│   │   ├── processing/  # Audio processing
│   │   └── shared/      # Shared utilities
│   └── tests/           # Core library tests
│
├── docs/                # Documentation
│   ├── specs/           # Technical specifications
│   ├── architecture/    # Architecture decisions
│   ├── api/             # API documentation
│   └── guides/          # User and developer guides
│
├── config/              # Configuration files
├── data/                # Data directories (git-ignored)
├── scripts/             # Utility scripts
└── tests/               # Integration tests

Development Workflow​

Backend Development​

Running Tests​

cd backend
pytest tests/ -v
pytest tests/ --cov=src  # With coverage

Code Formatting​

cd backend
black src/
isort src/
flake8 src/
mypy src/

Adding Dependencies​

cd backend
pip install <package>
pip freeze > requirements.txt

Creating a New Endpoint​

  1. Create route in backend/src/api/routes/:
from fastapi import APIRouter

router = APIRouter(prefix="/api/myfeature", tags=["myfeature"])

@router.get("/")
async def my_endpoint():
    return {"message": "Hello"}
  1. Register in backend/src/main.py:
from .api.routes import myfeature
app.include_router(myfeature.router)

Frontend Development​

Running Tests​

cd frontend
npm test
npm run test:coverage

Code Linting​

cd frontend
npm run lint
npm run format

Adding Dependencies​

cd frontend
npm install <package>

Creating a New Component​

// frontend/src/components/MyComponent.tsx
import { FC } from 'react'

interface MyComponentProps {
  title: string
}

const MyComponent: FC<MyComponentProps> = ({ title }) => {
  return <div>{title}</div>
}

export default MyComponent

Common Tasks​

Adding a New Whisper Model Size​

  1. Update backend/src/config/settings.py:
AVAILABLE_MODELS: List[str] = ["tiny", "base", "small", "medium", "large", "custom"]
  1. Update model configs in backend/src/services/transcription_service.py

Implementing New Output Format​

  1. Add format handler in core/src/processing/format_handlers.py
  2. Update TranscriptionService._save_output() method
  3. Add format to AVAILABLE_FORMATS in settings

Adding Authentication​

  1. Install dependencies:
pip install python-jose[cryptography] passlib[bcrypt]
  1. Create auth module in backend/src/api/auth/
  2. Add authentication middleware
  3. Update frontend to handle tokens

Testing​

Unit Tests​

# Backend
cd backend && pytest tests/unit/

# Frontend
cd frontend && npm test

Integration Tests​

pytest tests/integration/

End-to-End Tests​

# TODO: Setup E2E testing with Playwright or Cypress

Debugging​

Backend Debugging​

Enable debug mode in .env:

DEBUG=True
LOG_LEVEL=DEBUG

Use Python debugger:

import pdb; pdb.set_trace()

Frontend Debugging​

Use React DevTools browser extension

Console logging:

console.log('Debug info:', data)

Docker Development​

Build and Run​

make docker-build
make docker-up

View Logs​

make docker-logs
# or
docker-compose logs -f backend

Access Container​

docker exec -it coditect-audio2text-backend bash

Performance Optimization​

Backend​

  • Use async/await for I/O operations
  • Implement caching for expensive operations
  • Profile with cProfile or py-spy
  • Monitor with prometheus metrics

Frontend​

  • Use React.memo for expensive components
  • Implement code splitting with lazy loading
  • Optimize bundle size with webpack analyzer
  • Use service workers for caching

Troubleshooting​

Common Issues​

Issue: Whisper model download fails

# Solution: Set proxy or download manually
export HF_ENDPOINT=https://hf-mirror.com

Issue: FFmpeg not found

# Solution: Install FFmpeg
sudo apt install ffmpeg

Issue: CUDA out of memory

# Solution: Use smaller model or CPU mode
export DEVICE=cpu

Issue: Port already in use

# Solution: Change port in .env or kill process
lsof -ti:8000 | xargs kill -9

Contributing​

Code Style​

  • Python: Follow PEP 8, use Black formatter
  • TypeScript: Follow Airbnb style guide
  • Commits: Use conventional commits format

Pull Request Process​

  1. Fork the repository
  2. Create feature branch (git checkout -b feature/amazing-feature)
  3. Commit changes (git commit -m 'feat: add amazing feature')
  4. Push to branch (git push origin feature/amazing-feature)
  5. Open Pull Request

Commit Message Format​

type(scope): subject

body

footer

Types: feat, fix, docs, style, refactor, test, chore

Resources​

Getting Help​

  • GitHub Issues: Report bugs and request features
  • Discussions: Ask questions and share ideas
  • Documentation: Check docs/ directory

Last Updated: 2025-11-07