How playform/pieces works
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)