# mft-labs/aepf_opensearch architecture

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

- Interactive diagram: https://gitdiagram.com/mft-labs/aepf_opensearch
- Repository: https://github.com/mft-labs/aepf_opensearch

## Overview

##### Project type and purpose
- This is an Elixir library (mix project) that implements an Ash Framework data layer backed by OpenSearch.
- Purpose: let Ash resources query and index data in OpenSearch by translating Ash queries into OpenSearch DSL and communicating over HTTP.

##### File structure
- Top‐level:
- lib/aepf_opensearch: main modules
- lib/aepf_opensearch/application.ex: OTP application/Supervisor
- lib/aepf_opensearch/client.ex: HTTP client module
- lib/aepf_opensearch/data_layer.ex: implements Ash.DataLayer behavior
- lib/aepf_opensearch/translator.ex: turns Ash queries into DSL
- lib/aepf_opensearch/query.ex: data structures for queries
- lib/mix/opensearch/init.ex: mix task “mix opensearch.init” (seeder scaffolding)
- Other files: configuration under config/, Mix project files (mix.exs, mix.lock), tests under test/.

##### README for additional insights
- Confirms: Ash DataLayer integration, custom query translator, HTTP client, seeder utility.
- Notes configuration keys (base_url, json_library).

a. Main components
1. Ash Resource (in consumer app)
2. AepfOpensearch.DataLayer (implements Ash.DataLayer behaviour)
3. Translator (AepfOpensearch.Translator)
4. Query Model (AepfOpensearch.Query)
5. OpenSearch Client (AepfOpensearch.Client)
6. OpenSearch Cluster / Index
7. Mix Seeder Task (mix opensearch.init)
b. Relationships & interactions
- The Ash Resource’s data_layer configuration points to DataLayer → DataLayer API calls (read, create, update, delete) enter.
- DataLayer converts abstract operation into an internal Query struct.
- Translator module transforms Query struct into OpenSearch DSL JSON.
- Client sends HTTP request (uses configured base_url + Jason for JSON) to the OpenSearch cluster.
- OpenSearch responds with JSON → Client parses → DataLayer maps back to Ash Resource structs.
- Mix Seeder Task uses Client and DataLayer APIs to seed initial indices.
- Application Supervisor (application.ex) starts the Client (e.g., HTTP pool) under the OTP tree.
c. Architectural patterns & principles
- Behavior‐based extension of Ash (DataLayer behaviour).
- Clear separation of concerns: DataLayer (interface), Translator (logic), Client (transport).
- OTP supervision for client processes.
- Modular pipeline: Resource → DataLayer → Translator → Client → External service → back.
d. Key technologies
- Elixir / OTP / Mix
- Ash Framework (Ash.Resource, Ash.DataLayer)
- OpenSearch (REST API)
- JSON library (Jason)
- HTTP client (e.g., Finch or Hackney inside Client module)
- ExDoc for documentation

##### Detail
- Supervisor: show Application.ex starting the Client.
- Config injection from config/runtime.exs into Client.
- Behavior callbacks in DataLayer (e.g., load, run_query).

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Library Code"
        direction TB
        Entry["AepfOpensearch (Entry Point Module)"]:::library
        App["AepfOpensearch.Application (Supervisor)"]:::library
        Client["AepfOpensearch.Client"]:::library
        DataLayer["AepfOpensearch.DataLayer"]:::library
        Query["AepfOpensearch.Query"]:::library
        Translator["AepfOpensearch.Translator"]:::library
        Config["Runtime Config"]:::library
    end

    subgraph "External Components"
        direction TB
        Resource["Ash Resource"]:::external
        OpenSearch["OpenSearch Cluster/Index"]:::external
    end

    subgraph "Tooling"
        direction TB
        Seeder["mix opensearch.init"]:::tooling
    end

    %% Library initialization
    Entry --> App
    App --> Client

    %% Main data flow
    Resource -->|"data_layer config"| DataLayer
    DataLayer -->|"build Query struct"| Query
    Query -->|"to DSL JSON"| Translator
    Translator -->|"JSON DSL"| Client
    Client -->|"HTTP Request"| OpenSearch
    OpenSearch -->|"JSON Response"| Client
    Client -->|"parsed response"| DataLayer
    DataLayer -->|"Ash Structs"| Resource

    %% Seeder task flow
    Seeder --> Client
    Seeder --> DataLayer

    %% Configuration injection
    Config --> Client

    %% Click Events
    click Entry "https://github.com/mft-labs/aepf_opensearch/blob/main/lib/aepf_opensearch.ex"
    click App "https://github.com/mft-labs/aepf_opensearch/blob/main/lib/aepf_opensearch/application.ex"
    click Client "https://github.com/mft-labs/aepf_opensearch/blob/main/lib/aepf_opensearch/client.ex"
    click DataLayer "https://github.com/mft-labs/aepf_opensearch/blob/main/lib/aepf_opensearch/data_layer.ex"
    click Query "https://github.com/mft-labs/aepf_opensearch/blob/main/lib/aepf_opensearch/query.ex"
    click Translator "https://github.com/mft-labs/aepf_opensearch/blob/main/lib/aepf_opensearch/translator.ex"
    click Seeder "https://github.com/mft-labs/aepf_opensearch/blob/main/lib/mix/opensearch/init.ex"
    click Config "https://github.com/mft-labs/aepf_opensearch/blob/main/config/runtime.exs"

    classDef library fill:#D3E5FF,stroke:#004085,color:#004085,stroke-width:1px;
    classDef external fill:#FFF3CD,stroke:#856404,color:#856404,stroke-width:1px;
    classDef tooling fill:#D4EDDA,stroke:#155724,color:#155724,stroke-width:1px;
```
