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
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 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
Flower has two main types of users: producers and consumers of a Data Package’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.
| 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. |
| 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.
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 CLI, but its core functionality is also available through the Python API.
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 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 both diagram levels include classes, we combine the component and code levels into a single diagram.
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 and the reference documentation.