# youqad/bit-reversal-trees architecture

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

- Interactive diagram: https://gitdiagram.com/youqad/bit-reversal-trees
- Repository: https://github.com/youqad/bit-reversal-trees

## Overview

##### Main Components

a. Core Implementation Layer:
- Haskell Implementation Module (src/Lib.hs)
- Python Implementation Module (python/utils.py)

b. Testing Framework:
- Haskell Testing (test/Spec.hs, test/DynamicSpec.hs)
- Python Testing (multiple test files in python/)
- Property-Based Testing Components (QuickCheck & Hypothesis)

c. LLM Search Infrastructure:
- Generator LLM Interface
- Verifier LLM Interface
- Program Synthesis Controller (solve_challenge.py)

d. External Services:
- OpenAI API
- Anthropic API
- Weights & Biases Integration

##### Component Relationships

**┌─────────────────────────────────────────────────────────────┐**
- External Services Layer                   │
- ┌──────────┐    ┌────────────┐    ┌────────────────────┐  │
- OpenAI   │    │ Anthropic  │    │ Weights & Biases   │  │
- ┘    └────────────┘    └────────────────────┘  │
- ┬──────────────┬────────────────────┬────────────┘

- ▼              ▼                    ▼
**┌─────────────────────────────────────────────────────────────┐**
- LLM Search Layer                          │
- ┌──────────┐    ┌────────────┐    ┌────────────────────┐  │
- Generator │    │ Verifier   │    │ Program Synthesis   │  │
- LLM    │    │   LLM      │    │   Controller       │  │
- ┘    └────────────┘    └────────────────────┘  │
- ┬──────────────┬────────────────────┬────────────┘

- ▼              ▼                    ▼
**┌─────────────────────────────────────────────────────────────┐**
- Implementation Layer                          │
- ┌──────────┐    ┌────────────┐    ┌────────────────────┐  │
- Haskell  │    │  Python    │    │     Shared         │  │
- Core    │    │   Core     │    │    Data Types      │  │
- ┘    └────────────┘    └────────────────────┘  │
- ┬──────────────┬────────────────────┬────────────┘

- ▼              ▼                    ▼
**┌─────────────────────────────────────────────────────────────┐**
- Testing Layer                            │
- ┌──────────┐    ┌────────────┐    ┌────────────────────┐  │
- QuickCheck│    │ Hypothesis │    │ Integration Tests  │  │
- Tests   │    │   Tests    │    │                   │  │
- ┘    └────────────┘    └────────────────────┘  │
- ┘

##### Important Details

a. Configuration Flow:
- .env configuration affecting both LLM and implementation layers
- Where environment variables control behavior

b. Testing Flow:
- Bidirectional communication between implementation and testing layers
- Property-based testing feedback loops

c. LLM Search Process:
- Conversation flow between generator and verifier
- How solutions are validated and refined

##### Implementation Notes

- Numbered sequence indicators for the LLM search process

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles
    classDef external fill:#d0e8ff,stroke:#333
    classDef llm fill:#d0ffd0,stroke:#333
    classDef implementation fill:#ffe4cc,stroke:#333
    classDef testing fill:#e6d0ff,stroke:#333
    classDef config fill:#fff2cc,stroke:#333

    %% External Services Layer
    subgraph ExternalServices
        OpenAI["OpenAI API"]
        Anthropic["Anthropic API"]
        WandB["Weights & Biases"]
    end

    %% Configuration Layer
    subgraph Config
        EnvConfig["Environment Config"]:::config
        Dependencies["Dependencies"]:::config
        Prompts["LLM Prompts"]:::config
    end

    click EnvConfig "https://github.com/youqad/bit-reversal-trees/blob/main/.env.example"
    click Dependencies "https://github.com/youqad/bit-reversal-trees/blob/main/python/requirements.txt"
    click Prompts "https://github.com/youqad/bit-reversal-trees/blob/main/haskell_prompt.md"

    %% LLM Search Layer
    subgraph LLMSearch
        Generator["Generator LLM"]:::llm
        Verifier["Verifier LLM"]:::llm
        SynthController["Program Synthesis Controller"]:::llm
        Solutions["LLM Solution Storage"]:::llm
    end

    click SynthController "https://github.com/youqad/bit-reversal-trees/blob/main/python/solve_challenge.py"
    click Solutions "https://github.com/youqad/bit-reversal-trees/tree/main/python/some_almost_solutions_found/"

    %% Implementation Layer
    subgraph Implementation
        HaskellCore["Haskell Core Implementation"]:::implementation
        PythonCore["Python Core Implementation"]:::implementation
        SharedTypes["Shared Data Types"]:::implementation
        EntryPoint["Project Entry Point"]:::implementation
    end

    click HaskellCore "https://github.com/youqad/bit-reversal-trees/blob/main/src/Lib.hs"
    click PythonCore "https://github.com/youqad/bit-reversal-trees/blob/main/python/utils.py"
    click EntryPoint "https://github.com/youqad/bit-reversal-trees/blob/main/app/Main.hs"

    %% Testing Layer
    subgraph Testing
        HaskellTests["Haskell Tests"]:::testing
        PythonTests["Python Tests"]:::testing
        PropertyTests["Property-Based Tests"]:::testing
    end

    click HaskellTests "https://github.com/youqad/bit-reversal-trees/blob/main/test/Spec.hs"
    click PythonTests "https://github.com/youqad/bit-reversal-trees/blob/main/python/test_solve_challenge_hypothesis.py"

    %% Relationships
    EnvConfig --> Generator
    EnvConfig --> Verifier
    Dependencies --> Implementation
    Prompts --> Generator
    Prompts --> Verifier

    Generator --> SynthController
    Verifier --> SynthController
    SynthController --> Solutions

    OpenAI --> Generator
    OpenAI --> Verifier
    Anthropic --> Generator
    Anthropic --> Verifier
    WandB --> SynthController

    SynthController --> HaskellCore
    SynthController --> PythonCore
    HaskellCore --> SharedTypes
    PythonCore --> SharedTypes
    EntryPoint --> HaskellCore

    HaskellCore --> HaskellTests
    PythonCore --> PythonTests
    SharedTypes --> PropertyTests
    PropertyTests --> HaskellTests
    PropertyTests --> PythonTests

    %% Legend
    subgraph Legend
        L1["External Services"]:::external
        L2["LLM Components"]:::llm
        L3["Implementation"]:::implementation
        L4["Testing"]:::testing
        L5["Configuration"]:::config
    end
```
