Architecture

This document contains the architectural design for Flower. For design details of the Seedcase Project as a whole, see the Seedcase Design documentation.

The purpose of this description is to ensure that the team shares a common understanding about the implementation and to outline the design to anyone else interested in the internal workings of the package.

User types

This section describes the different users we expect and design for. Flower has two main types of users: producers and consumers of the metadata of a Data Package. They have different goals and needs when using Flower or interacting with docs generated by it. While the consumer might not directly use Flower, their experience and feedback to the producer will influence how Flower is used and configured, which is important for the producers to consider. So we describe both types and how they relate to Flower and its design.

Producers

Owner: This person or role is the one responsible and accountable for the Data Package’s metadata. Their tasks might be to ensure that the metadata is accurate, complete, and up-to-date. They may act as a coordinator for the project that is structured as a Data Package. They may also be responsible for maintaining the Data Package itself, or at least overseeing tasks that need to be done. They likely want more people to use their Data Package, so will use or assign someone to use Flower to generate the metadata into something that their group or collaborators can easily look through to better understand the Data Package. This person may not have much time or technical expertise to configure Flower or the output, so will likely use Flower’s default configurations, style, and templates.
Manager: This person or role, when distinct from the Owner, is responsible for managing, organising, and maintaining the Data Package, including how the metadata is structured and ultimately presented and disseminated. They may be responsible for structuring how the metadata is presented to the consumers, so will likely use Flower to generate the output, potentially based on feedback and instruction from the Owner. They may have some technical expertise, though not necessarily too much. They will likely be quite busy with other management tasks, so will likely use Flower’s default configurations, style, and templates. However, they may also be interested in or instructed to customise the output to match the project’s branding or other content-specific needs. In this case, they might do some small customisations to Flower’s configurations and final output.
Communication or outreach: This person or role is responsible for disseminating the Data Package’s metadata to a wider audience, such as stakeholders, collaborators, or the general public. They could be both producer and consumer. They may be involved in creating reports, presentations, or other materials that showcase the Data Package and its contents. They will likely use Flower to generate the output, potentially with some customisations to match the project’s branding or for other stylistic purposes. They may have some technical expertise, but not necessarily too much. They will likely be quite busy with other communication tasks, and so use Flower’s default configurations, style, and templates where possible.

Consumers

Coordinator: This person or role is responsible for coordinating the use of the Data Package among a group of users, such as a research team or project collaborators. They will be responsible for ensuring that the docs generated by Flower are accessible and easy to find for the people they are overseeing or coordinating. They will also likely be giving feedback and advice to the Owner or Manager about how others are using the docs for the Data Package. Their main use case for Flower is to simplify their work of coordinating the use of the Data Package, as they can direct people to the docs rather than having to examine the raw metadata themselves.
Communication or outreach: This is the same as the producer role, but from the consumer perspective. They will be invested in showing a nicely designed and aesthetically pleasing website or documentation of the Data Package to others. So they will have opinions and feedback on how the docs generated by Flower look and feel, which will influence how the producer configures and uses Flower.
Researcher or analyst: This person or role will be using the Data Package for their research or analysis work. They will be interested in understanding the contents of the Data Package to better inform that work. They will likely use the docs generated by Flower to get an overview of the Data Package and its metadata, rather than examining the raw metadata themselves. Their main use case for Flower is to obtain clear, concise, and well-organised documentation that helps them quickly understand the Data Package and its contents. If they are part of the group that owns the Data Package, they may also provide feedback on how the docs could be improved to better meet their needs.

Naming

This section contains a naming scheme for Flower that incorporates terms used in the Data Package standard. The main objects and actions used throughout the package can be found in the tables below.

Objects used throughout Flower.
Object	Description
package	A Data Package that contains a collection of related data resources and descriptor(s).
descriptor	A standalone and complete metadata structure contained in a JSON file, for example, in `datapackage.json`.
properties	Metadata fields (name-value pairs) of a descriptor loaded as a Python dictionary. This can be a subset of the original descriptor or the entire structure.
config	An object containing settings for modifying the behaviour and output of Flower, e.g., output format, template paths, or style.
section	A configuration unit that defines an output path and a list of metadata items to render at that path.
template	A Jinja file that defines the structure, layout, and format for rendering a metadata item.
style	A name for a set of templates that defines a coherent look and structure for the output, e.g., `quarto-one-page` or `quarto-resource-listings`.

Actions that Flower can perform.
Action	Description
build	Generate structured, human-readable output from a Data Package’s properties using the configuration and templates.
view	Output a Data Package’s properties as human-readable text for terminal output, similar to the Unix `man` command.
read	Read various files, such as a Data Package descriptor (the properties) or a configuration file.

