# agencyenterprise/nano-creatures-sdk architecture

> Architecture diagram of the GitHub repository agencyenterprise/nano-creatures-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agencyenterprise/nano-creatures-sdk
- Repository: https://github.com/agencyenterprise/nano-creatures-sdk

## Overview

##### Project type and purpose
- This is an open-source TypeScript SDK (“@nano-creatures/sdk”) designed to let client applications programmatically interact with the Nano Creatures REST API.
- It exposes methods for authentication (signUp/signIn), creatures management (CRUD), memory sources, and chat.

##### File structure
- Top level:
- index.ts – SDK entry point, re-exports public API
- types.ts – shared TypeScript interfaces and types
- package.json, tsconfig.json – build and packaging configuration
- dist/ – compiled JS + declaration files for distribution
- No “frontend” or “backend” code here; it’s purely a client library that wraps HTTP calls to an external service.

##### README for additional insights
- The README outlines every public method, parameters, and expected responses.
- It calls out a default baseUrl, optional apiKey, error handling patterns, and the requirement to attach memory sources before chat.

##### Elements
- Clear labels: “Client Application,” “NanoCreaturesSDK,” sub-modules (AuthService, CreatureService, etc.), “Nano Creatures REST API,” “Data Store”
- App → SDK methods
- SDK → HTTP Client → API
- API → HTTP Client → SDK → App
- Orange for External API

- Configuration module feeding into each service (baseUrl, apiKey)
- Which TypeScript types flow in/out of each service (e.g., CreateCreatureParams → Creature)
- Apply consistent coloring and legends to distinguish:
- Client code vs. SDK internals vs. external API

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Application
    ClientApp["Client Application"]:::client

    %% SDK Façade
    SDKFacade["NanoCreaturesSDK (façade)"]:::sdk
    click SDKFacade "https://github.com/agencyenterprise/nano-creatures-sdk/blob/main/index.ts"

    %% Types Module
    Types["types.ts (shared types)"]:::types
    click Types "https://github.com/agencyenterprise/nano-creatures-sdk/blob/main/types.ts"

    %% SDK Subgraph
    subgraph "NanoCreaturesSDK Internals"
        direction TB
        Config["Config Module\n(baseUrl, apiKey)"]:::sdk
        HTTPClient["HTTP Client\n(fetch/axios wrapper)"]:::sdk
        AuthService["AuthService\n(signUp/signIn)"]:::sdk
        CreatureService["CreatureService\n(CRUD)"]:::sdk
        MemorySourceService["MemorySourceService\n(CRUD)"]:::sdk
        ChatService["ChatService\n(chat endpoint)"]:::sdk
    end
    click Config "https://github.com/agencyenterprise/nano-creatures-sdk/blob/main/dist/config.js"
    click Config "https://github.com/agencyenterprise/nano-creatures-sdk/blob/main/dist/config.d.ts"

    %% External API and Data Store
    ExternalAPI["Nano Creatures REST API"]:::externalAPI
    DataStore["Backend Data Store"]:::datastore

    %% Dist Directory and Package Config
    DistDir["dist/ (compiled output)"]:::dist
    click DistDir "https://github.com/agencyenterprise/nano-creatures-sdk/tree/main/dist/"
    PackageJSON["package.json"]:::config
    click PackageJSON "https://github.com/agencyenterprise/nano-creatures-sdk/blob/main/package.json"
    TSConfig["tsconfig.json"]:::config
    click TSConfig "https://github.com/agencyenterprise/nano-creatures-sdk/blob/main/tsconfig.json"

    %% Relationships
    ClientApp -->|"uses methods"| SDKFacade
    SDKFacade -->|"delegates to"| AuthService
    SDKFacade -->|"delegates to"| CreatureService
    SDKFacade -->|"delegates to"| MemorySourceService
    SDKFacade -->|"delegates to"| ChatService
    SDKFacade -->|"exports types from"| Types

    %% Services use Config and HTTPClient
    AuthService -->|"reads config"| Config
    CreatureService -->|"reads config"| Config
    MemorySourceService -->|"reads config"| Config
    ChatService -->|"reads config"| Config

    AuthService -->|"calls"| HTTPClient
    CreatureService -->|"calls"| HTTPClient
    MemorySourceService -->|"calls"| HTTPClient
    ChatService -->|"calls"| HTTPClient

    %% HTTP interactions
    HTTPClient -->|"HTTP requests"| ExternalAPI
    ExternalAPI -->|"JSON responses"| HTTPClient

    HTTPClient -->|"parses JSON"| SDKFacade
    SDKFacade -->|"returns Promises or errors"| ClientApp

    %% External API to Data Store
    ExternalAPI -->|"reads/writes"| DataStore

    %% Distribution artifacts
    SDKFacade --> DistDir
    DistDir --> PackageJSON
    DistDir --> TSConfig

    %% Styles
    classDef client fill:#8fbc8f,stroke:#333,stroke-width:1px
    classDef sdk fill:#add8e6,stroke:#333,stroke-width:1px
    classDef externalAPI fill:#ffa500,stroke:#333,stroke-width:1px
    classDef datastore fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef dist fill:#f0e68c,stroke:#333,stroke-width:1px
    classDef config fill:#ffe4e1,stroke:#333,stroke-width:1px
    classDef types fill:#90ee90,stroke:#333,stroke-width:1px
```
