jasminb · ZurahidO · Dec 31, 2025
diff --git a/.claude/README.md b/.claude/README.md
@@ -0,0 +1,70 @@
+# Claude Context Directory
+
+This directory contains project-specific context files that provide consistent background information and workflows for Claude Code development sessions.
+
+## Directory Structure
+
+### 📋 `/workflows/`
+Development process and planning documents:
+
+- **`golden_path_workflow.txt`** - Systematic 6-phase development workflow
+  - Feature planning → Test scaffolding → Code generation → Local testing → Critical reassessment → PR preparation
+  - Ensures quality through iterative validation and small diffs
+
+- **`implementation_plan.md`** - JSON Library Abstraction Implementation Plan
+  - Complete roadmap for abstracting Jackson dependencies
+  - 7 epics with detailed work breakdown
+  - Risk assessment and mitigation strategies
+
+### 📚 `/documentation/`
+Comprehensive codebase documentation:
+
+- **`README.md`** - Master overview and architecture summary
+- **`core-converter.md`** - ResourceConverter, ConverterConfiguration, JSONAPIDocument (20 classes)
+- **`annotations.md`** - @Type, @Id, @Relationship and other annotations (8 annotations)
+- **`exceptions.md`** - Custom exception classes and error handling (4 exceptions)
+- **`error-models.md`** - JSON API error object models (4 classes)
+- **`retrofit-integration.md`** - Retrofit framework integration (5 classes)
+
+### 🔍 `/context/`
+Current state analysis and findings:
+
+- **`codebase_analysis.md`** - Assessment of current architecture, Jackson coupling, test coverage, and refactoring roadmap
+
+## Usage Guidelines
+
+### For New Development Sessions
+1. **Review workflows** - Understand the Golden Path process
+2. **Check implementation plan** - Know the current epic/phase status
+3. **Read relevant documentation** - Understand the module being worked on
+4. **Review codebase analysis** - Current state and key findings
+
+### For Refactoring Work
+- Follow **Golden Path workflow phases** systematically
+- Refer to **implementation plan** for strategic guidance
+- Use **documentation** to understand component interactions
+- Check **codebase analysis** for complexity assessments
+
+### For Code Reviews
+- Verify changes align with **implementation plan** goals
+- Ensure **Golden Path quality gates** are met
+- Reference **documentation** for architectural consistency
+
+## Current Project Status
+
+**Phase**: Ready for Golden Path Phase 2 (Test Scaffolding)
+**Test Status**: ✅ All 119 tests passing
+**Next Epic**: Core JSON Abstraction Layer
+**Complexity**: High (extensive Jackson coupling throughout codebase)
+
+## Benefits
+
+This organized context ensures:
+- **Consistent Development Approach** - Same workflow regardless of session
+- **Maintained Context** - No need to re-explain project background
+- **Quality Assurance** - Systematic validation at each step
+- **Documentation Currency** - Always up-to-date project understanding
+
+---
+
+*Maintained as part of JSON API Converter development workflow*
diff --git a/.claude/context/codebase_analysis.md b/.claude/context/codebase_analysis.md
@@ -0,0 +1,82 @@
+# Codebase Analysis Summary
+
+## Project Overview
+**JSON API Converter** - Java library for bidirectional conversion between JSON API documents and Java POJOs.
+
+## Current State Assessment (December 2024)
+- **Version**: 0.16-SNAPSHOT
+- **Java Target**: 1.7 (legacy compatibility)
+- **Build System**: Maven
+- **Primary Dependency**: Jackson 2.15.2 (tightly coupled)
+- **Test Coverage**: 119 tests, all passing ✅
+
+## Architecture Analysis
+### 40 Total Classes in 5 Modules:
+1. **Core Converter** (20 classes) - ResourceConverter, ConverterConfiguration, JSONAPIDocument + utilities
+2. **Annotations** (8 annotations) - @Type, @Id, @Relationship, @Meta, @Links, etc.
+3. **Exceptions** (4 classes) - ResourceParseException, UnregisteredTypeException, etc.
+4. **Error Models** (4 classes) - Error, Errors, Source, Links (JSON API error spec)
+5. **Retrofit Integration** (5 classes) - JSONAPIConverterFactory + adapters
+
+## Jackson Coupling Assessment
+### Heavy Dependencies:
+- `ResourceConverter.java:44` - ObjectMapper, JsonNode throughout
+- `JSONAPIDocument.java:19` - JsonNode for raw response access
+- `ValidationUtils.java` - JsonNode for document validation
+- All JSON tree navigation uses Jackson's JsonNode API
+
+### Abstraction Opportunities:
+- JSON processing operations (read/write/parse)
+- Tree navigation and manipulation
+- Type conversion and object mapping
+- Property naming strategies
+
+## Test Suite Analysis
+### Comprehensive Coverage (119 tests):
+- **ResourceConverterTest** (48 tests) - Core functionality
+- **ValidationUtilsTest** (42 tests) - JSON API spec validation
+- **SerializationTest** (15 tests) - Object → JSON conversion
+- **RetrofitTest** (6 tests) - Framework integration
+- **Edge cases** - ID types, inheritance, error handling
+
+### Test Strategy for Refactoring:
+- ✅ **90% of tests can be preserved** (test public contract, not implementation)
+- 🔄 **10% need adaptation** (Jackson-specific configuration tests)
+- ➕ **New tests needed** (service discovery, cross-library compatibility)
+
+## Refactoring Complexity Assessment
+### High Complexity Areas:
+1. **JSON Tree Navigation** - Extensive JsonNode usage throughout ResourceConverter
+2. **Property Naming** - PropertyNamingStrategy integration
+3. **Type Handling** - Jackson's sophisticated type system
+4. **Configuration Migration** - ObjectMapper settings abstraction
+
+### Low Risk Areas:
+1. **Public API** - Can maintain existing method signatures
+2. **Annotations** - No changes needed
+3. **Error Models** - Pure POJOs, minimal Jackson usage
+4. **Test Models** - Support classes, easily adaptable
+
+## Performance Baseline
+- Need to establish benchmarks before abstraction
+- Current: Direct Jackson calls (optimal performance)
+- Target: <5% performance degradation with abstraction
+
+## Success Criteria for Abstraction
+1. **Zero Breaking Changes** - All existing APIs work unchanged
+2. **Test Compatibility** - All 119 tests pass with each JSON library
+3. **Performance** - <5% degradation from baseline
+4. **Feature Parity** - Jackson, Gson, JSON-B all support core features
+5. **Auto-Discovery** - Zero-config JSON library detection
+
+## Next Steps Priority
+1. **Establish Performance Baseline** - Benchmark current Jackson performance
+2. **Create JsonProcessor Abstraction** - Core interface design
+3. **Implement Jackson Adapter** - Wrap existing ObjectMapper
+4. **Add Service Discovery** - Auto-detection mechanism
+5. **Iterative Migration** - Small diffs with continuous validation
+
+---
+*Analysis Date: December 18, 2024*
+*Test Status: ✅ All 119 tests passing*
+*Ready for: Golden Path Phase 2 (Test Scaffolding)*
diff --git a/.claude/documentation/README.md b/.claude/documentation/README.md
@@ -0,0 +1,164 @@
+# JSON API Converter - Complete Documentation
+
+## Overview
+
+The JSON API Converter is a Java library that provides comprehensive conversion between JSON API specification documents and Java POJOs. This library implements the [JSON API v1.0+ specification](https://jsonapi.org/) and provides features for both serialization and deserialization of JSON API documents.
+
+## Architecture Overview
+
+The library is organized into 5 main modules:
+
+### 1. Core Converter Module (`com.github.jasminb.jsonapi`)
+- **20 classes** - Main conversion engine and document handling
+- Entry point: `ResourceConverter.java:44`
+- Key classes: `ResourceConverter`, `ConverterConfiguration`, `JSONAPIDocument`
+
+### 2. Annotations Module (`com.github.jasminb.jsonapi.annotations`)
+- **8 annotations** - Public API for annotating domain model classes
+- Main annotations: `@Type`, `@Id`, `@Relationship`, `@Meta`, `@Links`
+
+### 3. Exception Handling Module (`com.github.jasminb.jsonapi.exceptions`)
+- **4 exceptions** - Custom exceptions for various error conditions
+- Key exception: `ResourceParseException` (wraps JSON API error responses)
+
+### 4. Error Models Module (`com.github.jasminb.jsonapi.models.errors`)
+- **4 classes** - Models representing JSON API error specification
+- Models: `Error`, `Errors`, `Source`, `Links`
+
+### 5. Retrofit Integration Module (`com.github.jasminb.jsonapi.retrofit`)
+- **5 classes** - Seamless Retrofit framework integration
+- Factory: `JSONAPIConverterFactory` for creating converters
+
+## Key Features
+
+### ✅ Complete JSON API Spec Compliance
+- Resource objects with `type`, `id`/`lid`, `attributes`
+- Relationships with data, links, and meta
+- Top-level `data`, `included`, `meta`, `links`, `errors`, `jsonapi` objects
+- Resource linkage and compound documents
+
+### ✅ Flexible ID Handling
+- String, Integer, Long ID types via `ResourceIdHandler` strategy pattern
+- Local ID (`lid`) support for client-generated identifiers
+- Configurable ID handlers per resource type
+
+### ✅ Relationship Management
+- Lazy loading via `RelationshipResolver` interface
+- Bidirectional relationships with circular reference prevention
+- Configurable serialization/deserialization per relationship
+- Support for `self` and `related` link types
+
+### ✅ Advanced Configuration
+- Jackson ObjectMapper integration with custom naming strategies
+- Per-request serialization settings override global configuration
+- Feature flags for deserialization/serialization behavior
+- Thread-safe resource caching
+
+### ✅ Framework Integration
+- First-class Retrofit support with factory pattern
+- Jackson annotation compatibility
+- Spring Boot friendly
+
+## Quick Start
+
+```java
+// 1. Define resource classes with annotations
+@Type("articles")
+public class Article {
+    @Id
+    private String id;
+
+    private String title;
+
+    @Relationship("author")
+    private Person author;
+}
+
+// 2. Create converter with registered types
+ResourceConverter converter = new ResourceConverter(Article.class, Person.class);
+
+// 3. Deserialize JSON API document
+JSONAPIDocument<Article> document = converter.readDocument(jsonBytes, Article.class);
+Article article = document.get();
+
+// 4. Serialize back to JSON API
+byte[] json = converter.writeDocument(new JSONAPIDocument<>(article));
+```
+
+## Documentation Structure
+
+| Module | File | Description |
+|--------|------|-------------|
+| Core | [core-converter.md](core-converter.md) | Main conversion engine, configuration, document wrapper |
+| Annotations | [annotations.md](annotations.md) | All annotations for marking up domain models |
+| Exceptions | [exceptions.md](exceptions.md) | Error handling and custom exceptions |
+| Error Models | [error-models.md](error-models.md) | JSON API error object models |
+| Retrofit | [retrofit-integration.md](retrofit-integration.md) | Retrofit framework integration |
+
+## Source Code Organization
+
+```
+src/main/java/com/github/jasminb/jsonapi/
+├── ResourceConverter.java              # Main converter class
+├── ConverterConfiguration.java         # Type registration & field mapping
+├── JSONAPIDocument.java               # Document wrapper
+├── annotations/
+│   ├── Type.java                      # @Type - resource type declaration
+│   ├── Id.java                        # @Id - resource identifier
+│   ├── LocalId.java                   # @LocalId - client-generated ID
+│   ├── Relationship.java              # @Relationship - relationship configuration
+│   ├── Meta.java                      # @Meta - meta data fields
+│   ├── Links.java                     # @Links - link fields
+│   ├── RelationshipMeta.java          # @RelationshipMeta - relationship meta
+│   └── RelationshipLinks.java         # @RelationshipLinks - relationship links
+├── exceptions/
+│   ├── DocumentSerializationException.java
+│   ├── InvalidJsonApiResourceException.java
+│   ├── ResourceParseException.java    # Wraps JSON API errors
+│   └── UnregisteredTypeException.java
+├── models/errors/
+│   ├── Error.java                     # Single JSON API error
+│   ├── Errors.java                    # Error collection wrapper
+│   ├── Source.java                    # Error source pointer
+│   └── Links.java                     # Error-specific links
+└── retrofit/
+    ├── JSONAPIConverterFactory.java   # Retrofit converter factory
+    ├── JSONAPIResponseBodyConverter.java
+    ├── JSONAPIDocumentResponseBodyConverter.java
+    ├── JSONAPIRequestBodyConverter.java
+    └── RetrofitType.java
+```
+
+## Configuration Options
+
+### Deserialization Features
+- `REQUIRE_RESOURCE_ID` - Enforce non-empty resource IDs
+- `REQUIRE_LOCAL_RESOURCE_ID` - Enforce non-empty local IDs
+- `ALLOW_UNKNOWN_INCLUSIONS` - Handle unknown types in included section
+- `ALLOW_UNKNOWN_TYPE_IN_RELATIONSHIP` - Handle unknown relationship types
+
+### Serialization Features
+- `INCLUDE_RELATIONSHIP_ATTRIBUTES` - Include relationship objects in `included`
+- `INCLUDE_META` - Include meta information
+- `INCLUDE_LINKS` - Include link objects
+- `INCLUDE_ID` - Include resource IDs
+- `INCLUDE_LOCAL_ID` - Include local IDs
+- `INCLUDE_JSONAPI_OBJECT` - Include top-level JSON API version object
+
+## Thread Safety
+
+The library is designed to be thread-safe:
+- `ResourceConverter` can be shared across threads
+- `ResourceCache` uses `ThreadLocal` storage
+- `ConverterConfiguration` is immutable after initialization
+
+## Performance Considerations
+
+- Use shared `ResourceConverter` instances when possible
+- Resource caching prevents infinite loops in circular relationships
+- Jackson `ObjectMapper` can be customized for performance
+- Lazy relationship loading reduces memory usage
+
+---
+
+*Generated documentation for JSON API Converter v1.x*