C4 Models

This section contains the C4 Models for Flower. The C4 Model is an established visualisation approach to describe the architecture of a software system. It breaks the system down into four levels of architectural abstraction: system context, containers, components, and code.

System context

The system context diagram shows the users and external systems that interact with Flower.

The users, described in the User types section, provide Flower with their Data Package’s metadata to convert it into structured, human-readable documents.

flowchart LR

    subgraph Users
        Producers["Producer users"]
        Consumers["Consumer users"]
    end

    subgraph Producers
        user_owner("Owner<br>[person]")
        user_manager("Manager<br>[person]")
        user_communicator1("Communication or<br>outreach<br>[person]")
    end

    subgraph Consumers
        user_communicator2("Communication or<br>outreach<br>[person]")
        user_coordinator("Coordinator<br>[person]")
        user_researcher("Researcher or<br>analyst<br>[person]")
    end

    datapackage("Data Package<br>[datapackage.json]")
    flower("seedcase-flower<br>[CLI]")

    output("Human-readable<br>[files and folders]")

    datapackage --"Contains metadata"--> flower
    Producers --"Gives Data Package"--> flower
    flower --"Generates docs"--> output
    Consumers --"Uses docs to understand<br>Data Package contents"--> output

    %% Styling
    style Producers fill:#FFFFFF, color:#000000
    style Consumers fill:#FFFFFF, color:#000000
    style Users fill:#FFFFFF, color:#000000

Figure 1: C4 system context diagram showing the anticipated users and external systems Flower interacts with.

Container

In C4, a container diagram zooms in on the system boundary to show the containers within it, such as web applications or databases. This diagram displays the main containers of Flower, their responsibilities, and how they interact, including the technologies used for each.

Flower is primarily designed for use as a command-line interface (CLI), with its core functionality also exposed as a Python API.

flowchart

    user("User<br>[person]")
    config("Config<br>[toml]")
    templates("Templates<br>[folder with<br>Jinja files]")

    subgraph "seedcase-flower"
        python("Core Python Package<br>[Python, Jinja]")
        cli("CLI<br>[Python]")

        python -- "Provides<br>functionality" --> cli
    end

    config --"Customises behaviour<br>and output"--> seedcase-flower
    templates --"Defines output<br>structure and layout"--> config
    user --"Renders Data Package<br>properties programmatically"--> python
    user -- "Renders Data Package<br>properties via the CLI" --> cli

    %% Styling
    style seedcase-flower fill:#FFFFFF, color:#000000

Figure 2: C4 container diagram showing the core Python package in Flower and the command line interface.

Component/code

In the diagram below, we zoom in on the core Python package container to show its internal components. In C4, a component is “a grouping of related functionality encapsulated behind a well-defined interface”, like a class or a module, while code is the basic building blocks, such as classes and functions.

Because the core Python package is relatively small and simple, and because both component and code diagrams include classes, we combine the component and code levels of the C4 model into a single diagram as shown below. This diagram shows the main classes and functions within the core Python package.

flowchart

    subgraph python_package["Core Python Package"]

        subgraph config_file["Configuration"]
            config("Config<br>[class]")
            section("Section<br>[class]")
        end

        read_config["read_config()<br>[function]"]
        read_json["read_json()<br>[function]"]
        build("build()<br>[function]")
        view("view()<br>[function]")

        section --"Lists metadata<br>items to include"--> config
        config_file -- "Provides build<br>configurations" --> read_config

        read_json --"Provides properties<br>as dict"--> build & view
        read_config -- "Adds build<br>configurations" --> build
        config --"Adds build<br>configurations"--> build & view
    end

    templates("Templates<br>[folder with<br>Jinja files]")
    user("User<br>[person]")
    output_files("Output<br>[files and<br>folders]")
    output_screen("Output<br>[text in the Terminal]")

    templates --"Provides output<br>structure and layout"--> config
    user --"Provides datapackage.json<br>to build"--> read_json
    user --"Provides configurations,<br>as file or Python class<br>(optional)"--> config_file
    user --"Provides templates<br>in folder<br>(optional)"--> templates
    build --"Populates template(s)<br>with metadata items"--> output_files
    view --"Displays output<br>to screen"--> output_screen

    %% Styling
    style python_package fill:#FFFFFF, color:#000000
    style config_file fill:#FFFFFF, color:#000000, stroke-dasharray: 5 5

Figure 3: C4 component diagram showing the parts of the Python package and their connections.

For more details on the individual classes and functions, see the interface documentation and the reference documentation.