---
title: "Architecture"
---

This document contains a description of Flower's expected user types,
naming, and C4 models. For design details of the Seedcase Project as a
whole, see the [Seedcase Design](https://design.seedcase-project.org)
documentation.

The purpose of this 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}

Flower has two main types of users: producers and consumers of a
[Data Package](https://datapackage.org/)'s metadata. They have different
goals and needs: one uses Flower to generate and manage the metadata,
while the other interacts with the generated documentation. While the
consumer might not directly use Flower, their experience and feedback to
the producer will influence how Flower is used and configured. Below we
describe both types and how they relate to Flower and its design.

### Producers

- **Owner**: This role is responsible and accountable for the Data
  Package by ensuring the metadata is accurate, complete, and up-to-date.
  They likely want more people to be aware of and use their Data
  Package, including their group, collaborators, and a wider external
  audience. They may use Flower themselves or delegate it to someone
  else to generate human-readable documents from the metadata. This role
  may not have much time or technical expertise to configure Flower, so
  they are likely to use Flower's default configurations, style, and
  templates.

- **Manager**: When distinct from the Owner, this role is responsible
  for managing, organising, and maintaining the Data Package, including
  how the metadata is structured, presented, and disseminated. They are
  primarily internal-facing: they serve the project team and act on
  instruction from the Owner, rather than targeting external audiences.
  Their scope covers the Data Package itself---structuring and
  controlling how the data and metadata are organised---not just the
  output Flower generates. Depending on their technical expertise, they
  may use Flower's defaults, make minor customisations, or create their
  own templates.

- **Communication or outreach lead**: This role is responsible for
  disseminating the Data Package to a wider, external audience, such as
  stakeholders, collaborators, or the general public. Unlike the
  Manager, they are external-facing: their scope is limited to the
  output Flower generates rather than the Data Package itself. As they
  are both producers and consumers of Flower's output, they use it to
  create materials that showcase the Data Package while also having
  opinions on how it looks and feels. They are likely to use Flower's
  default configurations, with some customisations for branding or other
  stylistic purposes.

### Consumers

- **Coordinator**: This role acts as a bridge between Flower's output
  and the end users of a Data Package, such as a research team or
  project collaborators. Their primary concern is access and
  discoverability: ensuring the documents generated by Flower are easy
  to find and use for the people they oversee. They are likely to give
  feedback to the Owner or Manager about how others are using the
  documents.

- **Communication or outreach lead**: This is the consumer counterpart
  to the producer role of the same name. Their primary concern is
  appearance and presentation: they are invested in how the documents
  generated by Flower look and feel, as they use them to showcase the
  Data Package to external audiences. Unlike the Coordinator, whose
  focus is on access and discoverability for internal users, this role
  cares about aesthetics and branding for external ones. Their feedback
  to the producer therefore tends to focus on style and visual design
  rather than structure or organisation.

- **Researcher or analyst**: This role uses the Data Package for their
  own research or analysis work. They use the documents generated by
  Flower to get an overview of the Data Package's contents to avoid
  having to examine the raw metadata themselves, and may give feedback
  on how the documents could better serve their analytical needs.

## Naming

The following naming scheme draws on terms from the
[Data Package standard](https://datapackage.org/).

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

```{mermaid}
%%| label: fig-c4-context
%%| fig-cap: "C4 system context diagram showing the anticipated users and external systems Flower interacts with."
flowchart TD

    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 lead<br>[person]")
    end

    subgraph Consumers
        user_communicator2("Communication or<br>outreach lead<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>[Python package]")

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

    datapackage --"Contains metadata"--> flower
    Producers --"Provide datapackage.json path<br>and optional config"--> flower
    flower --"Generates documentation"--> output
    Consumers --"Read documents 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 CLI, but its core
functionality is also available through the 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 TD

    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

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

    config --"Customises behaviour<br>and output"--> seedcase-flower
    templates --"Defines output<br>structure and layout"--> config
    user --"Provides datapackage.json path<br>programmatically"--> python
    user --"Provides datapackage.json path<br>via the CLI" --> cli
    user -."(Optional)<br>Provides configurations,<br>as file or Python class".-> config
    user -."(Optional)<br>Provides custom templates<br>in folder".-> templates
    seedcase-flower --"Generates documentation"--> output

    %% 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 both diagram
levels include classes, we combine the component and code levels into a
single diagram.

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

```{mermaid}
%%| label: fig-c4-component
%%| fig-cap: "C4 component diagram showing the main functions and classes within the Python package and their connections."
flowchart TD

    subgraph package["Core Python Package"]

        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]")
    subgraph output["Output"]
        output_files("Human-readable metadata<br>[files and folders]")
        output_screen("Human-readable metadata<br>[terminal output]")
    end

    user --"Provides datapackage.json path<br>programmatically"--> read_properties
    user -."(Optional)<br>Provides configurations,<br>as file or Python class".-> cfg
    user -."(Optional)<br>Provides custom templates<br>in folder".-> templates
    templates --"Defines output<br>structure and layout"--> cfg
    build --"Generates output files"--> output_files
    view --"Generates terminal output"--> output_screen

    %% Styling
    style package fill:#FFFFFF, color:#000000
    style output 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).
