ERD.puml

@startuml "HypercertERD"

' None of these support arrows originating from individual fields
'!pragma layout smetana
'!pragma layout elk
'!pragma layout vizjs

title "Hypercert ERD"

' Configuration variables
!ifndef SHOW_FIELDS
!define SHOW_FIELDS false
!endif

!if (SHOW_FIELDS == "false")
hide empty fields
!endif
hide empty methods
hide stereotypes

!define REVIEW_COLOR #FFFACD
!define ARROW_COLOR #666666

<style>
document {
    title {
        FontSize 24
        FontStyle bold
    }
}
classDiagram {
    arrow {
        LineColor ARROW_COLOR
        FontColor ARROW_COLOR
        FontSize 10
    }
    .largeBold {
        header {
            FontSize 20
            FontStyle bold
        }
    }
}
</style>

' Contributors are represented by DIDs or human-readable strings
' therefore do not require modelling via a lexicon.
entity "contributor (DID/profile)" as contributorEntity #FFD4A3 {
    !if (SHOW_FIELDS == "true")
    DID or social profile URI
    !endif
}

' org.hypercerts.claim.activity - this is the main record
' representing a hypercert.
dataclass activity <<largeBold>> #B4E5D0 {
    !if (SHOW_FIELDS == "true")
    title
    shortDescription
    description?
    image?
    workScope?
    startDate?
    endDate?
    contributions[]?
    locations[]?
    rights?
    createdAt
    !endif
}

' org.hypercerts.claim.evidence
dataclass evidence {
    !if (SHOW_FIELDS == "true")
    subject?
    content
    title
    shortDescription?
    description?
    relationType?
    createdAt
    !endif
}

' org.hypercerts.claim.measurement
dataclass measurement {
    !if (SHOW_FIELDS == "true")
    subject?
    measurers[]
    metric
    value
    methodType?
    methodURI?
    evidenceURI[]?
    location?
    createdAt
    !endif
}

' org.hypercerts.claim.evaluation
dataclass evaluation {
    !if (SHOW_FIELDS == "true")
    subject?
    summary
    evaluators[]
    content[]?
    measurements[]?
    score
    location?
    createdAt
    !endif
}

' org.hypercerts.claim.contributor
dataclass contributor {
    !if (SHOW_FIELDS == "true")
    identifier?
    displayName?
    image?
    role?
    contributionDescription?
    startDate?
    endDate?
    createdAt
    !endif
}

' app.certified.location
dataclass location {
    !if (SHOW_FIELDS == "true")
    lpVersion
    srs
    locationType
    location
    name?
    description?
    createdAt
    !endif
}

' Certified badges (data class + award + response)
dataclass badgeDefinition {
    !if (SHOW_FIELDS == "true")
    badgeType
    title
    icon
    description?
    allowedIssuers[]?
    createdAt
    !endif
}

dataclass badgeAward {
    !if (SHOW_FIELDS == "true")
    badge
    subject
    note?
    createdAt
    !endif
}

dataclass badgeResponse {
    !if (SHOW_FIELDS == "true")
    badgeAward
    response
    weight?
    createdAt
    !endif
}

' org.hypercerts.claim.rights
dataclass rights {
    !if (SHOW_FIELDS == "true")
    rightsName
    rightsType
    rightsDescription
    attachment?
    createdAt
    !endif
}

' org.hypercerts.claim.collection
' Note: Collections can use app.certified.location as a sidecar
' by creating a location record with the same TID
dataclass collection {
    !if (SHOW_FIELDS == "true")
    type?
    title
    shortDescription?
    description? (Leaflet ref)
    items[]
    createdAt
    !endif
}


' org.hypercerts.acknowledgement
dataclass acknowledgement {
    !if (SHOW_FIELDS == "true")
    subjects[]
    context
    given
    comment?
    createdAt
    !endif
}

