Update README.md to enhance project documentation and clarify usage instructions

README.md

@@ -6,23 +6,42 @@ A Go client and utility for interacting with the IamResponding (IaR) API, design
 - API client for IaR with keep-alive and alerting support
 - Configurable via YAML and Go structs
 - Modular codebase for easy extension
-- Logging with slog
+- Comprehensive test coverage
+- File system watcher for MP3 files
+- Event-driven architecture with custom event bus
+- Structured logging with slog
+- HTTP client with automatic cookie management
 
 ## Project Structure
 ```
 config.yml                # Example configuration file
+go.mod                    # Go module file
+go.sum                    # Go dependencies checksum
 main.go                   # Entry point
-bus/                      # Event bus logic
+bus/
-client/                   # IaR API client and helpers
+├── bus.go                # Custom event bus implementation
-config/                   # Configuration structs and loading
+└── bus_test.go           # Event bus tests
-utils/                    # Utility functions
+client/
-watcher/                  # File or event watcher logic
+├── client.go             # IaR API client
+├── response.go           # API response structures
+├── request.go            # API request structures
+├── client_test.go        # Basic client tests
+└── client_api_test.go    # API integration tests with mocked responses
+config/
+├── config.go             # Configuration loading and structs
+└── config_test.go        # Configuration tests
+utils/
+├── encoder.go            # MP3 to base64 encoder
+└── encoder_test.go       # Encoder tests
+watcher/
+├── watcher.go            # File system watcher for MP3 files
+└── watcher_test.go       # Watcher tests
 ```
 
 ## Getting Started
 
 ### Prerequisites
-- Go 1.20 or newer
+- Go 1.25 or newer
 - Access to the IamResponding API (credentials required)
 
 ### Installation
@@ -38,7 +57,24 @@ go mod tidy
 ```
 
 ### Configuration
-Edit `config.yml` with your IaR credentials and settings.
+Create a `config.yml` file with your IaR credentials and settings:
+
+```yaml
+credentials:
+  secret_key: "your_secret_key"
+  ttd_api_key: "your_ttd_api_key"
+directory: "/path/to/watch/for/mp3/files"
+watch_debounce_seconds: 5
+logging:
+  level: "INFO"
+```
+
+Configuration options:
+- `credentials.secret_key`: IaR API secret key
+- `credentials.ttd_api_key`: IaR API key
+- `directory`: Directory to watch for MP3 files
+- `watch_debounce_seconds`: Debounce time for file events (default: 1)
+- `logging.level`: Log level (DEBUG, INFO, WARN, ERROR)
 
 ### Usage
 Build and run the main application:
@@ -52,12 +88,48 @@ go build -o iar-notificator main.go
 ./iar-notificator
 ```
 
+The application will:
+1. Load configuration from `config.yml`
+2. Start watching the specified directory for MP3 files
+3. Send keep-alive signals to IaR API at regular intervals
+4. Automatically upload MP3 files as alerts when detected
+
+## API Integration
+The client integrates with the IaR API using GraphQL queries and mutations:
+
+- **KeepAlive**: Retrieves pager group information and maintains connection
+- **PreAlert**: Creates an alert entry
+- **Alert**: Uploads audio data to an existing alert
+
+API responses are parsed and used to populate internal state for subsequent requests.
+
 ## Testing
 Run all tests:
 ```sh
 go test ./...
 ```
 
+Run tests for specific packages:
+```sh
+go test ./client
+go test ./config
+go test ./bus
+go test ./watcher
+go test ./utils
+```
+
+The test suite includes:
+- Unit tests for all core functionality
+- Integration tests with mocked HTTP responses
+- File system watcher tests
+- Configuration loading tests
+- Event bus concurrency tests
+
+## Dependencies
+- `resty.dev/v3`: HTTP client for API requests
+- `github.com/fsnotify/fsnotify`: File system watching
+- `gopkg.in/yaml.v3`: YAML configuration parsing
+
 ## License
 MIT License