# Architecture Notes

* [iSamples Use Cases](https://docs.google.com/document/d/16397FFbd0NjzW93TTD95ZqYkrwEpsC5DzBJnE7xnLPA/edit#heading=h.1j9e9v3wssw7) document

Actors from Use Cases document

Administrator
: An administrator is responsible for higher level management and financial decisions. Generally not involved with technical aspects of operations.

Portal Manager
: *aka. "System Manager"* Responsible for operating a collection "portal" providing access to a collection through a web interface. The portal manager is responsible for maintaining access control and general maintenance of the portal.

Research Contributor
: Contributes content to a collection.

Research Consumer
: Retrieves content from a collection. May be working with specific records or broadly across collection content

Curator
: A curator is responsible for maintaining the integrity of content in collections. Generally a domain expert on the subject of the collection. May not be knowledgable about technical aspects of the collection system operations.

Data User:
: Has members *Research Contributor*, *Research Consumer*, *Curator*.

Any User
: Can be any person or machine interacting with the system.

---

!include https://raw.githubusercontent.com/datadavev/C4-PlantUML/master/C4_Component.puml

AddElementTag("v2.0", $fontColor="white")
AddRelTag("v2.0", $lineColor="gray", $textColor="gray")

AddElementTag("v3.0", $borderColor="gray", $fontColor="white", $bgColor="8e8e8e" )
AddRelTag("v3.0", $lineColor="gray", $textColor="gray")

System(isc, "iSC", "iSamples Central")
 
System_Boundary(isamples, "iSamples"){
  System(isb, "iSB", "iSamples-In-A-Box")
  System_Ext(collection, "Collection", "Collection of sample records")
  Rel(isb, collection, "Get records from collection")
}
BiRel(isb, isc, "Synchronize records")
  
System_Ext(pid, "Id Authority", "Identifier authorities (IGSN, ARK, DOI, ROR, ...", $tags="v2.0")
Rel(pid, isb, "Allocate range of identifier values", $tags="v2.0")
Rel(pid, isc, "Allocate range of identifier values?", $tags="v2.0")

Person(user, "User", "Data User")
Rel(user, isc, "Discover")
Rel(user, isc, "Annotate", $tags="v2.0")
Rel(user, isb, "Discover, Retrieve")
Rel(user, isb, "Annotate, [Create, Update if authorized]", $tags="v2.0")

Person(admin, "Admin", "Administrator")
Rel_U(admin, isc, "Manage")
Rel(admin, isb, "Manage")

System_Ext(evocab, "Vocabularies", "Community maintained vocabularies and ontologies")
Rel(evocab, isb, "Inform")
Rel(evocab, isc, "Inform")

System_Ext(identity, "Identity", "User identity service (ORCID, GitHub, ...)", $tags="v2.0")
Rel(isc, identity, "User metadata, Authenticate", $tags="v2.0")
Rel(isb, identity, "User metadata, Authenticate (if applicable)", $tags="v2.0")

Rel(admin, identity, "Identified by", $tags="v2.0")
Rel(user, identity, "Identified by", $tags="v2.0")


System_Ext(publisher, "Publisher", "Source of identifier appareance in publications", $tags="v3.0")
Rel(isc, publisher, "Get identifier appearances", $tags="v3.0")

## Version 1.0

### iSamples Architecture

!include https://raw.githubusercontent.com/datadavev/C4-PlantUML/master/C4_Component.puml

AddElementTag("v2.0", $borderColor="#ffffff", $fontColor="#ffffff", $bgColor="#ffffff" )
AddRelTag("v2.0", $lineColor="#ffffff", $textColor="#ffffff")

AddElementTag("v3.0", $borderColor="#ffffff", $fontColor="#ffffff", $bgColor="#ffffff" )
AddRelTag("v3.0", $lineColor="#ffffff", $textColor="#ffffff")

System(isc, "iSC", "iSamples Central")
 
System_Boundary(isamples, "iSamples"){
  System(isb, "iSB", "iSamples-In-A-Box")
  System_Ext(collection, "Collection", "Collection of sample records")
  Rel(isb, collection, "Get records from collection")
}
BiRel(isb, isc, "Synchronize records")
  
System_Ext(pid, "Id Authority", "Identifier authorities (IGSN, ARK, DOI, ROR, ...", $tags="v2.0")
Rel(pid, isb, "Allocate range of identifier values", $tags="v2.0")
Rel(pid, isc, "Allocate range of identifier values?", $tags="v2.0")

Person(user, "User", "Data User")
Rel(user, isc, "Discover")
Rel(user, isc, "Annotate", $tags="v2.0")
Rel(user, isb, "Discover, Retrieve")
Rel(user, isb, "Annotate, [Create, Update if authorized]", $tags="v2.0")

Person(admin, "Admin", "Administrator")
Rel_U(admin, isc, "Manage")
Rel(admin, isb, "Manage")

System_Ext(evocab, "Vocabularies", "Community maintained vocabularies and ontologies")
Rel(evocab, isb, "Inform")
Rel(evocab, isc, "Inform")

System_Ext(identity, "Identity", "User identity service (ORCID, GitHub, ...)", $tags="v2.0")
Rel(isc, identity, "User metadata, Authenticate", $tags="v2.0")
Rel(isb, identity, "User metadata, Authenticate (if applicable)", $tags="v2.0")

Rel(admin, identity, "Identified by", $tags="v2.0")
Rel(user, identity, "Identified by", $tags="v2.0")


System_Ext(publisher, "Publisher", "Source of identifier appareance in publications", $tags="v3.0")
Rel(isc, publisher, "Get identifier appearances", $tags="v3.0")

SHOW_LEGEND()

## Version 2.0

!include https://raw.githubusercontent.com/datadavev/C4-PlantUML/master/C4_Component.puml

AddElementTag("v2.0", $borderColor="#250339", $fontColor="#ffffff", $bgColor="#9775AA" )
AddRelTag("v2.0", $lineColor="#754B8E", $textColor="#754B8E")

AddElementTag("v3.0", $borderColor="#ffffff", $fontColor="#ffffff", $bgColor="#ffffff" )
AddRelTag("v3.0", $lineColor="#ffffff", $textColor="#ffffff")

System(isc, "iSC", "iSamples Central")
 
System_Boundary(isamples, "iSamples"){
  System(isb, "iSB", "iSamples-In-A-Box")
  System_Ext(collection, "Collection", "Collection of sample records")
  Rel(isb, collection, "Get records from collection")
}
BiRel(isb, isc, "Synchronize records")
  
System_Ext(pid, "Id Authority", "Identifier authorities (IGSN, ARK, DOI, ROR, ...", $tags="v2.0")
Rel(pid, isb, "Allocate range of identifier values", $tags="v2.0")
Rel(pid, isc, "Allocate range of identifier values?", $tags="v2.0")

Person(user, "User", "Data User")
Rel(user, isc, "Discover")
Rel(user, isc, "Annotate", $tags="v2.0")
Rel(user, isb, "Discover, Retrieve")
Rel(user, isb, "Annotate, [Create, Update if authorized]", $tags="v2.0")

Person(admin, "Admin", "Administrator")
Rel_U(admin, isc, "Manage")
Rel(admin, isb, "Manage")

System_Ext(evocab, "Vocabularies", "Community maintained vocabularies and ontologies")
Rel(evocab, isb, "Inform")
Rel(evocab, isc, "Inform")

System_Ext(identity, "Identity", "User identity service (ORCID, GitHub, ...)", $tags="v2.0")
Rel(isc, identity, "User metadata, Authenticate", $tags="v2.0")
Rel(isb, identity, "User metadata, Authenticate (if applicable)", $tags="v2.0")

Rel(admin, identity, "Identified by", $tags="v2.0")
Rel(user, identity, "Identified by", $tags="v2.0")


System_Ext(publisher, "Publisher", "Source of identifier appareance in publications", $tags="v3.0")
Rel(isc, publisher, "Get identifier appearances", $tags="v3.0")

SHOW_LEGEND()

## Version 3.0

!include https://raw.githubusercontent.com/datadavev/C4-PlantUML/master/C4_Component.puml

AddElementTag("v2.0", $borderColor="#250339", $fontColor="#ffffff", $bgColor="#9775AA" )
AddRelTag("v2.0", $lineColor="#754B8E", $textColor="#754B8E")

AddElementTag("v3.0", $borderColor="#ffffff", $fontColor="#ffffff", $bgColor="#D4D46A" )
AddRelTag("v3.0", $lineColor="#807F15", $textColor="#807F15")

System(isc, "iSC", "iSamples Central")
 
System_Boundary(isamples, "iSamples"){
  System(isb, "iSB", "iSamples-In-A-Box")
  System_Ext(collection, "Collection", "Collection of sample records")
  Rel(isb, collection, "Get records from collection")
}
BiRel(isb, isc, "Synchronize records")
  
System_Ext(pid, "Id Authority", "Identifier authorities (IGSN, ARK, DOI, ROR, ...", $tags="v2.0")
Rel(pid, isb, "Allocate range of identifier values", $tags="v2.0")
Rel(pid, isc, "Allocate range of identifier values?", $tags="v2.0")

Person(user, "User", "Data User")
Rel(user, isc, "Discover")
Rel(user, isc, "Annotate", $tags="v2.0")
Rel(user, isb, "Discover, Retrieve")
Rel(user, isb, "Annotate, [Create, Update if authorized]", $tags="v2.0")

Person(admin, "Admin", "Administrator")
Rel_U(admin, isc, "Manage")
Rel(admin, isb, "Manage")

System_Ext(evocab, "Vocabularies", "Community maintained vocabularies and ontologies")
Rel(evocab, isb, "Inform")
Rel(evocab, isc, "Inform")

System_Ext(identity, "Identity", "User identity service (ORCID, GitHub, ...)", $tags="v2.0")
Rel(isc, identity, "User metadata, Authenticate", $tags="v2.0")
Rel(isb, identity, "User metadata, Authenticate (if applicable)", $tags="v2.0")

Rel(admin, identity, "Identified by", $tags="v2.0")
Rel(user, identity, "Identified by", $tags="v2.0")


System_Ext(publisher, "Publisher", "Source of identifier appareance in publications", $tags="v3.0")
Rel(isc, publisher, "Get identifier appearances", $tags="v3.0")

SHOW_LEGEND()

## iSamples Application Landscape

!include https://raw.githubusercontent.com/datadavev/C4-PlantUML/master/C4_Context.puml

System(isa, "iSA", "iSamples Application")
System_Ext(coll, "Collection", "Collection of records")
 Rel_U(isa, coll, "Synchronize records from")
 
 System_Ext(ont, "Ontolgies", "Community maintained ontologies and vocabularies")
 Rel_L(isa, ont, "Uses")
 
Person(admin, "Manager", "System Manager")
Rel(admin, isa, "Manages")

Person(user, "User", "Data User")
Rel(user, isa, "Discover, Retrieve, Annotate, [Create, Update if authorized]")
 
 System_Ext(pid, "Id Authority", "Identifier authorities (IGSN, ARK, DOI, ROR, ...)")
 Rel(isa, pid, "Get allocation of identifier value range from")
 
 System_Ext(identity, "Identity", "User identity service (ORCID, GitHub, ...)")
Rel(isa, identity, "Get user metadata and authenticate using")
 
System_Ext(publisher, "Publisher", "Source of identifier appareance in publications")
Rel(isa, publisher, "Get identifier appearances from")
 
SHOW_LEGEND()

The overall landscape of interactions is similar regardless of whether iSApp is operating as an iSC or iSB instance.

## iSamples Application Containers

!include https://raw.githubusercontent.com/datadavev/C4-PlantUML/master/C4_Container.puml

Container(app, "API", "Python", "Business logic and background tasks")
Container(web, "Web UI", "Python, HTML, Javascript", "Web interface to iSC")
Container(vocab, "Vocabularies", "RDF", "Vocabularies managed by iSamples")
ContainerDb(db, "Storage", "Postgres")
ContainerDb(idx, "Index", "Solr")

Rel(web, app, "Implements UI for")
Rel(app, db, "Store, retrieve records")
Rel(vocab, db, "Store, retrieve vocabularies")
Rel(app, vocab, "Uses")
Rel(app, idx, "Index records, search for records")

Container_Ext(collection, "Collection", "Native or iSamplesApp")
Rel(app, collection, "Synchronize content from")

## iSamples Application Components

!include https://raw.githubusercontent.com/datadavev/C4-PlantUML/master/C4_Component.puml

Component(api, API, FastAPI, "Implements API for interacting with iSamples application")
Component(app, App, Python, "Business logical and internal operations")
Component(xform, Transform, Python, "Transform to core model")
ComponentDb(dbs, Database, Postgres, "Record storage")
ComponentDb(dbv, Database, ?, "Vocabulary storage")
ComponentDb(dba, Database, ?, "Annotation storage")
ComponentDb(dbr, Database, ?, "Relation storage")
ComponentDb(idx, Index, Solr, "Search index")