' org.hypercerts.claim.collection.project (sidecar)
dataclass collectionProject {
    !if (SHOW_FIELDS == "true")
    projectTitle?
    shortProjectDescription?
    projectDescription (Leaflet ref)
    avatar?
    coverPhoto?
    createdAt
    !endif
}

'together {

' Funders are represented by DIDs or human-readable strings
' therefore do not require modelling via a lexicon.
entity funder #FFD4A3 {
    !if (SHOW_FIELDS == "true")
    DID or name/pseudonym
    !endif
}

' org.hypercerts.funding.receipt
dataclass fundingReceipt {
    !if (SHOW_FIELDS == "true")
    to
    from
    for?
    amount
    currency
    paymentRail?
    paymentNetwork?
    transactionId?
    notes?
    occurredAt?
    createdAt
    !endif
}

'} ' end together

' NOTE: this is NOT a lexicon, but instead reflects an onchain
' tokenization of an activity record.  So it does not need
' a lexicon definition.
protocol token <<largeBold>> #FFB6C1 {
    !if (SHOW_FIELDS == "true")
    (on-chain only)
    !endif
}

' layout hints
'evaluation --d[hidden]-> evidence
'evaluation --d[hidden]-> measurement
'measurement -d[hidden]-> activity
'evidence -r[hidden]-> measurement
activity -l[hidden]-> token
'evidence -d[hidden]-> activity
'collection -d[hidden]-> activity
'activity -u[hidden]-> contributor
'activity -u[hidden]-> location
'activity -d[hidden]-> rights
'contribution -r[hidden]-> contributor
'fundingReceipt -[hidden]-> contributor

evaluation::subject --> evidence
evaluation::measurements --> measurement
evaluation::subject --> activity

' Impossible to get this one on without screwing up the layout
'evaluation::location --[norank]-> location

' so instead make a dangling arrow using a hidden class
skinparam class {
    BackgroundColor<<Ghost>> Transparent
    BorderColor<<Ghost>> Transparent
    EntityColor<<Ghost>> Transparent
}
class " " as hiddenLocation1 <<Ghost>>
hide hiddenLocation1 circle
evaluation::location --> hiddenLocation1
!if (SHOW_FIELDS == "true")
' Also ensure the hidden class is somewhere "en route" to location
hiddenLocation1 -[hidden]-> activity
!else
' Also Impossible to get this one on without screwing up the layout
'evaluation -d[norank]--> location
!endif

evidence::subject --> activity

measurement::subject --> activity

' Somewhat similarly for measurement --> location
!if (SHOW_FIELDS == "true")
class " " as hiddenLocation2 <<Ghost>>
hide hiddenLocation2 circle
measurement::location --> hiddenLocation2
' Also ensure the hidden class is somewhere "en route" to location
hiddenLocation2 -[hidden]-> location
!else
measurement --> location
!endif

collection::items --> activity
collection::items --> collection : "recursive\nnesting"
collection ..|> collectionProject : "sidecar\n(same TID)"


acknowledgement::subjects --> activity : "(subject)"
acknowledgement::context --> collection : "(context)"
note bottom of acknowledgement : "Subjects and context can reference\nany AT Protocol record type."

activity::contributions -l--> contributor
activity::rights --> rights
activity::locations --> location

contributor::identifier --> contributorEntity : made by

' These ones are not described by any lexicon, but are added to
' the diagram for clarity
token ..> activity : tokenizes
funder ..> activity : funds
contributor ..> rights : has

' These two are strings which will reference the counterparty's
' DID or human-readable name (if they're not on ATProto).
' However we still deliberately use solid arrows because they are
' explicitly described within the fundingReceipt lexicon.
fundingReceipt::from --> funder
fundingReceipt::to --> contributorEntity

fundingReceipt::for --> activity : funds

badgeAward::badge --> badgeDefinition
badgeResponse::badgeAward --> badgeAward
badgeAward::subject --> contributor
badgeAward::subject --> activity
' This screws up the layout
'badgeAward::subject --[norank]-> collection

@enduml