ivvycode/ivvy-sdk-net

1. Repository purpose

- This is a .NET SDK library, not an application.

- Its job is to wrap the iVvy API v1+ and provide typed models, request/response handling, and platform-extension helpers.

2. Top-level structure

- The main production code lives under src/.

- Unit tests live under tests/.

- Ivvy.API.csproj is the single library project; Ivvy.API.sln ties the library and tests together.

3. Core client layer

- src/ApiClient.cs is the central shared client implementation.

- Module-specific clients in folders like Account, Venue, Crm, Event, Invoice, Contact, Batch, and Test likely build on that shared client.

- The public surface is partitioned by API domain, so callers can work with a focused client per subsystem rather than a single monolith.

4. Domain modules as bounded contexts

- Each folder maps to a major iVvy API area:

- Account: users, subscription groups, custom fields, email/error logs

- Venue: venue, rooms, bookings, packages, rates, taxes, and ARI-related room/rate planning

- Crm: leads, opportunities, tasks, activities, allocation rules

- Event: events, registrations, attendees, invited contacts

- Invoice: invoices, payments, refunds, line items

- Contact: contacts, companies, agents

- Batch: asynchronous batch jobs and progress/result payloads

- Test: a simple ping-style health check

- These are the main architectural boundaries for the SDK.

5. Shared contracts and base abstractions

- IApiClient.cs, IApiClientSerializer.cs, IApiClientDeserializer.cs, and IApiClientEvents.cs define the common seams.

- ApiCallDetails.cs, ApiClientEvents.cs, and the Result* types provide shared infrastructure for API execution, eventing, and response wrapping.

- This keeps module clients thin and consistent.

6. Serialization and JSON handling

- src/Json/ApiClientSerializer.cs and src/Json/ApiClientDeserializer.cs are the main translation layer between .NET objects and API payloads.

- Custom converters handle API-specific formats such as:

- arrays-or-object representations

- ISO date-only values

- ISO time-only values

- response envelope conversion

- This layer is important because it isolates API quirks from the domain models.

7. Response and result model pattern

- The library uses reusable wrappers such as ResultList, ResultObject, ResultSuccess, and ResultOrError.

- Domain-specific response objects exist where the API needs specialized output, such as batch job results or booking operation results.

- This suggests a consistent “API envelope + typed payload” architecture across endpoints.

8. Venue subsystem is the most elaborate

- src/Venue/ is the deepest and most complex area.

- It includes core venue entities plus nested booking models under Venue/Bookings/.

- Booking-related types are split further into:

- booking composition and line items

- room reservations

- taxes, fees, notes, resources, sessions, packages

- operation-specific result objects for add/update/cancel/confirm/remove flows

- This is the main place where the SDK models a rich transactional domain.

9. Platform extensions subsystem

- src/PlatformExtensions/ supports iVvy platform extension workflows rather than normal API consumption.

- It contains installation setup/configure/unsetup request/response models and service abstractions.

- The Installation/Setup area includes verification services, indicating a workflow where the SDK helps validate and coordinate installation state across venue/event extension contexts.

10. Shared primitives and common models

- src/Common/ and top-level utility files provide cross-domain value objects like addresses and simple ID/name/type references.

- Utils.cs likely contains reusable helpers used across clients and models.

- These types reduce duplication and act as shared building blocks for the richer domain objects.

11. Data flow through the SDK

- A consumer calls a module-specific API client.

- That client delegates to the shared client infrastructure.

- Requests are serialized to JSON using the custom serializer and converters.

- Responses are deserialized into typed result wrappers and domain models.

- Error and event details are surfaced through shared response/error types rather than leaking raw transport concerns.

12. Testing boundaries

- tests/ contains unit tests for serialization/deserialization and some domain behaviors, especially booking and platform-extension setup verification.

- The tests focus on the contract boundary of the SDK: converting API payloads correctly and preserving expected model behavior.

- This reinforces that the critical architectural risk here is compatibility with API wire formats.

13. Overall architectural shape

- The repository is a layered SDK:

- transport/client core

- JSON translation layer

- domain-specific API modules

- platform-extension workflow support

- shared result/error primitives

- The main architectural diagram should show one shared client/serialization backbone feeding multiple domain modules, with Venue and Platform Extensions as the most specialized branches.