trax/PROJECT-DIRECTORY.md

Project Directory Structure

This document provides an overview of the Trax Media Processing Platform directory structure and the purpose of each component.

Root Directory

trax/
├── CLAUDE.md                    # Project context for Claude Code
├── AGENTS.md                    # Development rules for AI agents
├── EXECUTIVE-SUMMARY.md         # High-level project overview
├── CHANGELOG.md                 # Version history and changes
├── PROJECT-DIRECTORY.md         # This file - directory structure
├── README.md                    # Project introduction and quick start
├── pyproject.toml              # Project configuration and dependencies
├── requirements.txt            # Locked dependencies (generated)
├── scratchpad.md               # Temporary notes and ideas
└── test_config.py              # Configuration testing utilities

Source Code (src/)

src/
├── __init__.py                 # Python package initialization
├── config.py                   # Centralized configuration system
├── main.py                     # Application entry point
├── cli/                        # Command-line interface
│   ├── __init__.py
│   └── main.py                 # Click-based CLI implementation
├── services/                   # Business logic services
│   ├── __init__.py
│   ├── transcription/          # Transcription services
│   │   ├── __init__.py
│   │   ├── protocols.py        # Service interfaces
│   │   ├── whisper_service.py  # Whisper implementation
│   │   └── enhancement.py      # AI enhancement service
│   ├── caching/                # Caching layer
│   │   ├── __init__.py
│   │   ├── protocols.py        # Cache interfaces
│   │   └── sqlite_cache.py     # SQLite cache implementation
│   ├── batch/                  # Batch processing
│   │   ├── __init__.py
│   │   ├── processor.py        # Batch job processor
│   │   └── queue.py            # Job queue management
│   └── export/                 # Export functionality
│       ├── __init__.py
│       ├── protocols.py        # Export interfaces
│       ├── json_exporter.py    # JSON export
│       └── txt_exporter.py     # Text export
├── models/                     # Database models
│   ├── __init__.py
│   ├── base.py                 # Base model class
│   ├── media.py                # Media file models
│   ├── transcript.py           # Transcript models
│   └── batch.py                # Batch job models
├── database/                   # Database layer
│   ├── __init__.py
│   ├── registry.py             # Database registry pattern
│   ├── connection.py           # Connection management
│   └── migrations/             # Alembic migrations
├── utils/                      # Utility functions
│   ├── __init__.py
│   ├── audio.py                # Audio processing utilities
│   ├── validation.py           # Input validation
│   └── logging.py              # Logging configuration
└── agents/                     # AI agent components
    ├── __init__.py
    └── rules/                  # Agent rule files
        ├── TRANSCRIPTION_RULES.md
        ├── BATCH_PROCESSING_RULES.md
        ├── DATABASE_RULES.md
        ├── CACHING_RULES.md
        └── EXPORT_RULES.md

Documentation (docs/)

docs/
├── architecture/               # Architecture documentation
│   ├── development-patterns.md # Historical learnings and patterns
│   ├── audio-processing.md     # Audio pipeline architecture
│   └── iterative-pipeline.md   # Version progression details
├── reports/                    # Analysis reports
│   ├── 01-repository-inventory.md
│   ├── 02-historical-context.md
│   ├── 03-architecture-design.md
│   ├── 04-team-structure.md
│   ├── 05-technical-migration.md
│   └── 06-product-vision.md
└── team/                       # Team documentation
    └── job-descriptions.md     # Role definitions

Tests (tests/)

tests/
├── __init__.py                 # Test package initialization
├── conftest.py                 # Pytest configuration and fixtures
├── factories/                  # Test data factories
│   ├── __init__.py
│   ├── media_factory.py        # Media file factories
│   ├── transcript_factory.py   # Transcript factories
│   └── batch_factory.py        # Batch job factories
├── fixtures/                   # Test fixtures and data
│   ├── audio/                  # Test audio files
│   │   ├── sample_5s.wav       # 5-second test file
│   │   ├── sample_30s.mp3      # 30-second test file
│   │   └── sample_2m.mp4       # 2-minute test file
│   └── transcripts/            # Expected transcript outputs
│       └── expected_outputs.json
├── unit/                       # Unit tests
│   ├── test_protocols.py       # Protocol interface tests
│   ├── test_models.py          # Database model tests
│   └── services/               # Service unit tests
│       ├── test_batch.py       # Batch service tests
│       └── test_whisper.py     # Whisper service tests
└── integration/                # Integration tests
    ├── test_pipeline_v1.py     # v1 pipeline tests
    ├── test_batch_processing.py # Batch processing tests
    └── test_cli.py             # CLI integration tests

Data (data/)

data/
├── media/                      # Media file storage
│   ├── downloads/              # Downloaded media files
│   └── processed/              # Processed audio files
├── exports/                    # Export output files
│   ├── json/                   # JSON export files
│   └── txt/                    # Text export files
└── cache/                      # Cache storage
    ├── embeddings/             # Embedding cache
    ├── transcripts/            # Transcript cache
    └── analysis/               # Analysis cache

Scripts (scripts/)

scripts/
├── setup_dev.sh               # Development environment setup
├── setup_db.sh                # Database initialization
├── run_tests.sh               # Test execution script
└── deploy.sh                  # Deployment script

Configuration Files

pyproject.toml

• Project metadata and dependencies
• uv package manager configuration
• Development tools configuration (Black, Ruff, MyPy)
• Build system settings

.env (inherited from root)

• API keys and secrets
• Database connection strings
• Service configuration
• Environment-specific settings

alembic.ini

• Database migration configuration
• Alembic settings and paths

Key File Purposes

Core Documentation

• CLAUDE.md: Context for Claude Code to understand current state
• AGENTS.md: Development rules and workflows for AI agents
• EXECUTIVE-SUMMARY.md: High-level project overview and strategy
• CHANGELOG.md: Version history and change tracking
• PROJECT-DIRECTORY.md: This file - directory structure overview

Configuration

• src/config.py: Centralized configuration with root .env inheritance
• pyproject.toml: Project dependencies and tooling configuration
• requirements.txt: Locked dependency versions (generated)

Architecture

• docs/architecture/: Detailed architecture patterns and decisions
• docs/reports/: Analysis reports from YouTube Summarizer project
• src/agents/rules/: Agent rule files for consistency

Testing

• tests/fixtures/audio/: Real audio files for testing (no mocks)
• tests/conftest.py: Pytest configuration and shared fixtures
• tests/factories/: Test data generation utilities

Development Workflow

File Organization Principles

1. Separation of Concerns: Each directory has a specific purpose
2. Protocol-Based Design: Interfaces defined in protocols.py files
3. Real Files Testing: Actual media files in test fixtures
4. Documentation Limits: Keep files under 600 LOC for AI comprehension
5. Clear Naming: Descriptive file and directory names

Adding New Components

1. Services: Add to src/services/ with protocol interface
2. Models: Add to src/models/ with database registry
3. Tests: Add to tests/ with real file fixtures
4. Documentation: Add to docs/ with clear structure
5. Rules: Add to src/agents/rules/ for consistency

Migration Strategy

• Database Changes: Use Alembic migrations in src/database/migrations/
• Schema Updates: Update models and create migration
• Data Migration: Scripts in scripts/ directory
• Version Tracking: Update CHANGELOG.md with changes

---

Last Updated: 2024-12-19 Project Structure Version: 1.0