# ivvycode/ivvy-sdk-net architecture

> Architecture diagram of the GitHub repository ivvycode/ivvy-sdk-net, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ivvycode/ivvy-sdk-net
- Repository: https://github.com/ivvycode/ivvy-sdk-net

## Overview

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.

Main entry points: [`src/ApiClient.cs`](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/ApiClient.cs) (Api client), [`src/Json/ApiClientSerializer.cs`](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Json/ApiClientSerializer.cs) (JSON layer), [`src/PlatformExtensions/PlatformExtension.cs`](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/PlatformExtensions/PlatformExtension.cs) (Platform ext), [`src/Json/ApiClientDeserializer.cs`](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Json/ApiClientDeserializer.cs) (JSON decode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_src["src"]
  node_library["iVvy SDK<br/>.NET library<br/>[Ivvy.API.csproj]"]
  node_shared_client["Api client<br/>core client<br/>[ApiClient.cs]"]
  node_client_contracts["Client seams<br/>interfaces<br/>[IApiClient.cs]"]
  node_api_events["Api events<br/>[ApiClientEvents.cs]"]
  node_json_layer["JSON layer<br/>serializer"]
  node_json_deser["JSON decode<br/>deserializer"]
  node_converters["Converters"]
  node_results["Result wrappers<br/>response models<br/>[ResultObject.cs]"]
  node_common["Common types<br/>shared models<br/>[Address.cs]"]
  node_account["Account<br/>api module<br/>[ApiClient.cs]"]
  node_contact["Contact<br/>api module<br/>[ApiClient.cs]"]
  node_crm["CRM<br/>api module<br/>[ApiClient.cs]"]
  node_event["Event<br/>api module<br/>[ApiClient.cs]"]
  node_invoice["Invoice<br/>api module<br/>[ApiClient.cs]"]
  node_batch["Batch<br/>api module<br/>[ApiClient.cs]"]
  node_test["Test<br/>api module<br/>[ApiClient.cs]"]
  node_venue["Venue<br/>api module<br/>[ApiClient.cs]"]
  node_venue_bookings["Booking models<br/>booking domain<br/>[RoomReservation.cs]"]
  node_platform_ext["Platform ext<br/>workflow support"]
  node_platform_setup["Setup flow<br/>workflow services"]
  node_platform_config["Configure flow<br/>workflow models"]
  node_platform_unsetup["Unsetup flow<br/>workflow models<br/>[UnsetupRequest.cs]"]
end

subgraph group_tests["tests"]
  node_serializer_tests["Serializer tests<br/>unit tests"]
  node_deserializer_tests["Deserializer tests<br/>unit tests"]
  node_booking_tests["Booking tests<br/>unit tests<br/>[BookingTests.cs]"]
  node_platform_tests["Platform tests<br/>unit tests"]
end

node_library -->|"contains"| node_shared_client
node_library -->|"contains"| node_json_layer
node_shared_client -->|"implements"| node_client_contracts
node_shared_client -->|"emits"| node_api_events
node_shared_client -->|"uses"| node_json_layer
node_json_layer -->|"pairs with"| node_json_deser
node_json_layer -->|"uses"| node_converters
node_json_deser -->|"produces"| node_results
node_results -->|"wraps"| node_common
node_shared_client -->|"feeds"| node_account
node_shared_client -->|"feeds"| node_contact
node_shared_client -->|"feeds"| node_crm
node_shared_client -->|"feeds"| node_event
node_shared_client -->|"feeds"| node_invoice
node_shared_client -->|"feeds"| node_batch
node_shared_client -->|"feeds"| node_test
node_shared_client -->|"feeds"| node_venue
node_venue -->|"contains"| node_venue_bookings
node_platform_ext -->|"contains"| node_platform_setup
node_platform_ext -->|"contains"| node_platform_config
node_platform_ext -->|"contains"| node_platform_unsetup
node_serializer_tests -->|"verifies"| node_json_layer
node_deserializer_tests -->|"verifies"| node_json_deser
node_booking_tests -->|"verifies"| node_venue_bookings
node_platform_tests -->|"verifies"| node_platform_setup

click node_library "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Ivvy.API.csproj"
click node_shared_client "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/ApiClient.cs"
click node_client_contracts "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/IApiClient.cs"
click node_api_events "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/ApiClientEvents.cs"
click node_json_layer "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Json/ApiClientSerializer.cs"
click node_json_deser "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Json/ApiClientDeserializer.cs"
click node_converters "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Json/Converters/ResponseConverter.cs"
click node_results "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/ResultObject.cs"
click node_common "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Common/Address.cs"
click node_account "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Account/ApiClient.cs"
click node_contact "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Contact/ApiClient.cs"
click node_crm "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Crm/ApiClient.cs"
click node_event "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Event/ApiClient.cs"
click node_invoice "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Invoice/ApiClient.cs"
click node_batch "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Batch/ApiClient.cs"
click node_test "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Test/ApiClient.cs"
click node_venue "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Venue/ApiClient.cs"
click node_venue_bookings "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Venue/Bookings/RoomReservation.cs"
click node_platform_ext "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/PlatformExtensions/PlatformExtension.cs"
click node_platform_setup "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/PlatformExtensions/Installation/Setup/VerifySetupService.cs"
click node_platform_config "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/PlatformExtensions/Installation/Configure/ConfigureRequest.cs"
click node_platform_unsetup "https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/PlatformExtensions/Installation/Unsetup/UnsetupRequest.cs"
click node_serializer_tests "https://github.com/ivvycode/ivvy-sdk-net/blob/main/tests/ApiClientSerializerTests.cs"
click node_deserializer_tests "https://github.com/ivvycode/ivvy-sdk-net/blob/main/tests/DeserializerTests.cs"
click node_booking_tests "https://github.com/ivvycode/ivvy-sdk-net/blob/main/tests/Venue/BookingTests.cs"
click node_platform_tests "https://github.com/ivvycode/ivvy-sdk-net/blob/main/tests/PlatformExtensions/Installation/Setup/VerifySetupServiceTests.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_library,node_shared_client,node_client_contracts,node_api_events,node_json_layer,node_json_deser,node_converters,node_results,node_common,node_account,node_contact,node_crm,node_event,node_invoice,node_batch,node_test,node_venue,node_venue_bookings,node_platform_ext,node_platform_setup,node_platform_config,node_platform_unsetup toneBlue
class node_serializer_tests,node_deserializer_tests,node_booking_tests,node_platform_tests toneAmber
```

## Components

### src

Production library code

- [iVvy SDK](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Ivvy.API.csproj): .NET library · Single SDK project for typed iVvy API access · `src/Ivvy.API.csproj`
- [Api client](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/ApiClient.cs): core client · Shared API client implementation used by module-specific clients · `src/ApiClient.cs`
- [Client seams](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/IApiClient.cs): interfaces · Common client and event contracts for serialization, events, and transport · `src/IApiClient.cs`
- [Api events](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/ApiClientEvents.cs): events · Shared API call/event plumbing and call details · `src/ApiClientEvents.cs`
- [JSON layer](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Json/ApiClientSerializer.cs): serializer · Typed request/response translation layer for API payloads · `src/Json/ApiClientSerializer.cs`
- [JSON decode](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Json/ApiClientDeserializer.cs): deserializer · Response deserialization and envelope handling · `src/Json/ApiClientDeserializer.cs`
- [Converters](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Json/Converters/ResponseConverter.cs): json converters · API-specific format handling such as arrays-or-object and ISO date/time values · `src/Json/Converters/ResponseConverter.cs`
- [Result wrappers](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/ResultObject.cs): response models · Reusable list/object/success/error wrappers shared across endpoints · `src/ResultObject.cs`
- [Common types](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Common/Address.cs): shared models · Cross-domain value objects and simple reference models · `src/Common/Address.cs`
- [Account](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Account/ApiClient.cs): api module · Users, subscriptions, fields, and account logs · `src/Account/ApiClient.cs`
- [Contact](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Contact/ApiClient.cs): api module · Contacts, companies, and agents · `src/Contact/ApiClient.cs`
- [CRM](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Crm/ApiClient.cs): api module · Leads, opportunities, tasks, and allocation rules · `src/Crm/ApiClient.cs`
- [Event](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Event/ApiClient.cs): api module · Events, registrations, attendees, and invited contacts · `src/Event/ApiClient.cs`
- [Invoice](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Invoice/ApiClient.cs): api module · Invoices, payments, refunds, and line items · `src/Invoice/ApiClient.cs`
- [Batch](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Batch/ApiClient.cs): api module · Asynchronous batch jobs and progress/result payloads · `src/Batch/ApiClient.cs`
- [Test](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Test/ApiClient.cs): api module · Simple ping-style health check client · `src/Test/ApiClient.cs`
- [Venue](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Venue/ApiClient.cs): api module · Most complex domain: venues, rooms, bookings, rates, taxes, and ARI · `src/Venue/ApiClient.cs`
- [Booking models](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/Venue/Bookings/RoomReservation.cs): booking domain · Booking composition, reservations, operations, and related transactional types · `src/Venue/Bookings/RoomReservation.cs`
- [Platform ext](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/PlatformExtensions/PlatformExtension.cs): workflow support · Platform extension installation, configure, setup, and unsetup workflows · `src/PlatformExtensions/PlatformExtension.cs`
- [Setup flow](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/PlatformExtensions/Installation/Setup/VerifySetupService.cs): workflow services · Setup verification services and request/response models · `src/PlatformExtensions/Installation/Setup/VerifySetupService.cs`
- [Configure flow](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/PlatformExtensions/Installation/Configure/ConfigureRequest.cs): workflow models · Configure request and verification response models · `src/PlatformExtensions/Installation/Configure/ConfigureRequest.cs`
- [Unsetup flow](https://github.com/ivvycode/ivvy-sdk-net/blob/main/src/PlatformExtensions/Installation/Unsetup/UnsetupRequest.cs): workflow models · Unsetup request and response models · `src/PlatformExtensions/Installation/Unsetup/UnsetupRequest.cs`

### tests

Unit tests

- [Serializer tests](https://github.com/ivvycode/ivvy-sdk-net/blob/main/tests/ApiClientSerializerTests.cs): unit tests · Serialization contract coverage · `tests/ApiClientSerializerTests.cs`
- [Deserializer tests](https://github.com/ivvycode/ivvy-sdk-net/blob/main/tests/DeserializerTests.cs): unit tests · Deserialization and payload conversion coverage · `tests/DeserializerTests.cs`
- [Booking tests](https://github.com/ivvycode/ivvy-sdk-net/blob/main/tests/Venue/BookingTests.cs): unit tests · Venue booking behavior and model coverage · `tests/Venue/BookingTests.cs`
- [Platform tests](https://github.com/ivvycode/ivvy-sdk-net/blob/main/tests/PlatformExtensions/Installation/Setup/VerifySetupServiceTests.cs): unit tests · Setup verification workflow coverage · `tests/PlatformExtensions/Installation/Setup/VerifySetupServiceTests.cs`

## Connections

- iVvy SDK → Api client: contains · Library project exposes shared client core
- iVvy SDK → JSON layer: contains · Library includes JSON translation layer
- Api client → Client seams: implements · Core client is shaped by shared interfaces
- Api client → Api events: emits · Client execution surfaces shared API call events
- Api client → JSON layer: uses · Client serializes requests through JSON layer
- JSON layer → JSON decode: pairs with · Serialization and deserialization are complementary
- JSON layer → Converters: uses · JSON layer relies on API-specific converters
- JSON decode → Result wrappers: produces · Deserialization yields typed result wrappers
- Result wrappers → Common types: wraps · Shared result wrappers carry common value objects
- Api client → Account: feeds · Shared client underpins Account module client
- Api client → Contact: feeds · Shared client underpins Contact module client
- Api client → CRM: feeds · Shared client underpins CRM module client
- Api client → Event: feeds · Shared client underpins Event module client
- Api client → Invoice: feeds · Shared client underpins Invoice module client
- Api client → Batch: feeds · Shared client underpins Batch module client
- Api client → Test: feeds · Shared client underpins Test module client
- Api client → Venue: feeds · Shared client underpins Venue module client
- Venue → Booking models: contains · Venue module expands into booking-specific models and operations
- Platform ext → Setup flow: contains · Platform extension workflows include setup verification services
- Platform ext → Configure flow: contains · Platform extension workflows include configure models
- Platform ext → Unsetup flow: contains · Platform extension workflows include unsetup models
- Serializer tests → JSON layer: verifies · Tests cover request serialization behavior
- Deserializer tests → JSON decode: verifies · Tests cover payload deserialization behavior
- Booking tests → Booking models: verifies · Tests cover booking model behavior and contracts
- Platform tests → Setup flow: verifies · Tests cover setup verification workflow