Development Guide

This guide covers the complete development workflow for AuthentiVoice, including environment setup, architecture patterns, and best practices for contributing to the codebase.

🚀 Development Environment Setup

Prerequisites

Ensure you have all required tools installed:

Node.js 18+ for frontend development
Python 3.10+ for backend development
Docker for containerized services
ffmpeg for audio processing
Git for version control

Clone and Install

# Clone the repository
git clone https://github.com/authentivoice/authentivoice.git
cd authentivoice

# Install frontend dependencies
cd frontend && npm install

# Install backend dependencies
cd ../backend
pip install uv  # Fast Python package manager
uv sync

Environment Configuration

Create .env files from templates:

# Frontend
cp frontend/.env.example frontend/.env

# Backend
cp backend/.env.example backend/.env

Essential Environment Variables

Frontend (.env):

VITE_SUPABASE_URL - Your Supabase project URL
VITE_SUPABASE_ANON_KEY - Supabase anonymous key
VITE_API_BASE_URL - Backend API URL (default: http://localhost:8006)
VITE_API_KEY - API key for backend authentication
VITE_DEMO_ENABLED - Enable demo mode features
VITE_LOCAL_DEV - Enable local development features

Backend (.env):

GEMINI_API_KEY - Google AI API key for fraud analysis
S3_* - MinIO/S3 configuration for file storage
SUPABASE_* - Supabase service key and URL
API_KEY - Must match frontend API key

Start Development Servers

Use the Makefile for easy startup:

# Terminal 1 - Frontend (http://localhost:5173)
make run-frontend

# Terminal 2 - Backend (http://localhost:8006)
make run-backend

# Terminal 3 - Documentation (http://localhost:3333)
make docs-dev

🏗️ Architecture Overview

Frontend Architecture

frontend/
├── src/
│   ├── components/         # Reusable UI components
│   │   ├── dashboard/     # Dashboard-specific components
│   │   ├── landing/       # Landing page components
│   │   ├── analysis/      # Call analysis components
│   │   ├── review/        # Review system components
│   │   └── ui/           # shadcn-ui base components
│   ├── pages/            # Route-based page components
│   │   ├── Index.tsx     # Landing page
│   │   ├── Dashboard.tsx # Main dashboard
│   │   ├── AnalysisDetail.tsx # Analysis details
│   │   └── Settings/     # Settings pages
│   ├── hooks/            # Custom React hooks
│   │   ├── useAnalyses.ts # Analysis data hooks
│   │   ├── useReviews.ts  # Review system hooks
│   │   └── useIntegrations.ts # Integration hooks
│   ├── lib/              # Utilities and configurations
│   │   ├── api.ts        # API client
│   │   ├── supabase.ts   # Supabase client
│   │   └── utils.ts      # Helper functions
│   ├── types/            # TypeScript definitions
│   │   ├── analysis.ts   # Analysis types
│   │   ├── review.ts     # Review types
│   │   └── integration.ts # Integration types
│   └── integrations/     # Third-party integrations
├── public/               # Static assets
└── supabase/            # Database migrations and types

Backend Architecture

backend/
├── app/
│   ├── api/             # API route handlers
│   │   └── endpoints/   # Endpoint modules
│   │       ├── audio.py # Audio processing
│   │       ├── analysis.py # Analysis endpoints
│   │       ├── review.py # Review endpoints
│   │       └── integrations.py # Integration APIs
│   ├── core/            # Core business logic
│   │   ├── audio_processing/ # Audio manipulation
│   │   ├── transcription/    # Multiple engines
│   │   ├── analysis/         # AI fraud detection
│   │   └── review/          # Review logic
│   ├── services/        # External services
│   │   ├── s3_service.py    # File storage
│   │   ├── supabase_service.py # Database
│   │   ├── ai_service.py    # AI providers
│   │   └── notification_service.py # Alerts
│   ├── models/          # Pydantic models
│   │   ├── audio.py     # Audio models
│   │   ├── analysis.py  # Analysis models
│   │   └── review.py    # Review models
│   └── utils/           # Helper utilities
├── modal/               # Modal cloud deployment
├── tests/              # Test suite
└── alembic/            # Database migrations (if needed)

🛠️ Common Development Tasks

Working with New Features

Our platform has recently added several major features. Here’s how to work with them:

Multi-Reviewer Workflows
PDF Export
Integrations

Backend Implementation:

# app/api/endpoints/review.py
@router.post("/analyses/{analysis_id}/reviews")
async def create_review(
    analysis_id: str,
    review: ReviewCreate,
    current_user: User = Depends(get_current_user)
) -> ReviewResponse:
    # Implement review creation with scoring
    pass

@router.post("/reviews/bulk-assign")
async def bulk_assign_reviews(
    assignments: BulkAssignmentRequest,
    current_user: User = Depends(require_supervisor)
) -> BulkAssignmentResponse:
    # Assign multiple calls to reviewers
    pass

Frontend Implementation:

// hooks/useReviews.ts
export function useCreateReview(analysisId: string) {
  return useMutation({
    mutationFn: (review: ReviewCreate) => 
      createReview(analysisId, review),
    onSuccess: () => {
      queryClient.invalidateQueries(['reviews', analysisId]);
    }
  });
}

Development Patterns

API Client Pattern

All API calls go through a centralized client:

// lib/api.ts
async function request<T>(
  endpoint: string,
  options?: RequestInit
): Promise<T> {
  const token = await supabase.auth.getSession();
  const headers = {
    'Content-Type': 'application/json',
    'X-API-Key': import.meta.env.VITE_API_KEY,
    ...options?.headers,
  };
  
  if (token?.session?.access_token) {
    headers['Authorization'] = `Bearer ${token.session.access_token}`;
  }
  
  const response = await fetch(`${API_BASE_URL}${endpoint}`, {
    ...options,
    headers,
  });
  
  if (!response.ok) {
    throw new APIError(response);
  }
  
  return response.json();
}

React Query Pattern

Use React Query for all data fetching:

// hooks/useAnalyses.ts
export function useAnalyses(filters?: AnalysisFilters) {
  return useQuery({
    queryKey: ['analyses', filters],
    queryFn: () => fetchAnalyses(filters),
    staleTime: 5 * 60 * 1000, // 5 minutes
  });
}

export function useAnalysis(id: string) {
  return useQuery({
    queryKey: ['analysis', id],
    queryFn: () => fetchAnalysis(id),
    enabled: !!id,
  });
}

Error Handling Pattern

Consistent error handling across the app:

// components/ErrorBoundary.tsx
export function QueryErrorBoundary({ children }: Props) {
  return (
    <ErrorBoundary
      fallbackRender={({ error, resetErrorBoundary }) => (
        <Alert variant="destructive">
          <AlertCircle className="h-4 w-4" />
          <AlertTitle>Error</AlertTitle>
          <AlertDescription>
            {error.message}
            <Button onClick={resetErrorBoundary}>Try again</Button>
          </AlertDescription>
        </Alert>
      )}
    >
      {children}
    </ErrorBoundary>
  );
}

🧪 Testing Strategy

Frontend Testing

npm run typecheck

Backend Testing

uv run mypy app

Writing Tests

Frontend Tests
Backend Tests

// __tests__/hooks/useAnalyses.test.ts
import { renderHook, waitFor } from '@testing-library/react';
import { useAnalyses } from '@/hooks/useAnalyses';

describe('useAnalyses', () => {
  it('fetches analyses successfully', async () => {
    const { result } = renderHook(() => useAnalyses());
    
    await waitFor(() => {
      expect(result.current.isSuccess).toBe(true);
    });
    
    expect(result.current.data).toHaveLength(10);
  });
});

🔧 Advanced Development

Performance Optimization

Frontend Performance

Code Splitting:

// Lazy load heavy components
const AnalysisDetail = lazy(() => import('./pages/AnalysisDetail'));
const PDFViewer = lazy(() => import('./components/PDFViewer'));

Memoization:

// Memoize expensive computations
const fraudScore = useMemo(() => 
  calculateFraudScore(analysis), [analysis]
);

// Memoize components
const ExpensiveChart = memo(({ data }) => {
  return <Chart data={data} />;
});

Virtual Scrolling:

// Use virtualization for long lists
import { VirtualList } from '@tanstack/react-virtual';

Backend Performance

Async Processing:

# Use background tasks for heavy operations
from fastapi import BackgroundTasks

@router.post("/analyses")
async def create_analysis(
    file: UploadFile,
    background_tasks: BackgroundTasks
):
    # Quick response
    analysis_id = create_initial_analysis()
    
    # Process in background
    background_tasks.add_task(
        process_audio_analysis,
        analysis_id,
        file
    )
    
    return {"id": analysis_id, "status": "processing"}

Caching:

from functools import lru_cache

@lru_cache(maxsize=100)
def get_ai_prompt(analysis_type: str) -> str:
    # Cache frequently used prompts
    return load_prompt(analysis_type)

Security Best Practices

Always follow these security practices when developing AuthentiVoice features.

Input Validation

# Always validate input
from pydantic import BaseModel, validator

class AudioUpload(BaseModel):
    file_size: int
    file_type: str
    
    @validator('file_size')
    def validate_size(cls, v):
        if v > 100 * 1024 * 1024:  # 100MB
            raise ValueError('File too large')
        return v

Authentication

# Always verify user permissions
from app.core.auth import require_role

@router.delete("/analyses/{id}")
@require_role(["admin", "supervisor"])
async def delete_analysis(id: str):
    # Only admins/supervisors can delete
    pass

Rate Limiting

# Implement rate limiting
from slowapi import Limiter

limiter = Limiter(key_func=get_remote_address)

@router.post("/analyses")
@limiter.limit("10/minute")
async def create_analysis():
    pass

🚀 Deployment

Local Docker Development

# Build and run with docker-compose
docker-compose up --build

# Run specific service
docker-compose up frontend backend

# View logs
docker-compose logs -f backend

Production Build

cd frontend
npm run build
# Output in dist/

📚 Resources & References

React Best Practices

Official React patterns guide

FastAPI Tutorial

Complete FastAPI tutorial

Supabase Guides

Database and auth guides

TypeScript Deep Dive

Advanced TypeScript patterns

Python Async IO

Async programming in Python

shadcn/ui

Component library docs

🤝 Contributing

We welcome contributions! Please:

Fork the repository
Create a feature branch
Make your changes with tests
Submit a pull request

See our Contributing Guide for detailed instructions.

Get Started

User Guide

Features

Architecture

Deployment

🚀 Development Environment Setup

🏗️ Architecture Overview

Frontend Architecture

Backend Architecture

🛠️ Common Development Tasks

Working with New Features

Development Patterns

🧪 Testing Strategy

Frontend Testing

Backend Testing

Writing Tests

🔧 Advanced Development

Performance Optimization

Security Best Practices

🚀 Deployment

Local Docker Development

Production Build

📚 Resources & References

React Best Practices

FastAPI Tutorial

Supabase Guides

TypeScript Deep Dive

Python Async IO

shadcn/ui

🤝 Contributing

Get Started

User Guide

Features

Architecture

Deployment

​🚀 Development Environment Setup

​🏗️ Architecture Overview

​Frontend Architecture

​Backend Architecture

​🛠️ Common Development Tasks

​Working with New Features

​Development Patterns

​🧪 Testing Strategy

​Frontend Testing

​Backend Testing

​Writing Tests

​🔧 Advanced Development

​Performance Optimization

​Security Best Practices

​🚀 Deployment

​Local Docker Development

​Production Build

​📚 Resources & References

React Best Practices

FastAPI Tutorial

Supabase Guides

TypeScript Deep Dive

Python Async IO

shadcn/ui

​🤝 Contributing

🚀 Development Environment Setup

🏗️ Architecture Overview

Frontend Architecture

Backend Architecture

🛠️ Common Development Tasks

Working with New Features

Development Patterns

🧪 Testing Strategy

Frontend Testing

Backend Testing

Writing Tests

🔧 Advanced Development

Performance Optimization

Security Best Practices

🚀 Deployment

Local Docker Development

Production Build

📚 Resources & References

🤝 Contributing