FLAC Detective - Project Structure
=====================================

Root Directory (Production Files Only)
---------------------------------------
├── README.md                    # Main project documentation
├── docs/PROJECT_OVERVIEW.md     # Complete project structure guide
├── CHANGELOG.md                 # Version history
├── CONTRIBUTING.md              # Contribution guidelines
├── CODE_OF_CONDUCT.md          # Community standards
├── SECURITY.md                 # Security policy
├── LICENSE                     # MIT License
├── pyproject.toml              # Project configuration
├── Dockerfile                  # Docker image definition
├── docker-compose.yml          # Docker Compose setup
├── Makefile                    # Build automation
└── .pre-commit-config.yaml     # Code quality hooks

Source Code
-----------
src/flac_detective/
├── analysis/                   # Audio analysis engine
│   ├── new_scoring/           # 11-rule scoring system
│   │   ├── rules/             # Individual rule implementations
│   │   ├── calculator.py      # Score orchestration
│   │   └── verdict.py         # Verdict determination
│   ├── spectrum.py            # Spectral analysis
│   └── audio_cache.py         # Audio loading optimization
├── reporting/                 # Report generation
├── repair/                    # FLAC repair functionality
└── main.py                    # CLI entry point

Documentation (Organized by Audience)
--------------------------------------
docs/
├── README.md                  # Documentation index
├── user-guide/               # For end users
│   ├── GETTING_STARTED.md   # Installation & usage
│   ├── EXAMPLES.md          # Usage examples
│   ├── REPORT_FORMAT.md     # Understanding reports
│   └── TROUBLESHOOTING.md   # Common issues
├── technical/               # For researchers & advanced users
│   ├── ARCHITECTURE.md      # System design
│   ├── RULES.md            # Detection rules overview
│   ├── RULE_SPECIFICATIONS.md  # Detailed rule specs
│   ├── LOGIC_FLOW.md       # Analysis workflow
│   └── TECHNICAL_DOCUMENTATION.md
├── reference/               # API documentation
│   ├── API_DOCUMENTATION.md  # Complete API reference
│   └── PYTHON_API_GUIDE.md  # Using as library
├── development/             # For contributors
│   ├── CONTRIBUTING.md     # How to contribute
│   ├── DEVELOPMENT_SETUP.md # Dev environment
│   └── TESTING.md          # Testing guide
├── automation/              # Deployment & automation
│   ├── DOCKER_GUIDE.md     # Docker usage
│   ├── LOGGING_GUIDE.md    # Logging config
│   └── VERSION_MANAGEMENT.md
└── ci-cd/                   # CI/CD & quality
    ├── CI_CD_GUIDE.md      # Pipeline overview
    ├── PRE_COMMIT_SETUP.md # Pre-commit hooks
    ├── CODE_QUALITY_SETUP.md
    ├── COVERAGE_SETUP.md
    ├── RELEASE_GUIDE.md
    └── SECURITY_GUIDE.md

Testing
-------
tests/
├── unit/                    # Unit tests
├── integration/             # Integration tests
└── benchmarks/             # Performance tests

Automation
----------
.github/
├── workflows/              # CI/CD pipelines
│   ├── ci.yml             # Main CI pipeline
│   ├── release.yml        # Automated releases
│   ├── docker.yml         # Docker builds
│   ├── security-scan.yml  # Security scanning
│   └── codeql.yml         # Code analysis
├── ISSUE_TEMPLATE/        # Issue templates
│   ├── bug_report.yml
│   ├── feature_request.yml
│   └── performance_issue.yml
└── PULL_REQUEST_TEMPLATE.md

Scripts
-------
scripts/
├── bump_version.py        # Version management
├── prepare_release.py     # Release preparation
├── coverage_report.py     # Coverage reporting
└── validate_ci.py         # CI validation

Quick Start
-----------
1. Users: Start at docs/user-guide/GETTING_STARTED.md
2. Developers: Start at docs/development/CONTRIBUTING.md
3. API Users: Start at docs/reference/PYTHON_API_GUIDE.md
4. Overview: Read docs/PROJECT_OVERVIEW.md

Key Features
------------
✓ Clean, professional root directory
✓ Organized documentation by audience
✓ Comprehensive CI/CD automation
✓ Docker support for easy deployment
✓ Pre-commit hooks for code quality
✓ Automated releases and changelogs
✓ Security scanning and best practices
✓ 95%+ test coverage

Project Status: Production-Ready ✅
