# Client Architecture

The OCAP Client is designed with a modular architecture to cater to different JavaScript environments and specific use cases. Instead of a one-size-fits-all library, it offers several client implementations, each optimized for a particular context, such as a Node.js backend or a bundle-size-sensitive web application. This approach allows you to choose the most efficient client for your needs, ensuring better performance and a smaller footprint where necessary.

All client variations are built upon a common base, `GraphQLClientBase`, which provides the core functionality for interacting with the blockchain's GraphQL API.

### Inheritance Diagram

The following diagram illustrates the relationship between the different client implementations:

<!-- DIAGRAM_IMAGE_START:architecture:4:3 -->

![Client Architecture](assets/diagram/core-concepts-client-architecture-01.jpg)

<!-- DIAGRAM_IMAGE_END -->


## Client Implementations

Here's a breakdown of each available client and its intended use case.

### `GraphQLClientBase` (The Core)

This is the foundational, lightweight client that all other clients extend. It provides the essential features for communicating with the blockchain:

* Sending GraphQL queries and mutations.
* Establishing WebSocket connections for real-time event subscriptions.
* Handling gas payment headers for sponsored transactions.
* It is environment-agnostic but requires you to provide compatible implementations for WebSockets and EventEmitters if you use subscriptions.

This client is ideal if you only need basic, read-only functionality and want to minimize dependencies.

### `GraphQLClient` (The Full Client)

This is the standard, general-purpose client and the one you'll likely use most often. It extends `GraphQLClientBase` and adds a rich set of high-level helper methods that simplify common on-chain operations. These helpers cover tasks like creating assets, transferring tokens, and managing stakes, abstracting away the complexity of raw GraphQL mutations.

By default, it also automatically initializes its context upon instantiation, making it ready to use immediately.

### `NativeGraphqlClient` (For Node.js)

This client is specifically optimized for the Node.js runtime. It extends the full `GraphQLClient` and configures it to use Node.js's native `events` module for its event handling. This makes it the most performant and reliable choice for any backend application, command-line tool, or script running on a server.

### `GraphqlClientLite` (For Browsers)

Designed for front-end web applications, the `GraphqlClientLite` extends `GraphQLClientBase` and is optimized for minimal bundle size. It swaps out Node.js-specific dependencies for browser-compatible alternatives like `wolfy87-eventemitter`. If you are building a web application where performance and load times are critical, this client provides the core OCAP functionality without the extra weight of the full helper method suite.


## Which Client Should I Use?

To help you decide, here is a summary of the recommended client for each scenario:

| Environment | Use Case                                    | Recommended Client    | Import Path         |
| :---------- | :------------------------------------------ | :-------------------- | :------------------ |
| Node.js     | Backend services, scripts, CLI tools        | `NativeGraphqlClient` | `@ocap/client/node` |
| Browser     | General web applications (e.g., React, Vue) | `GraphQLClient`       | `@ocap/client`      |
| Browser     | Bundle-size sensitive applications          | `GraphqlClientLite`   | `@ocap/client/lite` |
| Any         | Read-only, minimal functionality required   | `GraphQLClientBase`   | `@ocap/client/base` |

### Example Imports

Here’s how you would import each client in your code:

```javascript Node.js Client icon=logos:nodejs-icon
const NativeGraphqlClient = require('@ocap/client/node');
const client = new NativeGraphqlClient('https://beta.abtnetwork.io/api');
```

```javascript Full Browser Client icon=logos:javascript
const GraphQLClient = require('@ocap/client');
const client = new GraphQLClient('https://beta.abtnetwork.io/api');
```

```javascript Lite Browser Client icon=logos:javascript
const GraphqlClientLite = require('@ocap/client/lite');
const client = new GraphqlClientLite('https://beta.abtnetwork.io/api');
```


## Summary

Understanding the different client implementations allows you to make an informed choice that best fits your application's environment and requirements. By selecting the appropriate client, you can optimize for performance, bundle size, and ease of use.

Now that you understand the client architecture, you can dive deeper into how transactions are constructed and processed. Learn more in the [Transaction Lifecycle](./core-concepts-transaction-lifecycle.md) guide.
