> For the complete documentation index, see [llms.txt](https://docs.pal.aic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pal.aic.io/foundations/architecture.md).

# Architecture

PAL.NET is a layered client framework. Applications call capability façades or generated clients; those clients create operation descriptors and request envelopes; the shared runtime enforces identity, licensing, transport, resilience, diagnostics, and response ownership.

## Runtime flow

```
Application
   |
   +-- IPalOntologyClient / IPalDatasetClient / IPalSqlClient / IPalAipAgentsClient
   +-- Generated capability client
             |
             v
      IPalPlatformOperationClient
             |
             v
      IPalantirClient -> IPalantirTransport
             |
             +-- IPalantirLicenseGuard
             +-- IPalantirAccessTokenProvider
             +-- IPalantirRetryPolicy
             +-- IPalantirTransportDiagnostics
             +-- IPalantirResponseReader
             |
             v
           HttpClient
```

## Ownership boundaries

* `PAL.Core.Models.Domain` owns immutable wire and application contracts.
* `PAL.Core.Services.Domain` owns Palantir-specific protocol behavior.
* Capability projects depend on the models and domain runtime; they do not depend on host UI projects or one another.
* Generated code is an input/output boundary, not a place for hand-authored business logic.
* Foundation owns host composition, configuration providers, shared logging sinks, repositories, and general application infrastructure.
* Foundry OAuth2 behavior is consumed through an adapter; PAL.NET still owns its operation-scoped token boundary.
* The web and native shells are leaf hosts. PAL.NET must remain UI-neutral.

See the [shared ownership matrix](file:///9999950/architecture/PAL.NET-Shared-Ownership-Matrix.md) for the reviewed reuse decisions.

## Contracts first

The runtime is built around replaceable interfaces:

| Interface                       | Purpose                                                        |
| ------------------------------- | -------------------------------------------------------------- |
| `IPalantirAccessTokenProvider`  | Gets a short-lived token for an operation and its scopes.      |
| `IPalantirLicenseGuard`         | Fails closed when the deployment is not entitled.              |
| `IPalantirTransport`            | Executes buffered or streaming requests.                       |
| `IPalantirRetryPolicy`          | Makes bounded, idempotency-aware retry decisions.              |
| `IPalantirResponseReader`       | Materializes bounded responses and transfers stream ownership. |
| `IPalantirTransportDiagnostics` | Emits secret-safe operation diagnostics.                       |
| `IPalPlatformOperationClient`   | Connects generated descriptors to the shared pipeline.         |

This makes tests deterministic: replace the token provider, transport, clock, jitter source, or licence guard without replacing capability clients.

## Immutable request contracts

Requests are records or sealed contracts with validation methods. Validation occurs before network access. Generated request builders separate required constructor values from optional initializers and prevent invalid dependent combinations from reaching the transport.

## UI and host neutrality

The SDK does not depend on Blazor, Avalonia, ASP.NET request context, or a particular logging sink. A web/API host can compose it with the Foundation registration pipeline; a worker or console host can call the core registration directly; a native client can use the native composition root.