# metosin/oksa architecture

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

- Interactive diagram: https://gitdiagram.com/metosin/oksa
- Repository: https://github.com/metosin/oksa

## Overview

##### Project’s Purpose and Type
- Project Purpose: It is a library that converts Clojure data structures into GraphQL query strings. The README shows extensive examples that cover queries, mutations, subscriptions, fragments, variables, directives, and more. This makes it a domain-specific, data-driven library that abstracts GraphQL syntax.
- Target Environments: The project is designed for use in Clojure, ClojureScript, and babashka. There are example projects (e.g., “examples/apollo-cljs” and “examples/babashka”) that show integration with front-end applications and script-based use cases.

##### Main Components
a. Core Library Components (inside the “src/oksa” directory):
- Core Functionality: Files such as core.cljc, parse.cljc, and unparse.cljc implement the main logic for transforming Clojure data structures into GraphQL queries.
- API Layer: The “alpha” subdirectory (with files like api.cljc and protocol.cljc) represents an experimental or extended API that provides a programmatic API for building selections, fragments, variables, etc.
- Utility Functions: Utility functions (in util.cljc) support common operations.

b. Examples and Integration Layers:
- Examples: The “examples” folder contains projects that show how to use the library in diverse environments (e.g., apollo-cljs for front-end integration and a babashka script example). Represent these as client applications that utilize the “oksa” library.

c. Testing & Build/Infrastructural Components:
- Automated Testing: The “test” directory contains tests for the library (unit tests in various subdirectories). Also note the “tests.edn” file that likely controls test configurations.
- Build and Deployment: Build configuration files such as deps.edn, bb.edn, build.clj and package-related files (package.json, package-lock.json) indicate multiple build environments and packaging targets.
- CI/CD Pipelines: The .github/workflows directory shows GitHub Actions workflows for Clojure, generating tests, and release management. This component ensures continuous integration and automated releases.

##### Relationships and Interactions
- The core library (represented by the “src/oksa” package) is the heart. It interacts with:
- User code (via examples and documentation) where clients (Clojure/ClojureScript/babashka code) call the public API.
- Testing framework (tests directory and build scripts) which validates that the transformation from Clojure data structures to GraphQL string output meets the spec.
- CI/CD pipelines (GitHub workflows) that are triggered to build, test, and release the library.
- “Client Applications” (using examples) invoking functions from “oksa core and API.”
- “Test/Build Systems” feeding back into development by running validations based on updates in “src.”
- “CI/CD Pipelines” orchestrating deployment of releases using build scripts and configuration files.

##### Architectural Patterns and Design Principles
- Data-Driven Transformation: The entire purpose is to translate data structures into query strings, so emphasize a “transformation pipeline” starting from structured data to a GraphQL string.
- Modularity: The separation between core functions, extended/alpha API functions, and utilities highlights modularity.
- Testing and Continuous Integration: Use of distinct test directories, workflow scripts, and multiple environment builds exhibits best practices in software engineering.
- Platform Agnostic Design: Despite platform-specific examples, the design remains agnostic to many environments.

## Diagram (Mermaid)

```mermaid
graph TD
    DDATA["Clojure Data Structure"]:::input

    subgraph "Client Applications"
        AP["Apollo-cljs Example"]:::example
        BB["Babashka Example"]:::example
    end

    subgraph "oksa Core (src/oksa)"
        CF["Core Functionality (core.cljc)"]:::core
        PS["Parsing (parse.cljc)"]:::core
        UP["Unparsing (unparse.cljc)"]:::core
        AL["API / Alpha Layer (src/oksa/alpha)"]:::core
        UT["Utility Functions (util.cljc)"]:::core
    end

    QO["GraphQL Query String Output"]:::output

    subgraph "Testing & Build Infrastructure"
        subgraph "Testing Suite"
            T["Test Directory (test/)"]:::infra
            TS["Test Config (tests.edn)"]:::infra
        end
        subgraph "Build Scripts & Configs"
            BL["build.clj"]:::infra
            DFILE["deps.edn"]:::infra
            BBE["bb.edn"]:::infra
            PKG["package.json"]:::infra
            PKGLK["package-lock.json"]:::infra
        end
        CI["CI/CD Pipelines (.github/workflows)"]:::infra
    end

    DDATA -->|"transforms"| CF
    AP -->|"calls"| CF
    BB -->|"calls"| CF
    CF -->|"generates"| QO

    T ---|"validates"| CF
    TS ---|"configures"| CF
    CI -->|"triggers"| BL
    BL -->|"builds"| CF

    CF --- PS
    CF --- UP
    CF --- AL
    CF --- UT

    classDef core fill:#E0BBE4,stroke:#333,stroke-width:2px;
    classDef example fill:#FFDFD3,stroke:#333,stroke-width:2px;
    classDef infra fill:#C1E1C1,stroke:#333,stroke-width:2px;
    classDef input fill:#FFEB99,stroke:#333,stroke-width:2px;
    classDef output fill:#B3E5FC,stroke:#333,stroke-width:2px;

    click CF "https://github.com/metosin/oksa/blob/main/src/oksa/core.cljc"
    click PS "https://github.com/metosin/oksa/blob/main/src/oksa/parse.cljc"
    click UP "https://github.com/metosin/oksa/blob/main/src/oksa/unparse.cljc"
    click AL "https://github.com/metosin/oksa/tree/main/src/oksa/alpha"
    click UT "https://github.com/metosin/oksa/blob/main/src/oksa/util.cljc"
    click AP "https://github.com/metosin/oksa/tree/main/examples/apollo-cljs"
    click BB "https://github.com/metosin/oksa/tree/main/examples/babashka"
    click T "https://github.com/metosin/oksa/tree/main/test"
    click TS "https://github.com/metosin/oksa/blob/main/tests.edn"
    click BL "https://github.com/metosin/oksa/blob/main/build.clj"
    click DFILE "https://github.com/metosin/oksa/blob/main/deps.edn"
    click BBE "https://github.com/metosin/oksa/blob/main/bb.edn"
    click PKG "https://github.com/metosin/oksa/blob/main/package.json"
    click PKGLK "https://github.com/metosin/oksa/blob/main/package-lock.json"
    click CI "https://github.com/metosin/oksa/tree/main/.github/workflows"
```
