# overture-stack/arranger architecture

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

- Interactive diagram: https://gitdiagram.com/overture-stack/arranger
- Repository: https://github.com/overture-stack/arranger

## Overview

##### Project Type and Purpose
- Arranger is a full-stack microservice comprised of:
- A GraphQL API server (Node.js/TypeScript) that proxies and augments Elasticsearch.
- A React-based admin UI (modules/admin-ui) for managing indices and configurations.
- A reusable React component library (modules/components) for building custom search UIs.
- Container orchestration (docker-compose) to spin up Elasticsearch, the API, and UI.

##### High-Level Components
A. Data Layer
– Elasticsearch cluster
- docker/elasticsearch (mapping.json, load-es-data scripts, sample docs)
B. API Layer
– Arranger GraphQL Server (modules/server + src/)
- GraphQL schema & resolvers (admin schemas, network resolvers)
- Middleware (query builder, aggregation builder)
- Config loader (configTemplates, utils)
- ES REST adapter (es_rest, mapping utilities)
C. UI Layer
1. Admin UI (modules/admin-ui)
- React app using Apollo Client to query GraphQL API
- Pages for Project, Indices, Version, Config Editor
2. Component Library (modules/components)
- Standalone React components (Arranger, Table, Filters, SQON builder, etc.)
- Storybook stories for manual testing and preview
D. DevOps/CI
– docker-compose.yml orchestrates three services (ES, server, UI)
– Docker build scripts (docker/Dockerfile.*)
– Jenkinsfile & Makefile for CI/CD pipelines
– Integration tests (integration-tests/*)

##### Interactions and Data Flow
1. Admin UI (React) → GraphQL Server
- Apollo client issues GraphQL queries/mutations (projects, mappings, facets)
2. Component Library (imported by external apps or admin UI) → GraphQL Server
- Uses gql queries defined in src/utils/api.ts or generated code
3. GraphQL Server → Elasticsearch
- Middleware builds DSL from SQON filters, mapping utilities translate mappings
- ES REST calls via fetchMapping and es_rest client
- Aggregations, paging, set resolution handled in server before returning GraphQL response
4. CI/CD → Docker images → Deployment
- Jenkins pulls code, runs tests (unit, integration), builds Docker images for ES, server, UI
- docker-compose brings up services for local dev or staging

##### Architectural Patterns and Principles
- Layered separation: UI / API / Data
- Microservice/containerized design: each component in its own Docker container
- Modular GraphQL schemas: “admin” vs “network” resolvers, schema stitching
- Reusability: UI library decoupled from admin portal, consumed via package.json
- Configuration‐driven mapping: JSON templates in configTemplates and docker/server

##### Technologies & Frameworks
- Node.js / TypeScript / GraphQL (Apollo or custom server)
- Elasticsearch (v7+)
- React / TypeScript / Redux (admin-ui)
- Storybook (components)
- Docker & docker-compose
- Jenkins CI, Makefile scripts
- Jest / Mocha for unit & integration tests

##### Essential Elements
- Notes on tests and CI pipeline feeding into Docker images (Jenkins → docker build → deploy)

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Data Layer"
        ES["Elasticsearch Cluster"]:::data
    end

    subgraph "Backend/API"
        API["Arranger GraphQL Server"]:::backend
        subgraph "Server Modules"
            CT["configTemplates"]:::backend
            IDX["index.ts"]:::backend
            GQL["gqlServer.ts"]:::backend
            GR["graphqlRoutes.js"]:::backend
            ADMIN["src/admin"]:::backend
            NET["src/network"]:::backend
            MW["src/middleware"]:::backend
            MAP["src/mapping"]:::backend
            ESREST["src/es_rest"]:::backend
        end
    end

    subgraph "Frontend/UI"
        subgraph "Admin UI"
            AUI["Admin UI (React)"]:::frontend
            APP["App.tsx"]:::frontend
            PAGES["pages"]:::frontend
            CMPS["components"]:::frontend
            QRY["gql/queries"]:::frontend
            HTML["index.html"]:::frontend
        end
        subgraph "Component Library"
            LIB["React Component Library"]:::library
            LIBSRC["src"]:::library
            SB[".storybook"]:::library
            STORIES["stories"]:::library
        end
    end

    subgraph "DevOps/CI"
        CI["CI/CD Pipeline"]:::ci
        DC["docker-compose.yml"]:::ci
        DF1["docker/Dockerfile.local"]:::ci
        DF2["docker/Dockerfile.jenkins"]:::ci
        JEN["Jenkinsfile"]:::ci
        MAKE["Makefile"]:::ci
        INT["integration-tests"]:::ci
    end

    AUI -->|"GraphQL over HTTP"| API
    LIB -->|"GraphQL over HTTP"| API
    API -->|"ES JSON-DSL"| ES
    CI -->|"Docker image push"| DC
    CI -->|"uses"| DF1
    CI -->|"uses"| DF2
    CI -->|"runs"| JEN
    CI -->|"runs"| MAKE
    CI -->|"tests"| INT
    DC -->|"orchestrates"| ES
    DC -->|"orchestrates"| API
    DC -->|"orchestrates"| AUI

    click ES "https://github.com/overture-stack/arranger/tree/main/docker/elasticsearch/"
    click CT "https://github.com/overture-stack/arranger/tree/main/modules/server/configTemplates/"
    click IDX "https://github.com/overture-stack/arranger/blob/main/modules/server/index.ts"
    click GQL "https://github.com/overture-stack/arranger/blob/main/modules/server/src/gqlServer.ts"
    click GR "https://github.com/overture-stack/arranger/blob/main/modules/server/src/graphqlRoutes.js"
    click ADMIN "https://github.com/overture-stack/arranger/tree/main/modules/server/src/admin/"
    click NET "https://github.com/overture-stack/arranger/tree/main/modules/server/src/network/"
    click MW "https://github.com/overture-stack/arranger/tree/main/modules/server/src/middleware/"
    click MAP "https://github.com/overture-stack/arranger/tree/main/modules/server/src/mapping/"
    click ESREST "https://github.com/overture-stack/arranger/tree/main/modules/server/src/es_rest/"
    click APP "https://github.com/overture-stack/arranger/blob/main/modules/admin-ui/src/App.tsx"
    click PAGES "https://github.com/overture-stack/arranger/tree/main/modules/admin-ui/src/pages/"
    click CMPS "https://github.com/overture-stack/arranger/tree/main/modules/admin-ui/src/components/"
    click QRY "https://github.com/overture-stack/arranger/tree/main/modules/admin-ui/src/gql/queries/"
    click HTML "https://github.com/overture-stack/arranger/blob/main/modules/admin-ui/public/index.html"
    click LIBSRC "https://github.com/overture-stack/arranger/tree/main/modules/components/src/"
    click SB "https://github.com/overture-stack/arranger/tree/main/modules/components/.storybook/"
    click STORIES "https://github.com/overture-stack/arranger/tree/main/modules/components/stories/"
    click DC "https://github.com/overture-stack/arranger/blob/main/docker-compose.yml"
    click DF1 "https://github.com/overture-stack/arranger/blob/main/docker/Dockerfile.local"
    click DF2 "https://github.com/overture-stack/arranger/blob/main/docker/Dockerfile.jenkins"
    click JEN "https://github.com/overture-stack/arranger/tree/main/Jenkinsfile"
    click MAKE "https://github.com/overture-stack/arranger/tree/main/Makefile"
    click INT "https://github.com/overture-stack/arranger/tree/main/integration-tests/"

    classDef data fill:#ffd,stroke:#bb5,stroke-width:1px
    classDef backend fill:#dfd,stroke:#5b5,stroke-width:1px
    classDef frontend fill:#ddf,stroke:#55b,stroke-width:1px
    classDef library fill:#ddf,stroke:#55b,stroke-width:1px,stroke-dasharray: 5 5
    classDef ci fill:#eee,stroke:#999,stroke-width:1px
```
