Data Model
This page maps the Smart EPD entity hierarchy and explains how the core objects relate to each other. Understanding this model is essential for API integrators and anyone working with Smart EPD data programmatically.
Entity hierarchy
Smart EPD organizes data through a strict containment hierarchy. Each level constrains the next:
EPD type progression
EPDs under a project can follow one of two paths. Every EPD begins life as a standard draft. From there, it can be submitted and approved on its own (standalone path), or it can be morphed into a reference EPD, which locks a modeling envelope and then serves as the parent for zero or more variant EPDs.
The standalone and reference paths are mutually exclusive per EPD: once an EPD is morphed to reference, it cannot become standard again, and variants always belong to exactly one reference.
Platform layer
Organization
A company or entity on the platform. Every user belongs to exactly one organization, and every action traces back to one.
| Attribute | Description |
|---|---|
| Name | Company name |
| Type | manufacturing_group, tool_provider, consultant, or verifier |
| Members | Users with roles (admin or user) |
| Parent org | Self-referential link for corporate hierarchy (e.g., subsidiaries under a parent group) |
| Partner orgs | Explicit one-way links to other organizations for collaboration, tracked via a PartnerOrganization record with its own active / revoked status |
Organizations can also receive scoped OrgAccessGrant records, which grant a partner organization access to a specific workspace, PCC, or project.
Workspace
A collaboration space where organizations work together. One workspace per engagement.
| Attribute | Description |
|---|---|
| Name | Engagement name (e.g., "Acme 2025 EPDs") |
| Primary organization | The reporting org this workspace was created for |
| Status | draft → active → archived |
| Organization memberships | Each org has a role: reporting_organization, tool_provider, or member |
| User memberships | Individual users get workspace-level roles: admin, editor, or viewer |
| PCCs | Product Category Configurations within this workspace |
When an organization joins a workspace, all of its current members automatically receive viewer-level access. Users added to the org later are not auto-enrolled — they must be invited explicitly. Individual users can be elevated to editor or admin.
Consultant and verifier relationships are expressed at the organization type level (org_type), not as workspace roles. Workspace membership only distinguishes the reporting org, the tool provider, and general members for access-control purposes.
PCC (Product Category Configuration)
The governance layer, defining how a product category's EPDs are created and verified. Exposed in the UI as a "Category" and in frontend routes as /category/:id, but the backend model is named PCC.
| Attribute | Description |
|---|---|
| Name | Product category label (e.g., "Ready-Mixed Concrete") |
| PCR Spec | Which Product Category Rules specification governs this PCC |
| Tool | For tool-based modes, the selected LCA tool. The tool's allows_reference_epds flag determines whether projects under this PCC can create reference/variant EPDs. |
| Tool version | Version string of the selected tool |
| Status | draft → active → archived |
Product layer
Project
A concrete product assessment. The central hub for all EPD work.
| Attribute | Description |
|---|---|
| Name | Product being assessed |
| PCC | Parent Product Category Configuration (governs rules, tool, verifier) |
| Status | draft → retired |
| Sequence ID | Auto-incremented identifier assigned on first EPD publish, used in declaration numbers |
| Reporting owner metadata | Optional declaration-owner details (name, phone, address, website, email) captured at the project level |
| Team | Individual users with per-project permissions |
| Revision chain | Self-referential link (previous_revision) pointing to a prior project. A unique constraint ensures each revision has at most one successor. |
A project contains EPDs, LCA versions, zero or more ResolvedTemplate instances (one per approved spec version that applies here), and submittal packages.
EPD (Environmental Product Declaration)
The core deliverable: a structured environmental impact report for a product. Every EPD stores its content in a document JSONField — a structured blob keyed by the project's resolved spec.
EPD types:
| Type | Description |
|---|---|
standard | Standalone EPD, individually reviewed. Does not use a locked template. |
reference | A verification artifact bound to a locked ResolvedTemplate. The template defines the modeling envelope variants must stay within; the reference EPD is the populated instance that proves it. Produced by morphing a standard draft — see the EPD type progression diagram above. |
variant | Derived from an approved reference EPD via the VariantEpd junction. Inherits the reference's template and is validated against its constraints on generation. |
An EPD carries tracking metadata through its lifecycle: submitted_at/by, approved_at/by, flagged_at/by, published_at/by, declaration_number and expiration_date, and pdf_file_key/pdf_generated_at for the rendered PDF.
Status lifecycle:
Variant-specific models layer on top of this: OutlierFlag tracks statistical outliers on variant indicator values, and RepublishingRequest (with child RepublishingSection records) drives the approval flow when a previously-published EPD needs to be updated.
LCA Version
Life Cycle Assessment documentation for a project. The LCA must be approved before EPDs can be approved.
Status lifecycle: draft → submitted → in_review → approved (or rejected → reopened)
LCA versions contain uploaded documents staged as either LCA submittal documents or supporting documentation. Each LCADocument also carries a document_type categorization (LCA report, supporting data, data-quality assessment, methodology notes, other) and supports soft deprecation via deprecated_at / deprecated_by rather than hard deletion, preserving the audit trail. LCA versions also track submission and review metadata (submitted_by, reviewed_by, reviewed_at, review_notes) and an optional tool_url for linking to the external LCA tool.
Specification & Template layer
Specification (Spec)
A structured definition of rules, requirements, and form configurations. Specifications exist at two levels and cascade downward through inheritance:
| Level | Example | What it defines |
|---|---|---|
| Standard | ISO 21930 / EN 15804 | Baseline structural requirements |
| PCR | EN 15804+A2 for Concrete | Category-specific rules, impact categories, input constraints, field configurations |
Specifications are versioned using semantic versioning. Each version contains requirements (with validation checks), field group definitions, and section structures.
For a deep dive, see Specifications & Validation.
EPD Template
The output when the full specification chain is evaluated for a specific project. Backed by the ResolvedTemplate model. An EPD Template locks field values, applies constraints, and defines the form that manufacturers interact with when authoring EPDs that are bound to it.
Status lifecycle: draft → in_review → approved (or rejected)
Templates are immutable after approval. Template versions are tracked via semantic versioning: minor updates auto-apply to existing projects, major updates do not.
How each EPD type uses (or doesn't use) a template:
| EPD type | Template relationship | What the template does |
|---|---|---|
standard | No template required (template FK is null) | The EPD is authored free-form against the PCC's spec. Validation comes from the spec itself, not from a locked envelope. |
reference | Required — a ResolvedTemplate is auto-created when a standard draft is morphed to reference | Locks the verified modeling envelope (locked field values + constraint ranges). The reference EPD proves the tool-and-spec combination works at these setpoints. |
variant | Inherits the template from its parent reference EPD (via the VariantEpd junction) | Every variant is validated against the same constraints the reference was approved under. Out-of-bounds inputs block variant generation — see EPD Templating for the full out-of-bounds flow. |
In short: standard EPDs are the free-form path, and reference/variant EPDs are the templated path. A project can contain both — standard EPDs for one-off products, reference EPDs (each with its own variant family) for tool-driven product lines.
For a deep dive, see EPD Templating.
Verification layer
Submittal Package
A bundle submitted by a manufacturer for third-party verification. Groups together the items a verifier needs to review as a unit.
Status lifecycle: draft → submitted (locked) → in_review → approved (or rejected / feedback)
Each package contains submittal items, each independently reviewable:
| Item type | Review scope |
|---|---|
| LCA version | LCA documentation completeness |
| Standard EPD | Full section-by-section review |
| Reference EPD | Template + tool compliance review |
| Variant EPD | Automated validation + spot checks |
Dependency gates enforce approval order: LCA → EPDs → Reference EPD → Variant EPDs.
Verification mechanics
Verification assignments are created per-EPD, per-PCF, or per-LCA version — not at the Category or project level. The verification system then operates at the section level within each assigned item:
| Component | Purpose |
|---|---|
| Verifier assignments | Per-EPD, per-PCF, or per-LCA, with status tracking |
| Verification comments | Per-section threaded discussions with author replies |
| AI conformance hints | Automated suggestions with confidence levels |
| Verifier checklists | Per-requirement compliance tracking (Y/N/OFI/N/A) |
For the full verification process, see Verification Workflow.
Related pages
- Platform Overview -Visual introduction to the entity hierarchy
- Terminology -Definitions for all platform concepts
- Specifications & Validation -How the specification inheritance chain works
- EPD Lifecycle -How entities move through the status lifecycle