dev.data-models.md

+# Sonador Design Patterns
+TODO:Describe the design philosophy and "rules of thumb" which govern the Sonador interfaces.
+
+* Sonador client libraries provide an object relational map (ORM) interface to interact with system resources stored within Sonador and Orthanc.
+  - The [Sonador IO Client](https://code.oak-tree.tech/oak-tree/medical-imaging/sonador-client) libary (which is a core dependency of all other Sonador libraries) inherits from the [Guru Client](https://code.oak-tree.tech/guru-labs/guru-client), which provides base utilities and core object clases.
+  - The three core classes are **servers** (which represent the data source), **model** (which defines a resource, its fundamental properties, and API methods), and **collections** (which allow for interaction with logical sets of models).
+* Sonador API methods follow traditional REST-like principals.
+  + Operations on the remote server utilize HTTP verbs to describe an action.
+  + Data payloads are sent as JSON (representated as `dict` instances within the library)
+* Sonador model classes define properties and interfaces to create, retrieve, update, and delete model instances. _The four methods are often called `CRUD` operations._
+
+
+
+## Object Relational Mappers (ORM)
+The persistence of data is the foundation of almost every web application.
+
+A model is a Python class that represents an object in the data store (usually a relational database with attributes mapping to table columns). Models determine the structure of the stored data and define methods for working with the information on the server. Models are initialized by retrieving data from a database or API. Once retrieved, however, it provides a local instance of the data which can be used for a variety of applications.
+
+The practice of mapping data from a remote source to a local programmatic representation is called "object relational mapping" (ORM). The [Sonador IO Client library](https://code.oak-tree.tech/oak-tree/medical-imaging/sonador-client) (and [Guru Client library](https://code.oak-tree.tech/guru-labs/guru-client) upon which they are based) provide an ORM system which maps JSON data retrieved from the Sonador and Orthanc APIs to properties (both dynamic and static) that can be used from client applications in a consistent object-oriented manner.
+
+The Guru Client provides three base components:
+
+* a "server" which represents the remote system and handles the exchange of data (connection, error handling, and authentication)
+* model classes which represent the object defined on the server
+* collection classes which can be used to interact with logically grouped sets of models
+
+
+TODO:Describe server implementation
+
+TODO:Describe base model class and primary interface
+
+TODO:Describe base collection model class and primary interface
+
+TODO:Describe REST-like rules of thumb for Sonador applications.
+
+* By convention, every Guru, Oak-Tree, and Sonador API resource is associated with **two primary endpoints**.
+  - **A "management" endpoint** that is used for describing the resource, retrieving collections of logically grouped models, and creating new instances of the model.
+  creating new models that are part of the collection.
+    + `OPTIONS`: retrieve schema and access details for the model type (the response will also include access paramters and query/filter options)
+    + `GET`: retrieve a collection of models. _The endpoint will often have search capabilities that can be accessed via query parameters and pagination information available from headers._
+    + `POST`: create a new model instance in the collection.    
+  - **A "details" endpoint** (also sometimes called a REST endpoint) that is associated with a specific instance of the model and used to retrieve details of the instance, make updates, or to remove it from the server.
+    + `GET`: retrieve details of the specific instance
+    + `PUT`: update model attributes
+    + `DELETE`: remove the model instance
+* Client design philosophies
+  - Client model classes contain the properties that define what the model "is" and where its data resides.
+  - Client collection classes read model properties to execute 
+  - Client model and collection operations are organized around the capabilities of the endpoints they interact with.
+    + **Collection operations** mirror management endpoint capabilities.
+      * `fetch` (class method): retrieve a set of models from the endpoint
+      * `create` (class method): create a new model instance
+    + **Model operations** mirror instance (REST) endpoint capabilities.
+      * `update`: update the data for a model
+      * `delete`: remove a model from the server
+
+
+
+## Sonador IO Client Organization
+
+* `local`: local representations of DICOM resources that follow general Sonador conventions
+* `remote`: remote (server API) resources (also follows Sonador conventions)
+* `sr`: structured types and properties defined by the DICOM-SR standard which can be used to parse data SR files to an in-memory format and persist data to a file on-disk or stored in the medical imaging database
+
+
+### `local`
+TODO:Describe the `local` module of Sonador, the problems it solves, when it should be used, and examples.
+
+
+### `remote`
+TODO:Describe the `remote` module of Sonador, the problems it solves, when it should be used and examples.
+
+The `remote` module includes models (sometimes called data objects) 
+
+Model class properties.
+* `fetch_endpoint` (`str` or `property` which returns `str`): defines the "management" interface for the dataclass. _The endpoint should contain the resource path, query parameters and fragments. Schema, network location, and port will be taken from the server._
+
+
+### `sr`
+TODO:Describe the `sr` module of Sonador and how it relates to the `local` and `remote` modules.