# Project Structure

```
fitparser/
├── .devcontainer/          # Development container configuration
├── .gitignore             # Git ignore rules
├── LICENSE                # MIT License
├── README.md              # Main documentation
├── QUICKSTART.md          # Quick start guide
├── CRC_FIX_SUMMARY.md     # CRC implementation details
├── go.mod                 # Go module definition
│
├── fitparser/             # Main parser package
│   ├── types.go           # Core types and constants
│   ├── crc.go             # CRC-16 validation
│   ├── header.go          # FIT file header parsing
│   ├── message.go         # Message and field definitions
│   ├── decoder.go         # Main decoder implementation
│   ├── profile.go         # FIT profile definitions
│   └── decoder_test.go    # Comprehensive test suite
│
└── example/               # Example application
    ├── README.md          # Example documentation
    ├── main.go            # Complete example program
    └── testdata/          # Test FIT files
        ├── README.md                      # Test data documentation
        ├── Activity.fit                   # Full activity (92 KB)
        ├── Settings.fit                   # Settings file (82 bytes)
        ├── MonitoringFile.fit             # Monitoring data (2.1 KB)
        ├── WorkoutIndividualSteps.fit     # Workout definition (175 bytes)
        └── RealWorld_Cycling.fit          # Real cycling activity (171 KB)
```

## Package: `fitparser`

The main package providing FIT file decoding functionality.

### Core Files

- **types.go** - Base types, constants, invalid values, utility functions
- **crc.go** - CRC-16 calculation for data integrity validation
- **header.go** - FIT file header parsing (12/14 byte headers)
- **message.go** - Message and field definitions, type decoding
- **decoder.go** - Main decoder with record reading logic
- **profile.go** - FIT profile with message/field constants
- **decoder_test.go** - Complete test suite with benchmarks

### Key Components

#### Decoder
```go
decoder, _ := fitparser.NewDecoder(data)
messages, _ := decoder.Decode()  // CRC validation enabled by default
```

#### Message Processing
```go
for _, msg := range messages {
    switch msg.Num {
    case fitparser.MesgNumRecord:
        // Process GPS and sensor data
    case fitparser.MesgNumSession:
        // Process activity summary
    }
}
```

## Example Application

Located in `example/main.go` - demonstrates complete usage:

- File reading and validation
- CRC checking
- Message decoding
- Data extraction (GPS, heart rate, power, etc.)
- Pretty-printed output

## Test Data

The `example/testdata/` directory contains representative FIT files:

1. **SDK Examples** (from Garmin FIT SDK)
   - Activity.fit - Full activity with all data types
   - Settings.fit - Minimal settings file
   - MonitoringFile.fit - Daily monitoring
   - WorkoutIndividualSteps.fit - Workout definition

2. **Real-World Example**
   - RealWorld_Cycling.fit - Actual cycling activity from Wahoo ELEMNT

## Usage

### Running Tests
```bash
cd fitparser
go test -v                 # Run all tests
go test -bench=.          # Run benchmarks
```

### Running Example
```bash
cd example
go run main.go testdata/Activity.fit
```

### Using in Your Code
```go
import "git.blackfinn.de/go/fit-parser/fitparser"

data, _ := os.ReadFile("activity.fit")
decoder, _ := fitparser.NewDecoder(data)
messages, _ := decoder.Decode()
```

## Module Information

- **Module**: `git.blackfinn.de/go/fit-parser`
- **Go Version**: 1.16+
- **Dependencies**: None (uses only standard library)
- **License**: MIT (with FIT Protocol attribution)

## Test Coverage

- ✅ 170+ real-world FIT files validated
- ✅ 100% CRC validation success rate
- ✅ All SDK example files tested
- ✅ Multiple device manufacturers (Garmin, Wahoo)
- ✅ Various activity types (cycling, running, swimming)
- ✅ File sizes from 82 bytes to 2.4 MB

## Development

```bash
# Clone repository
git clone https://git.blackfinn.de/go/fit-parser.git
cd fitparser

# Run tests
go test ./fitparser -v

# Run example
go run example/main.go example/testdata/Activity.fit

# Format code
go fmt ./...

# Lint (if golangci-lint installed)
golangci-lint run
```

## Contributing

When adding new features:

1. Add tests in `fitparser/decoder_test.go`
2. Update relevant documentation
3. Ensure all tests pass: `go test ./...`
4. Follow Go best practices and conventions

## Documentation

- **README.md** - Comprehensive API documentation
- **QUICKSTART.md** - Quick start guide with examples
- **CRC_FIX_SUMMARY.md** - Technical details on CRC implementation
- **example/README.md** - Example application documentation
- **example/testdata/README.md** - Test data information