From abe37cacad19b416ec56d8efd99a35c6e127fb7b Mon Sep 17 00:00:00 2001
From: Guilherme Souza <ogrsouza@gmail.com>
Date: Tue, 4 Nov 2025 09:18:38 -0300
Subject: [PATCH] docs: update CLAUDE.md

---
 CLAUDE.md | 70 +++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 58 insertions(+), 12 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 2c6fd77..8d2e581 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -8,19 +8,29 @@ This is a Swift HTTP client library built upon Apple's SwiftOpenAPIRuntime and O
 
 ## Architecture Overview
 
-The library is structured into two main modules:
+The library is structured as a single module with organized subdirectories:
 
 ### HTTPClient Module
-- **Core Interface**: `Client.swift` - Main HTTP client that orchestrates requests through transport and middleware layers
-- **Transport Layer**: `ClientTransport` protocol abstracts HTTP operations from underlying libraries
-- **Middleware Layer**: `ClientMiddleware` protocol for request/response interception (auth, logging, metrics)
-- **Error Handling**: Structured error types in `Errors/` with `ClientError` and `RuntimeError`
-- **HTTP Types**: Built on Apple's `HTTPTypes` package for request/response modeling
 
-### HTTPClientFoundation Module  
+#### Core Interface (`Interface/`)
+- **Client.swift**: Main HTTP client that orchestrates requests through transport and middleware layers
+- **ClientTransport**: Protocol that abstracts HTTP operations from underlying libraries
+- **ClientMiddleware**: Protocol for request/response interception (auth, logging, metrics)
+- **HTTPBody**: Core body type with streaming support and progress tracking (`HTTPBody+Progress.swift`)
+- **MultipartFormData**: Built-in support for multipart/form-data requests with automatic encoding
+- **CurrencyTypes**: Common types used across the library
+
+#### Foundation Transport (`HTTPClientFoundation/`)
 - **URLSessionTransport**: Foundation-based implementation of `ClientTransport` using URLSession
-- **Streaming Support**: Platform-dependent streaming vs buffered request handling
-- **Buffered Streams**: Custom buffered streaming implementation with lock management
+- **Bidirectional Streaming**: Platform-specific streaming support for request/response bodies
+- **Buffered Streams**: Custom buffered streaming implementation with lock management for platforms without native streaming
+
+#### Error Handling (`Errors/`)
+- Structured error types with `ClientError` and `RuntimeError`
+- Errors include full context (request, response, baseURL)
+
+#### Middlewares (`Middlewares/`)
+- **LoggingMiddleware**: Structured logging integration via swift-log
 
 ## Key Design Patterns
 
@@ -29,6 +39,15 @@ The library is structured into two main modules:
 3. **Platform Adaptation**: Conditional compilation for Darwin vs Linux Foundation differences
 4. **Error Wrapping**: All errors wrapped in `ClientError` with context (request, response, baseURL)
 
+## Platform Support
+
+- iOS 13.0+
+- macOS 10.15+
+- macCatalyst 13.0+
+- watchOS 6.0+
+- tvOS 13.0+
+- Swift 5.10+
+
 ## Development Commands
 
 ### Building
@@ -46,10 +65,17 @@ swift test
 swift test --filter HTTPClientTests
 ```
 
+### CI/CD
+The project uses GitHub Actions for continuous integration:
+- **macOS**: Tests on Xcode 16.4 and 26.0 in both debug and release configurations
+- **Linux**: Builds on Swift 6.2
+- **Integration Tests**: Uses go-httpbin (httpbingo.org) for real HTTP testing
+
 ## Dependencies
 
 - **HTTPTypes** (Apple): Core HTTP request/response types
-- **swift-log** (Apple): Structured logging via `LoggingMiddleware`  
+- **HTTPTypesFoundation** (Apple): Foundation integration for HTTPTypes
+- **swift-log** (Apple): Structured logging via `LoggingMiddleware`
 - **swift-collections** (Apple): `DequeModule` for buffered streaming
 
 ## Testing Framework
@@ -59,9 +85,29 @@ Uses Apple's Swift Testing framework (not XCTest). Test files use:
 - `#expect()` for assertions
 - `@testable import` for internal access
 
+## Key Features
+
+### Multipart Form Data
+Built-in support for `multipart/form-data` requests with:
+- Memory-efficient encoding (< 10 MB in memory, larger files streamed from disk)
+- Automatic MIME type detection for file uploads
+- Convenient builder API via `Client.send(multipartFormData:with:)`
+
+### HTTPBody Progress Tracking
+Monitor upload/download progress through `HTTPBody+Progress.swift` for:
+- Real-time progress updates during streaming operations
+- Integration with progress reporting UIs
+
+### Bidirectional Streaming
+Platform-optimized streaming support:
+- Native streaming on Darwin platforms (iOS, macOS, etc.)
+- Buffered streaming fallback for Linux/other platforms
+- Lock-based synchronization for thread safety
+
 ## Code Conventions
 
-- Apache 2.0 license headers on all source files
+- **License**: Project uses MIT license, though source files retain Apache 2.0 headers from upstream Apple code
 - Platform-specific imports with `#if canImport(Darwin)` blocks
 - `@preconcurrency` imports for Linux Foundation types
-- Sendable conformance throughout for Swift concurrency safety
\ No newline at end of file
+- Sendable conformance throughout for Swift concurrency safety
+- Single module architecture with organized subdirectories
\ No newline at end of file