gwutilz/gwencoder/docs/PROJECT_STRUCTURE.md

GWEncoder Project Structure

This document provides a detailed overview of the GWEncoder repository organization.

Directory Structure

gwencoder/
├── cmd/                    # Command-line applications
│   └── gwencoder/          # Main gwencoder application
│       └── main.go         # Entry point with CLI, encoding logic, and workflow
│
├── pkg/                    # Library packages (reusable code)
│   └── encoding/           # Video/audio encoding functionality
│       ├── audio.go        # Audio stream analysis and processing
│       ├── av1.go          # AV1 codec-specific parameters and logic
│       └── streams.go      # Stream reordering, subtitle handling, CC extraction
│
├── docs/                   # Documentation
│   ├── phases/             # Development phase documentation
│   │   ├── PHASE1_COMPLETE.md
│   │   ├── PHASE2_IMPLEMENTATION.md
│   │   ├── PHASE3_COMPLETE.md
│   │   ├── PHASE4_COMPLETE.md
│   │   ├── PHASE5_PROGRESS.md
│   │   ├── PHASE5_SUMMARY.md
│   │   ├── PHASE5_TESTING_PLAN.md
│   │   ├── PHASE6_COMPLETE.md
│   │   ├── PHASE_OVERVIEW.md
│   │   ├── PHASE3_PLAN.md
│   │   ├── PLAN_UPDATES.md
│   │   ├── TEST_RESULTS.md
│   │   └── TEST_RESULTS_PHASE2.md
│   │
│   ├── reference/          # Technical reference documentation
│   │   ├── CODEC_EXTENSIBILITY.md     # Codec system architecture
│   │   ├── DEFAULTS_COMPARISON.md     # Encoding mode comparisons
│   │   ├── DEFAULT_TRANSCODE_BEHAVIOR.md  # Transcoding rules
│   │   └── FLAG_REFERENCE.md          # Complete CLI flag reference
│   │
│   ├── guides/             # User guides and tutorials
│   │   ├── TROUBLESHOOTING.md         # Common issues and solutions
│   │   ├── MISSING_FEATURES.md        # Feature wish list and TODOs
│   │   └── TDARR_MERGE_PLAN.md        # Tdarr integration analysis
│   │
│   └── nextstps.txt        # Development task tracker
│
├── scripts/                # Build and test scripts
│   ├── run_tests.sh                   # Main test runner
│   ├── check_test_progress.sh         # Test progress monitoring
│   ├── phase5_test.sh                 # Comprehensive phase 5 tests
│   ├── phase5_quick_test.sh           # Quick phase 5 tests
│   └── test_combinations.sh           # Encoding combination tests
│
├── tests/                  # Test assets and outputs
│   ├── artifacts/          # Test media files (git-ignored)
│   │   ├── testvid.webm    # Sample test video
│   │   └── .gitkeep
│   │
│   ├── logs/               # Test execution logs (git-ignored)
│   │   ├── test1_output.log
│   │   ├── test2_output.log
│   │   ├── test3_output.log
│   │   ├── test_results.txt
│   │   └── .gitkeep
│   │
│   └── outputs/            # Encoded test outputs (git-ignored)
│       ├── phase5_test_outputs/
│       └── .gitkeep
│
├── integrations/           # External tool integrations
│   └── tdarr/              # Tdarr plugin scripts
│       ├── Tdarr_Plugin_av1_svt_converter.js
│       ├── Tdarr_Plugin_combined_audio_standardizer.js
│       └── Tdarr_Plugin_english_first_streams.js
│
├── logs/                   # Runtime logs and statistics (git-ignored)
│   ├── gwencoder_errors.txt
│   ├── gwencoder_log.txt
│   ├── gwencoder_stats.json
│   └── .gitkeep
│
├── build/                  # Compiled binaries (git-ignored)
│   ├── gwencoder           # Main executable
│   └── .gitkeep
│
├── .archive/               # Archived old versions (git-ignored)
│   ├── gwencoder           # Old binary (v2.x)
│   ├── main                # Old binary
│   └── old-gwcod           # Legacy binary
│
├── .gitignore              # Git ignore rules
├── Makefile                # Build automation
├── go.mod                  # Go module definition
└── README.md               # Main project documentation

File Organization Principles

1. Separation of Concerns

• cmd/: Application entry points only
• pkg/: Reusable library code
• docs/: All documentation grouped by purpose
• scripts/: Executable helper scripts
• tests/: Test data and outputs
• logs/: Runtime artifacts

2. Build Artifacts

• All compiled binaries go in build/
• Git-ignored to keep the repository clean
• Easily cleaned with make clean

3. Documentation Categories

• phases/: Historical development records
• reference/: Technical specifications
• guides/: User-facing documentation

4. Test Organization

• artifacts/: Input test media
• logs/: Execution logs and results
• outputs/: Encoded output files

5. Legacy Code

• Old binaries archived in .archive/
• Git-ignored but preserved for reference
• Separated from active development

Key Files

Source Code

File	Purpose
cmd/gwencoder/main.go	Main application entry point with CLI parsing, encoding orchestration
pkg/encoding/audio.go	Audio stream analysis, codec selection, bitrate calculation
pkg/encoding/av1.go	AV1 encoding parameters, CRF adjustment, quality control
pkg/encoding/streams.go	Stream reordering, subtitle handling, CC extraction

Configuration

File	Purpose
go.mod	Go module definition and dependencies
Makefile	Build automation and common tasks
.gitignore	Git exclusion rules for artifacts and binaries

Documentation

File	Purpose
README.md	Main project documentation and quick start guide
docs/reference/FLAG_REFERENCE.md	Complete CLI flag documentation
docs/guides/TROUBLESHOOTING.md	Common issues and solutions

Build System

The project uses a Makefile for build automation:

make build      # Build the binary
make clean      # Remove build artifacts
make test       # Run tests
make install    # Install to GOPATH/bin
make deps       # Download dependencies
make tidy       # Tidy go.mod
make help       # Show available targets

Import Structure

The main application imports the encoding package:

import (
    "gwencoder/pkg/encoding"
    "gwutils"  // External utility library
)

The gwutils package is a sibling module in the parent directory, referenced via go.mod replace directive.

Git Ignore Strategy

The following are excluded from version control:

• Binaries: build/, .archive/, *.exe, *.so, etc.
• Logs: logs/, tests/logs/, *.log
• Test artifacts: Large media files, encoded outputs
• IDE files: .vscode/, .idea/, *.swp
• Temporary files: tmp/, *.tmp

Empty directories are preserved with .gitkeep files.

Development Workflow

1. Edit source: Modify files in cmd/ or pkg/
2. Build: Run make build
3. Test: Execute scripts in scripts/ directory
4. Document: Update relevant docs in docs/
5. Commit: Only source code and documentation

Migration Notes

This structure was reorganized from the original flat layout to improve:

• Discoverability: Easier to locate files by category
• Maintainability: Clearer separation of concerns
• CI/CD: Standard Go project layout for automated builds
• Documentation: Grouped and categorized for better navigation
• Collaboration: Conventional structure familiar to Go developers

Future Enhancements

Potential improvements to consider:

• Add internal/ package for non-exported code
• Create api/ directory if exposing a library interface
• Add examples/ directory with usage examples
• Consider docker/ directory for container builds
• Add ci/ directory for GitHub Actions or CI/CD configs