Penpot Data Model #
This is the conceptual data model. The actual representations of those entities slightly differ, depending on the environment (frontend app, backend RPC calls or the SQL database, for example). But the concepts are always the same.
The diagrams use basic UML notation with PlantUML.
Users, teams and projects #
Profile holds the personal info of any user of the system. Users belongs to
Teams and may create
Projects inside them.
Inside the projects, there are
Files. All users of a team may see the projects
and files inside the team. Also, any project and file has at least one user that
is the owner, but may have more relationships with users with other roles.
Files may use other files as shared
The main content of the file is in the "file data" attribute (see next section). But there are some objects that reside in separate entities:
StorageObjectrepresents a file in an external storage, that is embedded into a file (currently images and SVG icons, but we may add other media types in the future).
Commentsare the comments that any user may add to a file.
ShareLinkcontains a token, an URL and some permissions to share the file with external users.
File data #
The data attribute contains the
Pages and the library assets in the file
The lists of pages and assets are modelled also as entities because they have a lot of functions and business logic.
Pages and components #
Components contains a tree of shapes, and share many
functions and logic. So, we have modelled a
Container entity, that is an
abstraction that represents both a page or a component, to use it whenever we
have code that fits the two.
ShapeTree represents a set of shapes that are hierarchically related: the top
frame contains top-level shapes (frames and other shapes). Frames and groups may
contain any non frame shape.
Shape is the most important entity of the model. Represents one of the
layers of our design, and it
corresponds with one SVG node, augmented with Penpot special features.
We have code to render a
Shape into a SVG tag, with more or less additions
depending on the environment (editable in the workspace, interactive in the
viewer, minimal in the shape exporter or the handoff, or with metadata in the
Also have code that imports any SVG file and convert elements back into shapes. If it's a SVG exported by Penpot, it reads the metadata to reconstruct the shapes exactly as they were. If not, it infers the atributes with a best effort approach.
In addition to the identifier ones (the id, the name and the type of element), a shape has a lot of attributes. We tend to group them in related clusters. Those are the main ones:
Selrectand other geometric attributes (x, y, width, height...) define the position in the diagram and the bounding box.
Transformis a 2D transformation matrix to rotate or stretch the shape.
Constraintsexplains how the shape changes when the container shape resizes (kind of "responsive" behavior).
Interactionsdescribe the interactive behavior when the shape is displayed in the viewer.
Fillcontains the shape fill color and options.
Strokecontains the shape stroke color and options.
Shadowcontains the shape shadow options.
Blurcontains the shape blur options.
Fontcontains the font options for a shape of type text.
Contentcontains the text blocks for a shape of type text.
Exportsare the defined export settings for the shape.
Also a shape contains a reference to its containing shape (parent) and of all the children.