# phoe/amb architecture

> Architecture diagram of the GitHub repository phoe/amb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phoe/amb
- Repository: https://github.com/phoe/amb

## Overview

##### Project Type Analysis
This is a specialized Common Lisp library implementing McCarthy's ambiguous operator, focusing on nondeterministic computing. It's a relatively small, focused project with a specific purpose.

##### Key Components

a. Core Components:
- AMB Operator System
- AMB Macro Component
- Constraint System Component
- Backtracking Engine
- Stack Management System
- Failure Handling System

b. External Interface:
- Public API Layer
- AMB Macro Interface
- CONSTRAIN Macro Interface
- AMB-FAILURE Condition System

**┌─ Public API Layer ─────────────────────┐**
- ┌─ AMB Macro ─┐ ┌─ CONSTRAIN Macro ─┐ │
- ┘ └──────────────────┘  │
- ┘

- ▼              ▼
**┌─ Core Processing Layer ───────────────┐**
- ┌─ Backtracking ─┐ ┌─ Constraint  ─┐ │
- Engine      │ │  Evaluation   │ │
- ┘ └──────────────┘  │
- ┌─ Stack        ─┐ ┌─ Variable   ─┐ │
- Management    │ │  Binding     │ │
- ┘ └──────────────┘  │
- ┘

- ▼              ▼
**┌─ Error Handling Layer ──────────────┐**
- ┌─ AMB-FAILURE ─┐ ┌─ Warning    ─┐ │
- Condition   │ │  System      │ │
- ┘ └─────────────┘  │
- ┘

##### Important Elements to Highlight

a. Data Flow:
- How variable bindings flow from AMB macro to the backtracking engine
- Constraint evaluation flow
- Demonstrate backtracking paths when constraints fail
- Error propagation paths

b. Key Interactions:
- AMB macro ↔ Stack Management
- CONSTRAIN macro ↔ Constraint Evaluation
- Backtracking Engine ↔ Variable Binding
- Error Handling ↔ All Layers

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and classes
    classDef api fill:#a8d1f0,stroke:#2980b9
    classDef core fill:#a8e6cf,stroke:#1abc9c
    classDef error fill:#ffd3b6,stroke:#e67e22
    classDef doc fill:#ddd,stroke:#666

    %% Public API Layer
    subgraph API
        AMBMacro["AMB Macro Interface"]:::api
        CONSTRAINMacro["CONSTRAIN Macro Interface"]:::api
        APIDoc["API Documentation"]:::doc
        Manual["User Manual"]:::doc
    end

    %% Core Processing Layer
    subgraph Core
        BacktrackEngine["Backtracking Engine"]:::core
        ConstraintEval["Constraint Evaluation"]:::core
        StackMgmt["Stack Management"]:::core
        VarBinding["Variable Binding"]:::core
    end

    %% Error Handling Layer
    subgraph ErrorHandling
        AMBFailure["AMB-FAILURE Condition"]:::error
        WarnSystem["Warning System"]:::error
    end

    %% Testing Layer
    subgraph Testing
        TestFramework["Test Framework"]:::doc
        SICPTests["SICP Tests"]:::doc
    end

    %% Relationships
    AMBMacro --> BacktrackEngine
    AMBMacro --> StackMgmt
    CONSTRAINMacro --> ConstraintEval
    BacktrackEngine --> VarBinding
    ConstraintEval --> VarBinding
    BacktrackEngine --> AMBFailure
    ConstraintEval --> AMBFailure
    StackMgmt --> WarnSystem
    VarBinding --> WarnSystem

    %% Testing relationships
    TestFramework --> AMBMacro
    TestFramework --> CONSTRAINMacro
    SICPTests --> AMBMacro

    %% Click events
    click AMBMacro "https://github.com/phoe/amb/blob/main/src/amb.lisp"
    click CONSTRAINMacro "https://github.com/phoe/amb/blob/main/src/amb.lisp"
    click BacktrackEngine "https://github.com/phoe/amb/blob/main/src/amb.lisp"
    click ConstraintEval "https://github.com/phoe/amb/blob/main/src/amb.lisp"
    click StackMgmt "https://github.com/phoe/amb/blob/main/src/amb.lisp"
    click VarBinding "https://github.com/phoe/amb/blob/main/src/amb.lisp"
    click APIDoc "https://github.com/phoe/amb/blob/main/src/documentation.lisp"
    click Manual "https://github.com/phoe/amb/blob/main/doc/MANUAL.md"
    click TestFramework "https://github.com/phoe/amb/blob/main/t/test.lisp"
    click SICPTests "https://github.com/phoe/amb/blob/main/t/test-sicp.lisp"

    %% Legend
    subgraph Legend
        API_Legend["API Component"]:::api
        Core_Legend["Core Component"]:::core
        Error_Legend["Error Handling"]:::error
        Doc_Legend["Documentation"]:::doc
    end
```
