Repository Structure

This document provides an overview of the `ava-sdk-js` repository structure, describing its monorepo organization, package composition, and supporting infra.

This document provides an overview of the ava-sdk-js repository structure, describing its monorepo organization, package composition, and supporting infrastructure. For information about the high-level SDK architecture, see SDK Architecture.

Monorepo Overview#

The ava-sdk-js repository is organized as a monorepo using Yarn workspaces, allowing multiple packages to be managed within a single repository. The monorepo approach enables code sharing between packages while maintaining separate versioning and publication processes.

Sources:

Package Structure#

The repository contains two primary packages under the packages/ directory:

1. sdk-js Package#

The @avaprotocol/sdk-js package is the core component, providing the primary SDK functionality. This package implements the client interface and workflow management systems, enabling developers to interact with the Ava Protocol's AVS service.

Key features:

  • Client implementation for AVS communication
  • Workflow models and management
  • Node and trigger factories for workflow construction
  • Authentication mechanisms

Sources:

2. types Package#

The @avaprotocol/types package contains shared type definitions used by the SDK and potentially other Ava Protocol applications. It defines enums, interfaces, and type definitions for the various components of the SDK.

Package contents:

  • Workflow-related types (WorkflowStatus, WorkflowProps)
  • Node types (NodeType, NodeProps)
  • Trigger types (TriggerType, TriggerProps)
  • Execution types (ExecutionStatus, StepProps)

Sources:

Workspace Dependencies#

The packages in the repository are connected through workspace dependencies, with the sdk-js package depending on the types package. This setup allows for type definitions to be shared and maintained separately from the implementation code.

Sources:

Development and Testing Infrastructure#

The repository includes a comprehensive testing setup using Jest for test runner and Babel for transpilation. Tests are organized by functionality, covering different aspects of the SDK.

Test Structure#

Sources:

gRPC Code Generation#

The SDK communicates with the AVS service using gRPC. The repository includes scripts for downloading protocol buffer definitions and generating the necessary gRPC client code.

Sources:

Build and Packaging#

The repository uses:

  • Yarn workspaces for package management
  • TypeScript for static typing and transpilation
  • tsup for building packages
  • Changesets for versioning and change management

Build Configuration#

Each package has its own build configuration, extending the root TypeScript configuration. The SDK exports CommonJS and ESM modules along with TypeScript declaration files.

Sources:

Configuration Files#

The repository includes several configuration files:

  1. package.json: Defines the root workspace and shared dependencies/scripts
  2. tsconfig.json: TypeScript configuration with path aliases for easier imports
  3. jest.config.cjs: Jest test runner configuration
  4. Package-specific tsconfig.json files: Extend the root configuration with package-specific settings

Sources:

Release Management#

The repository uses Changesets for managing releases and versioning:

  • Changesets track changes to packages
  • Automated versioning based on semantic versioning
  • Changelog generation
  • Commands include changeset, version, and individual package build commands

Sources:

Engine Requirements#

The repository specifies the following engine requirements:

  • Node.js ≥ 20.18.0
  • Yarn ≥ 1.22.19

These requirements ensure consistent development and build environments across all contributors.

Sources: