# joshcox/kanren architecture

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

- Interactive diagram: https://gitdiagram.com/joshcox/kanren
- Repository: https://github.com/joshcox/kanren

## Overview

##### Main Components

a) Core Engine Components:
- Unification Engine
- Term Management System
- State Management
- Search Strategy
- Substitution System

b) API Layer:
- Public Interface
- Goal Construction
- Query Execution

**Top Layer: Public API**

**Middle Layer: Core Logic**

**Bottom Layer: State Management**

##### Core Components
- Term Management (src/term.ts) connected to the Unification Engine
- State Store (src/store.ts) and Substitution Map (src/substitution.map.ts)
- Search Stream system (src/search.stream.ts)

##### Flow Representations
- Blue: Core logic operations
- Green: State transformations
- Orange: Search operations

##### Specific Implementation Details

**┌─────────────────────┐**
- Public API      │
- (kanren.ts)        │
- ┘
- ↓
**┌─────────────────────┐**
- Unification Engine │←──→│ Term Management │
- (unification.ts)   │    │   (term.ts)     │
- ┘    └────────────────┘
- ↓
**┌─────────────────────┐**
- State Management  │←──→│ Substitution Map│
- (store.ts)      │    │(substitution.map│
- ┘    └────────────────┘
- ↓
**┌─────────────────────┐**
- Search Stream     │
- (search.stream.ts) │
- ┘

##### Additional Notes
- Notes about the asynchronous nature of the search stream
- Where custom term types can be integrated
- Potential constraint extension points

##### Implementation Details to Highlight
- Term type system
- Goal construction process
- State management flow
- Search strategy implementation

Remember to include:
- Version information
- Reference to the original microKanren implementation
- TypeScript-specific implementation details
- Extension points for future development

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph API
        PublicAPI["Public Interface"]
        GoalConstruction["Goal Construction"]
        QueryExecution["Query Execution"]
    end

    subgraph CoreLogic
        UnificationEngine["Unification Engine"]
        TermManagement["Term Management"]
        Container["Container System"]
        Constants["Constants Definition"]
    end

    subgraph StateManagement
        StateStore["State Store"]
        SubstitutionMap["Substitution Map"]
        SearchStream["Search Stream"]
    end

    subgraph Extensions
        direction TB
        Constraints["Constraint Extensions"]
        TermTypes["Term Type Extensions"]
        StandardLib["Standard Libraries"]
    end

    subgraph Testing
        Benchmarking["Benchmarking System"]
        TestUtils["Test Utilities"]
    end

    %% Connections
    PublicAPI --> GoalConstruction
    GoalConstruction --> QueryExecution
    QueryExecution --> UnificationEngine
    UnificationEngine <--> TermManagement
    UnificationEngine <--> Container
    TermManagement --> Constants
    UnificationEngine --> StateStore
    StateStore <--> SubstitutionMap
    StateStore --> SearchStream
    
    %% Extension Points
    UnificationEngine -.-> Constraints
    TermManagement -.-> TermTypes
    TermManagement -.-> StandardLib
    
    %% Testing Connections
    UnificationEngine --> Benchmarking
    StateStore --> Benchmarking
    SearchStream --> Benchmarking
    Benchmarking --> TestUtils

    %% Click Events
    click UnificationEngine "https://github.com/joshcox/kanren/blob/master/packages/microkanren/src/unification.ts"
    click TermManagement "https://github.com/joshcox/kanren/blob/master/packages/microkanren/src/term.ts"
    click StateStore "https://github.com/joshcox/kanren/blob/master/packages/microkanren/src/store.ts"
    click SearchStream "https://github.com/joshcox/kanren/blob/master/packages/microkanren/src/search.stream.ts"
    click SubstitutionMap "https://github.com/joshcox/kanren/blob/master/packages/microkanren/src/substitution.map.ts"
    click PublicAPI "https://github.com/joshcox/kanren/blob/master/packages/microkanren/src/index.ts"
    click Container "https://github.com/joshcox/kanren/blob/master/packages/microkanren/src/container.ts"
    click Constants "https://github.com/joshcox/kanren/blob/master/packages/microkanren/src/constants.ts"
    click Benchmarking "https://github.com/joshcox/kanren/tree/master/packages/microkanren/src/benchmarking/"
    click TestUtils "https://github.com/joshcox/kanren/blob/master/packages/microkanren/src/test/prelude.ts"

    %% Styling
    classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px
    classDef api fill:#d4e6f1,stroke:#2874a6
    classDef core fill:#d5f5e3,stroke:#196f3d
    classDef state fill:#fdebd0,stroke:#d35400
    classDef extension fill:#ebdef0,stroke:#8e44ad
    classDef testing fill:#f2d7d5,stroke:#c0392b

    class PublicAPI,GoalConstruction,QueryExecution api
    class UnificationEngine,TermManagement,Container,Constants core
    class StateStore,SubstitutionMap,SearchStream state
    class Constraints,TermTypes,StandardLib extension
    class Benchmarking,TestUtils testing
```
