# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**Svrnty.GeoManagement** is a .NET 8 library providing abstractions for geocoding and address management services. The solution follows a provider pattern to allow different geocoding service implementations.

## Solution Structure

The solution contains these projects:

- **Svrnty.GeoManagement.Abstractions**: Core abstractions and models for geocoding operations (published to NuGet)
- **Svrnty.GeoManagement.Google**: Google Geocoding API provider implementation (published to NuGet)
- **Svrnty.GeoManagement.Tests**: xUnit integration test project

## Key Architecture Patterns

### Provider Pattern
The library uses the `IGeoManagementProvider` interface to abstract geocoding services. Implementations should provide:
- Forward geocoding (address to coordinates)
- Reverse geocoding (coordinates to address)
- Address normalization

### Address Model
The `Address` record in `Svrnty.GeoManagement.Abstractions/Models/Address.cs` is the central data structure. It:
- Implements `IAddress` interface
- Includes optional `GeoPoint` location data
- Provides formatted address output via `GetFormattedAddress()` method with three format types (Full, Compact, MultiLine)
- Has an `IsNormalized` flag to track address validation status

## Common Commands

### Build
```bash
dotnet build
```

### Run Tests
```bash
dotnet test
```

### Run Specific Test
```bash
dotnet test --filter "FullyQualifiedName~TestNamespace.TestClass.TestMethod"
```

### Restore Dependencies
```bash
dotnet restore
```

## Development Notes

- Target framework: .NET 8
- Nullable reference types are enabled
- The Abstractions project is designed to be provider-agnostic - don't add provider-specific dependencies
- When implementing `IGeoManagementProvider`, all methods support `CancellationToken` for async operations

## NuGet Package Publishing

### Published Packages

- **Svrnty.GeoManagement.Abstractions** - Core interfaces and models
- **Svrnty.GeoManagement.Google** - Google Maps API provider

### Release Process

1. **Ensure all changes are committed and pushed**
2. **Create and push a git tag** with the version number:
   ```bash
   git tag 1.0.0
   git push origin 1.0.0
   ```

3. **Tag format**:
   - Stable releases: `1.0.0`, `1.2.3`
   - Pre-releases: `1.0.0-alpha`, `1.0.0-beta.1`, `1.0.0-rc.2`

4. **Automated workflow** (`.gitea/workflows/publish-nuget.yml`):
   - Triggers on any tag matching version pattern
   - Runs all tests
   - Builds Release configuration
   - Packs both NuGet packages with the tag version
   - Publishes to NuGet.org

### Version Management

- Package versions are automatically set from the git tag
- Default version in `.csproj` files is `0.1.0` (used only for local development)
- CI/CD overrides version with tag value during publish

### Prerequisites

- `NUGET_API_KEY` must be configured as a Gitea repository secret
- Tests must pass for publish to succeed
- Both packages are always published together with the same version

### Local Package Testing

To test package creation locally:
```bash
# Pack with custom version
dotnet pack Svrnty.GeoManagement.Abstractions -c Release -p:Version=1.0.0-test

# Pack Google provider
dotnet pack Svrnty.GeoManagement.Google -c Release -p:Version=1.0.0-test

# View generated packages
ls */bin/Release/*.nupkg
```