---
title: "Architecture"
---

This document contains the architectural design for Flower. For design
details of the Seedcase Project as a whole, see the
[Seedcase Design](https://design.seedcase-project.org) 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 {#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](https://datapackage.org/). The main
objects and actions used throughout the package can be found in the
tables below.

| 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`.            |

: Objects used throughout Flower.

| 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.                    |

: Actions used within Flower, including the CLI commands and Python API functions.

## C4 Models

This section contains the [C4 Models](https://c4model.com/) 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](#user-types) section, provide
Flower with their Data Package's metadata to convert it into structured,
human-readable documents.

```{mermaid}
%%| label: fig-c4-context
%%| fig-cap: "C4 system context diagram showing the anticipated users and external systems Flower interacts with."
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
```

### Container

In C4, a [container diagram](https://c4model.com/diagrams/container)
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.

```{mermaid}
%%| label: fig-c4-container
%%| fig-cap: "C4 container diagram showing the core Python package in Flower and the command line interface."
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
```

### Component/code

In the diagram below, we zoom in on the core Python package container to
show its internal components. In C4, a
[component](https://c4model.com/abstractions/component) is "a grouping
of related functionality encapsulated behind a well-defined interface",
like a class or a module, while
[code](https://c4model.com/abstractions/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
Python package that represents the CLI.

<!-- TODO: Switch to using a Properties class instead of dict? -->

```{mermaid}
%%| label: fig-c4-component
%%| fig-cap: "C4 component diagram showing the parts of the Python package that contribute to the CLI and their connections."
flowchart TB
    subgraph package["Python code"]
        subgraph cfg["Configuration"]
            config("Config<br>[class]")
            section("Section<br>[class]")
        end

        read_properties["read_properties()<br>[function]"]
        properties["properties<br>[dict]"]
        build("build()<br>[function]")
        view("view()<br>[function]")

        read_properties --> properties
        properties --> build & view
        cfg --> build & view
    end

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

    user --"Gives<br>datapackage.json"--> read_properties
    user --"Gives templates<br>in folder<br>(optional)"--> templates
    user --"Gives configurations,<br>as file, Python classes,<br>or from CLI<br>(optional)"--> config
    templates --"Sets output<br>structure and layout"--> section
    build --"Populates template(s)<br>with metadata items"--> output_files
    view --"Displays output<br>to screen"--> output_screen

    %% Styling
    style package fill:#FFFFFF, color:#000000
    style cfg fill:#FFFFFF, color:#000000, stroke-dasharray: 5 5
```

For more details on the individual classes and functions, see the
[interface documentation](/docs/design/interface/index.qmd) and the
[reference documentation](/docs/reference/index.qmd).
