#300: Added an overview section discussing CDS Hooks components.

Author: brynrhodes

docs/specification/1.0.md

@@ -5,7 +5,7 @@
 
 ## Overview
 
-The CDS Hooks specification describes the RESTful APIs and interactions between EHRs and CDS Services. All data exchanged through the RESTful APIs MUST be sent and received as JSON structures, and MUST be transmitted over channels secured using the Hypertext Transfer Protocol (HTTP) over Transport Layer Security (TLS), also known as HTTPS and defined in [RFC2818](https://tools.ietf.org/html/rfc2818).
+The CDS Hooks specification describes the RESTful APIs and interactions to integrate Clinical Decision Support (CDS) between CDS Clients (typically Electronic Health Record Systems (EHRs) or other health information systems) and CDS Services. All data exchanged through the RESTful APIs MUST be sent and received as JSON structures, and MUST be transmitted over channels secured using the Hypertext Transfer Protocol (HTTP) over Transport Layer Security (TLS), also known as HTTPS and defined in [RFC2818](https://tools.ietf.org/html/rfc2818).
 
 ### Conformance Language
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in [RFC2119](https://tools.ietf.org/html/rfc2119).
@@ -23,6 +23,27 @@ An [Open API Specification](https://www.openapis.org/) (formally known as the Sw
 
 CDS Hooks implementers are not required to use the Open API Specification interface of CDS Hooks. You can download the [API specification](/specification/1.0-api.yaml) and view it online via the [Swagger Editor](http://editor.swagger.io/?url=https://raw.githubusercontent.com/cds-hooks/docs/master/docs/specification/1.0-api.yaml).
 
+## CDS Hooks Anatomy
+
+This specification describes a ["hook"](http://en.wikipedia.org/wiki/Hooking)-based pattern for invoking
+decision support from within a clinician's EHR workflow. The API supports:
+
+ * Synchronous, workflow-triggered CDS calls returning information and suggestions
+ * Launching a user-facing SMART app when CDS requires additional interaction
+ 
+The basic components of CDS Hooks are:
+
+* **CDS Service** A decision support service that accepts requests containing patient information, and provides responses
+* **CDS Client** or *EHR* An electronic health record, or other clinical information system that consumes decision support in the form of services
+* **Hook** A defined point within the client system's workflow with well-known contextual information provided as part of the request
+* **Card** Guidance from decision support services is returned in the form of cards representing discrete recommendations or suggestions that are presented to the user within the EHR
+
+In CDS Hooks, a _CDS Service_ is a service that provides patient-specific recommendations and guidance through RESTful APIs as described by this specification. The primary APIs are [Discovery](#discovery), which allows a CDS Developer to publish the types of CDS Services it provides, and the [Service](#calling-a-cds-service) endpoint that EHRs use to request decision support.
+
+A _CDS Client_ or _EHR_ is an electronic health record, or other clinical information system that consumes decision support by calling CDS Services at specific points in the application's workflow called [hooks](#hooks). Each hook defines the _hook context_, contextual information available within the client and specific to the workflow. Each service advertises which hooks it supports and what [_prefetch data_](#providing-fhir-resources-to-a-cds-service) (information needed by the CDS Service to determine what decision support should be presented) it requires.
+
+Decision support is then returned to the CDS Client in the form of [cards](#cds-service-response), which the client displays to the end-user as part of their workflow. Cards may be informational, or they may provide suggestions that the user may accept or reject, or they may provide a [link](#link) to additional information or even launch a SMART-app when additional user interaction is required.
+
 ## Discovery
 
 Developers of CDS Services SHALL provide a stable endpoint for allowing EHRs to discover available CDS Services, including information such as a description of the CDS Service, when it should be invoked, and any data that is requested to be prefetched.