# kumarpit/lamb architecture

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

- Interactive diagram: https://gitdiagram.com/kumarpit/lamb
- Repository: https://github.com/kumarpit/lamb

## Overview

##### Project type and purpose
- lamb(iguous) is a small, open‑source JavaScript/TypeScript library (an NPM package) implementing a generalized backtracking (“amb”) search operator à la SICP.
- Its goal is to expose a simple, declarative API (the `Lamb<T>` class) so client code can define choice variables and constraints, and then automatically search for satisfying assignments.

##### File structure
Top‑level:
- error.ts          – defines custom error classes (e.g., ambiguous failure)
- example.ts        – usage examples or demos
- index.ts          – public entry point, exports the `Lamb` class and API
- __tests__/lamb.test.js – unit tests against the built library
- tsconfig.json, .npmignore, .gitignore, package*.json – config, build, packaging
lib/:
- *.js, *.d.ts       – transpiled outputs ready for publishing

Patterns & architecture implications:
- Single-package library, no frontend/backends split
- Core engine lives in index.ts (and possibly split into internal helpers)
- Error handling in error.ts
- Build pipeline compiles TS → JS + type declarations for consumers
- Testing harness against lib/ outputs

##### README for additional insights
- Core concepts: `addChoice`, `addConstraint`, `solve` methods
- Usage examples: simple sum‑to‑n, map‑coloring, eight‑queens
- No built‑in persistence or external service calls; purely in‑memory search
- Heavily relies on JavaScript callbacks and recursion

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Code
    subgraph "User Code" 
        direction TB
        Client["Client Code"]:::client
        TestHarness["Test Harness"]:::infra
    end

    %% Library Package Sources
    subgraph "Library Source Code"
        direction TB
        API["Lamb API\n(index.ts)"]:::api
        ErrorSrc["Error Module\n(error.ts)"]:::core
    end

    %% Core Logic Components
    subgraph "Core Engine Components"
        direction TB
        CoreEngine["Core Engine"]:::core
        ChoiceMgr["Choice Manager"]:::core
        ConstraintEval["Constraint Evaluator"]:::core
    end

    %% Infrastructure: Build Pipeline
    subgraph "Build Pipeline"
        direction TB
        TSConfig["tsconfig.json"]:::infra
        NpmIgnore[".npmignore"]:::infra
        PackageJSON["package.json"]:::infra
    end

    %% Transpiled Outputs
    subgraph "Transpiled Outputs (lib/)"
        direction TB
        LibIndexJS["index.js"]:::infra
        LibIndexDTS["index.d.ts"]:::infra
        LibErrorJS["error.js"]:::infra
        LibErrorDTS["error.d.ts"]:::infra
        LibExampleJS["example.js"]:::infra
        LibExampleDTS["example.d.ts"]:::infra
    end

    %% Relationships
    Client -->|"imports & calls"| API
    TestHarness -->|"runs tests against"| LibIndexJS
    API -->|"delegates to"| CoreEngine
    CoreEngine -->|"reads/writes domains"| ChoiceMgr
    CoreEngine -->|"invokes constraints"| ConstraintEval
    CoreEngine -->|"throws on failure"| ErrorSrc
    TSConfig -->|"compiles sources"| LibIndexJS
    NpmIgnore -->|"packages"| LibIndexJS
    PackageJSON -->|"defines package"| LibIndexJS
    LibIndexJS -->|"includes declarations"| LibIndexDTS
    ErrorSrc -->|"compiled to"| LibErrorJS
    LibErrorJS -->|"with types"| LibErrorDTS
    %% Build pipeline also outputs example
    TSConfig -->|"compiles example"| LibExampleJS
    LibExampleJS -->|"with types"| LibExampleDTS

    %% Click events
    click Client "https://github.com/kumarpit/lamb/blob/main/example.ts"
    click TestHarness "https://github.com/kumarpit/lamb/blob/main/__tests__/lamb.test.js"
    click API "https://github.com/kumarpit/lamb/blob/main/index.ts"
    click API "https://github.com/kumarpit/lamb/blob/main/lib/index.js"
    click API "https://github.com/kumarpit/lamb/blob/main/lib/index.d.ts"
    click CoreEngine "https://github.com/kumarpit/lamb/blob/main/index.ts"
    click CoreEngine "https://github.com/kumarpit/lamb/blob/main/lib/index.js"
    click ErrorSrc "https://github.com/kumarpit/lamb/blob/main/error.ts"
    click ErrorSrc "https://github.com/kumarpit/lamb/blob/main/lib/error.js"
    click ErrorSrc "https://github.com/kumarpit/lamb/blob/main/lib/error.d.ts"
    click TSConfig "https://github.com/kumarpit/lamb/blob/main/tsconfig.json"
    click NpmIgnore "https://github.com/kumarpit/lamb/blob/main/.npmignore"
    click PackageJSON "https://github.com/kumarpit/lamb/blob/main/package.json"
    click LibExampleJS "https://github.com/kumarpit/lamb/blob/main/lib/example.js"
    click LibExampleDTS "https://github.com/kumarpit/lamb/blob/main/lib/example.d.ts"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:1px
    classDef api fill:#bbf,stroke:#333,stroke-width:1px
    classDef core fill:#bfb,stroke:#333,stroke-width:1px
    classDef infra fill:#ddd,stroke:#333,stroke-width:1px
```
