# toml-f/jonquil architecture

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

- Interactive diagram: https://gitdiagram.com/toml-f/jonquil
- Repository: https://github.com/toml-f/jonquil

## Overview

##### Project Type and Purpose
- Jonquil is a specialized Fortran library that provides JSON parsing functionality by building on top of the TOML Fortran ecosystem. Its purpose is to offer a compatibility layer allowing libraries built for TOML to process JSON data, essentially “bringing TOML blooms to JSON land.”
- The README clearly outlines that the library implements a JSON lexer and serializer while reusing components of TOML Fortran. It is a niche tool (and not a full-stack web application) intended for scientific, engineering, or legacy code bases where Fortran is used.

##### Analyzing the File Structure
- Top-Level Files and Directories:
- Build configuration files for multiple build systems (meson.build, CMakeLists.txt, fpm.toml) indicate that the project must support diverse Fortran build frameworks.
- The "src" directory is the core of the library, containing several Fortran files (for lexer, parser, serialization, and version information) that encapsulate the main functionality.
- The "config" directory includes additional build and configuration scripts (including CMake scripts and Meson files) meant for discovering dependencies and configuring the build.
- A "test" directory indicates that there is a unit testing layer (with Fortran test files, again with both CMake and meson build configurations) that verifies the functionality of the components.
- The "subprojects" directory holds dependencies (wrapped libraries like test-drive and toml-f), which shows that Jonquil leverages externally maintained modules.

##### Main Architectural Components
- Core Library (src):
- Components include a JSON lexer (lexer.f90), a JSON parser (parser.f90), and a JSON serializer (ser.f90). These form the key functionality of Jonquil.
- Build & Integration Interfaces:
- Build configurations for meson, CMake, and the fpm manifest show that integration with external projects is emphasized. The instructions in the README detail how to use these systems.
- Configuration and Dependency Management:
- The "config" directory contains helper scripts (e.g., Findtest-drive.cmake, Findtoml-f.cmake) that support build-time dependency discovery and integration.
- Testing Framework:
- The "test" directory, including unit tests (main.f90, test_lexer.f90), serves to ensure the integrity of key functionalities of the library.
- External Dependencies (Subprojects):
- The external dependencies included as subprojects (like toml-f) are essential for both the TOML and JSON processing capabilities.

##### Relationships and Interactions
- The core library in the "src" folder interfaces with the configuration system during build time; it uses the scripts in the "config" directory to incorporate dependencies.
- External libraries from the "subprojects" directory complement the internal functionality (providing TOML processing support).
- The tests (in the "test" directory) are designed to validate the behavior of core components, ensuring accuracy of the lexer, parser, and serializer.
- Build systems (meson, CMake, fpm) act as the orchestration layer, managing compilation, testing, and installation flows.

