# playform/pieces architecture

> Architecture diagram of the GitHub repository playform/pieces, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/playform/pieces
- Repository: https://github.com/playform/pieces

## Overview

##### Project Type & Purpose
- This is a TypeScript client‐SDK (library), auto‐generated via OpenAPI, for interacting with a locally hosted “Pieces OS” backend service.
- Its role is to provide strongly typed API clients (ConnectorApi, AssetsApi, WellKnownApi, etc.), model definitions, and an HTTP runtime layer so that application code can easily call Pieces OS endpoints (copilot chats, asset management, LLM provisioning, etc.).

##### High-Level File Structure Analysis
Top-level
- package.json / tsconfig.json – Node package and compiler configuration
- assets/ – logo images used in README; not part of runtime
- core/
– apis/ – one class per REST endpoint group (ActivitiesApi.ts, AssetsApi.ts, ConnectorApi.ts, …)
– models/ – all request/response interfaces & enums (SeededAsset, ConversationMessage, Model, etc.)
– index.ts – barrel exports of Configuration, APIs, Models
– runtime.ts – HTTP request wrapper, serialization/deserialization, error handling
– .openapi-generator*/ – codegen metadata & ignore rules
- README.md – usage, examples, intended to onboard developers

##### README Insights
- SDK requires a locally running Pieces OS (on port 1000 or 5323)
- Typical flow:
a. Create a Configuration with basePath
b. Instantiate one of the generated Api classes
c. Call methods (connect, assetsCreateNewAsset, getWellKnownHealth, etc.)
- Emphasizes features: Copilot Chats, Asset Management, multi-LLM support

a. Main Components
1. Client Application
- Your TS/JS code (main.ts, scripts, UI app)
2. SDK Library (“@pieces.app/pieces-os-client”)
– Configuration module (basePath, auth tokens)
– HTTP Runtime (fetch/XHR wrapper, serializers)
– API Modules (ConnectorApi, AssetsApi, WellKnownApi, …)
– Model Layer (TypeScript interfaces & enums)
3. Pieces OS Backend Service
– Exposes REST endpoints for assets, chats, models, health checks
– Integrates with external services: Auth0, OpenAI, etc.
– Auth0 (authentication)
– OpenAI or other LLM providers
– Storage/Database

b. Relationships & Data Flow
- Client App → SDK Configuration → selects basePath & headers
- Client App → calls SDK API method (e.g., new AssetsApi().assetsCreateNewAsset({...}))
- API module → HTTP Runtime → sends HTTP request JSON → Pieces OS Service
- Pieces OS Service → processes request (auth middleware, business logic, LLM calls) → returns JSON
- HTTP Runtime → deserializes into Model objects → API module returns typed result → Client App

c. Architectural Patterns & Principles
– Separation of Concerns
- Configuration vs. Runtime vs. API layer vs. Model definitions
– Codegen / OpenAPI client pattern
– Dependency inversion: Client app depends on abstractions (API interfaces)
– Single responsibility: Each Api class handles one resource set

d. Key Technologies / Frameworks
– TypeScript & Node.js
– OpenAPI Generator (produces core/apis + core/models + runtime.ts)
– Fetch or Axios wrapper inside runtime.ts
– NPM packaging
– Pieces OS backend (HTTP/REST)

## Diagram (Mermaid)

```mermaid
flowchart TD
    ClientApp["Client Application"]:::client

    subgraph "Pieces SDK"
        Configuration["Configuration"]:::sdk
        Runtime["HTTP Runtime"]:::sdk

        subgraph "API Modules"
            Connector["ConnectorApi"]:::sdk
            AssetsApi["AssetsApi"]:::sdk
            WellKnown["WellKnownApi"]:::sdk
            APIIndex["Barrel Export of APIs"]:::sdk
        end

        subgraph "Model Layer"
            ModelsIndex["Barrel Export of Models"]:::sdk
        end

        Codegen["Codegen Metadata"]:::sdk
    end

    Backend["Pieces OS Backend Service"]:::backend

    subgraph "External Services"
        Auth0["Auth0"]:::external
        OpenAI["OpenAI / LLM Providers"]:::external
        Storage["Storage / Database"]:::external
    end

    Docs["README.md"]:::sdk
    StaticAssets["assets/"]:::external
    Package["package.json / tsconfig.json"]:::sdk

    %% Data Flow
    ClientApp -->|"set basePath & headers"| Configuration
    ClientApp -->|"calls API method"| Connector
    Connector -->|"REST JSON request"| Runtime
    AssetsApi -->|"REST JSON request"| Runtime
    WellKnown -->|"REST JSON request"| Runtime
    Runtime -->|"HTTP Request"| Backend
    Backend -->|"REST JSON response"| Runtime
    Runtime -->|"deserializes & returns typed data"| Connector
    Runtime -->|"deserializes & returns typed data"| AssetsApi
    Runtime -->|"deserializes & returns typed data"| WellKnown
    Connector -->|"returns result"| ClientApp
    AssetsApi -->|"returns result"| ClientApp
    WellKnown -->|"returns result"| ClientApp

    Backend --> Auth0
    Backend --> OpenAI
    Backend --> Storage

    %% Click Events
    click Configuration "https://github.com/playform/pieces/blob/main/core/index.ts"
    click Runtime "https://github.com/playform/pieces/blob/main/core/runtime.ts"
    click APIIndex "https://github.com/playform/pieces/blob/main/core/apis/index.ts"
    click ModelsIndex "https://github.com/playform/pieces/blob/main/core/models/index.ts"
    click Codegen "https://github.com/playform/pieces/tree/main/core/.openapi-generator/"
    click StaticAssets "https://github.com/playform/pieces/tree/main/assets/"
    click Package "https://github.com/playform/pieces/blob/main/package.json"
    click Docs "https://github.com/playform/pieces/blob/main/README.md"

    %% Styles
    classDef client fill:#88cc88,stroke:#333,stroke-width:1px
    classDef sdk fill:#88aaff,stroke:#333,stroke-width:1px
    classDef backend fill:#ffbb66,stroke:#333,stroke-width:1px
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
