dotnet-geo-management/CLAUDE.md

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

dotnet build

Run Tests

dotnet test

Run Specific Test

dotnet test --filter "FullyQualifiedName~TestNamespace.TestClass.TestMethod"

Restore Dependencies

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:

   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:

# 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