export:puml

Generate PlantUML diagrams from the active product’s feature model, database models, dependencies, and Docker topology.

Table of contents

1. Usage
2. Diagram modes
3. Output options
4. Examples
5. Feature model (default)
6. Class diagram (--classes)
   1. Example output
7. Dependency graph (--deps)
8. Deployment diagram (--deployment)
9. UVL resolution
10. Refinement mixins
11. Error reporting
12. Requirements
13. See also

---

Usage

splent export:puml [OPTIONS]

Diagram modes

By default, export:puml generates a feature model diagram. Use flags to select other modes:

Flag	Diagram	What it shows
(none)	Feature model	Components with contracts (routes, models, services, hooks, env vars) + UVL constraints
--classes	UML class diagram	SQLAlchemy models with attributes, types, PKs, unique, nullable, methods, FK relationships with cardinality
--deps	Dependency graph	Clean feature nodes (colored by mandatory/optional) + requires arrows
--deployment	Docker deployment	Containers, images, ports, volumes, networks, and dependencies

Output options

Option	Description
--pdf	Also export as PDF (requires PlantUML + rsvg-convert)
--png	Also export as PNG
--svg	Also export as SVG
-o PATH	Custom output path (without extension)

Files are saved to <product>/exports/puml/ by default.

Examples

# Feature model (default)
splent export:puml

# Class diagram as PDF
splent export:puml --classes --pdf

# Dependency graph as PNG
splent export:puml --deps --png

# Docker deployment as SVG
splent export:puml --deployment --svg

# All formats at once
splent export:puml --classes --pdf --png --svg

# Custom output path
splent export:puml --classes -o docs/diagrams/models --pdf

Feature model (default)

Generates a component diagram showing all features declared in pyproject.toml with their:

• Cardinality: mandatory or optional (from UVL)
• Contract details: routes, blueprints, models, services, hooks, docker, env vars (from [tool.splent.contract] in each feature’s pyproject.toml)
• Dependencies: requires arrows between features (from UVL constraints)

splent export:puml

Output: exports/puml/<product>.puml

Class diagram (--classes)

Parses models.py from each feature and generates a UML class diagram with:

• Classes grouped by feature (as <<Feature>> packages)
• Attributes: name, type (int, str, datetime, bool), stereotypes (<<PK>>, <<unique>>), nullable (?)
• Methods: public methods extracted from the model class
• Relationships: foreign keys with cardinality ("1" -- "1" or "1" -- "*") — detected from db.ForeignKey and db.relationship (handles both quoted and unquoted target names)

splent export:puml --classes

Output: exports/puml/<product>_classes.puml

Example output

package "auth" <<Feature>> {
  class User {
    + id : int <<PK>>
    + email : str? <<unique>>
    + password : str
    + created_at : datetime
    + active : bool
    ..
    + set_password()
    + check_password()
  }
}

package "profile" <<Feature>> {
  class UserProfile {
    + id : int <<PK>>
    + user_id : int <<unique>>
    + name : str
    + surname : str
  }
}

User "1" -- "1" UserProfile : profile

Dependency graph (--deps)

A clean, minimal diagram showing only feature nodes and dependency arrows. Features are color-coded:

• Dark blue (#2E86C1): mandatory features
• Light blue (#AED6F1): optional features

splent export:puml --deps

Output: exports/puml/<product>_deps.puml

Deployment diagram (--deployment)

Reads all docker-compose.yml files (product + features + CLI) and generates a deployment diagram showing:

• Containers with appropriate shapes:
  • node for application containers
  • database for MariaDB/MySQL/PostgreSQL
  • storage for Redis
  • collections for mail services (MailHog)
• Ports: host:container mappings
• Dependencies: depends_on relationships
• Named volumes: persistent data volumes

splent export:puml --deployment

Output: exports/puml/<product>_deployment.puml

UVL resolution

The command resolves the UVL model using the SPL catalog first. It reads [tool.splent].spl from the product’s pyproject.toml and looks for the UVL file at splent_catalog/{spl_name}/{spl_name}.uvl.

If no SPL catalog entry is found, it falls back to the legacy [tool.splent.uvl].file configuration.

---

Refinement mixins

When generating class diagrams (--classes), features that declare [tool.splent.refinement].extends.models in their pyproject.toml are handled specially. Mixin classes (classes defined without explicit base classes) are detected and their attributes and methods are merged into the target model in the diagram. This means the class diagram reflects the fully composed model, not the raw source files.

---

Error reporting

When PlantUML fails to render a diagram, the actual PlantUML error output (stderr and stdout) is displayed directly, making it easier to diagnose syntax issues in the generated .puml file.

---

Requirements

• PlantUML: Required for --pdf, --png, --svg rendering. Installed in the CLI Docker container.
• rsvg-convert: Required for PDF/PNG conversion from SVG. Part of librsvg2-bin in the CLI container.
• UVL file: Must be configured via [tool.splent].spl (SPL catalog, preferred) or [tool.splent.uvl].file (legacy) in the product’s pyproject.toml.
• Feature contracts: For full detail in the feature model, features should have [tool.splent.contract] in their pyproject.toml (auto-generated by feature:release).

See also

• product:validate — Validate the UVL model
• feature:contract — Infer and write feature contracts
• product:validate — Check for conflicts between features