##### Architectural Patterns and Design Principles
- Modularity: Clear separation between core logic (in src) and ancillary components (config, tests, subprojects).
- Multi-platform Build Support: Through meson, CMake, and fpm, the design supports diverse Fortran build environments.
- Compatibility Layer: The design emphasizes a compatibility layer where JSON components work interchangeably with components from TOML Fortran.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Systems Layer
    BS1["Meson Build System"]:::buildsys
    BS2["CMake Build System"]:::buildsys
    BS3["FPM Build System"]:::buildsys

    %% Build & Integration: Top-Level Build Configurations
    subgraph "Top-Level Build Configurations"
        TL1["CMakeLists.txt"]:::build
        TL2["meson.build"]:::build
        TL3["fpm.toml"]:::build
    end

    %% Build & Integration: Configuration Scripts
    subgraph "Configuration Scripts"
        CS1["config/meson.build"]:::build
        CS2["config/CMakeLists.txt"]:::build
        CS3["config/cmake/Findtest-drive.cmake"]:::build
        CS4["config/cmake/Findtoml-f.cmake"]:::build
        CS5["config/template.cmake"]:::build
        CS6["config/template.pc"]:::build
        CS7["config/install-mod.py"]:::build
    end

    %% Core Library Layer
    subgraph "Core Library (src)"
        CL1["JSON Lexer"]:::core
        CL2["JSON Parser"]:::core
        CL3["JSON Serializer"]:::core
        CL4["Version Information"]:::core
        CL5["Main Library Interface"]:::core
    end

    %% Testing Framework Layer
    subgraph "Test Build Configurations"
        TBC1["test/CMakeLists.txt"]:::test
        TBC2["test/meson.build"]:::test
        TBC3["test/unit/CMakeLists.txt"]:::test
        TBC4["test/unit/meson.build"]:::test
    end

    subgraph "Unit Tests"
        UT1["test/unit/main.f90"]:::test
        UT2["test/unit/test_lexer.f90"]:::test
    end

    %% External Dependencies Layer
    subgraph "External Dependencies"
        ED1["Test Drive Dependency"]:::external
        ED2["TOML Fortran Dependency"]:::external
    end

    %% Connections from Build Systems to Top-Level Build Configurations
    BS1 -->|"triggers"| TL2
    BS2 -->|"triggers"| TL1
    BS3 -->|"triggers"| TL3

    %% Connections from Top-Level Build Configurations to Configuration Scripts
    TL1 -->|"uses"| CS2
    TL2 -->|"uses"| CS1
    TL3 -->|"uses"| CS7

    %% Connections from Configuration Scripts to Core Library
    CS1 -->|"configures"| CL1
    CS2 -->|"configures"| CL5
    CS3 -->|"discovers"| CL2
    CS4 -->|"discovers"| CL3
    CS5 -->|"templates"| CL4
    CS6 -->|"templates"| CL4

    %% Core Library Validation with Testing Framework
    CL1 -->|"validated_by"| TBC1
    CL2 -->|"validated_by"| TBC2
    CL3 -->|"validated_by"| TBC3
    CL5 -->|"validated_by"| UT1

    %% Core Library interaction with External Dependencies
    CL2 -->|"integrates"| ED1
    CL3 -->|"integrates"| ED2

    %% Connections from Core Library to Unit Tests (for detailed behavior tests)
    CL1 -->|"tested_by"| UT2

    %% Click Events - Core Library
    click CL1 "https://github.com/toml-f/jonquil/blob/main/src/jonquil/lexer.f90"
    click CL2 "https://github.com/toml-f/jonquil/blob/main/src/jonquil/parser.f90"
    click CL3 "https://github.com/toml-f/jonquil/blob/main/src/jonquil/ser.f90"
    click CL4 "https://github.com/toml-f/jonquil/blob/main/src/jonquil/version.f90"
    click CL5 "https://github.com/toml-f/jonquil/blob/main/src/jonquil.f90"

    %% Click Events - Top-Level Build Configurations
    click TL1 "https://github.com/toml-f/jonquil/blob/main/CMakeLists.txt"
    click TL2 "https://github.com/toml-f/jonquil/blob/main/meson.build"
    click TL3 "https://github.com/toml-f/jonquil/blob/main/fpm.toml"

    %% Click Events - Configuration Scripts
    click CS1 "https://github.com/toml-f/jonquil/blob/main/config/meson.build"
    click CS2 "https://github.com/toml-f/jonquil/blob/main/config/CMakeLists.txt"
    click CS3 "https://github.com/toml-f/jonquil/blob/main/config/cmake/Findtest-drive.cmake"
    click CS4 "https://github.com/toml-f/jonquil/blob/main/config/cmake/Findtoml-f.cmake"
    click CS5 "https://github.com/toml-f/jonquil/blob/main/config/template.cmake"
    click CS6 "https://github.com/toml-f/jonquil/blob/main/config/template.pc"
    click CS7 "https://github.com/toml-f/jonquil/blob/main/config/install-mod.py"

    %% Click Events - Testing Framework
    click TBC1 "https://github.com/toml-f/jonquil/blob/main/test/CMakeLists.txt"
    click TBC2 "https://github.com/toml-f/jonquil/blob/main/test/meson.build"
    click TBC3 "https://github.com/toml-f/jonquil/blob/main/test/unit/CMakeLists.txt"
    click TBC4 "https://github.com/toml-f/jonquil/blob/main/test/unit/meson.build"
    click UT1 "https://github.com/toml-f/jonquil/blob/main/test/unit/main.f90"
    click UT2 "https://github.com/toml-f/jonquil/blob/main/test/unit/test_lexer.f90"

    %% Click Events - External Dependencies
    click ED1 "https://github.com/toml-f/jonquil/blob/main/subprojects/test-drive.wrap"
    click ED2 "https://github.com/toml-f/jonquil/blob/main/subprojects/toml-f.wrap"

    %% Styles
    classDef core fill:#ffe0e0,stroke:#c0392b,stroke-width:2px;
    classDef build fill:#e0f7ff,stroke:#2980b9,stroke-width:2px;
    classDef test fill:#e0ffe0,stroke:#27ae60,stroke-width:2px;
    classDef external fill:#fff7e0,stroke:#f39c12,stroke-width:2px;
    classDef buildsys fill:#f0e68c,stroke:#d4ac0d,stroke-width:2px;
```
