Add some big picture docs based on my understanding

Author: julianstirling

docs/source/index.rst

@@ -7,6 +7,7 @@ Documentation for LabThings-FastAPI
 
    quickstart/quickstart.rst
    wot_core_concepts.rst
+   lt_core_concepts.rst
    tutorial/index.rst
    dependencies/dependencies.rst
    blobs.rst
@@ -34,7 +35,7 @@ Documentation for LabThings-FastAPI
     - Starlette (used by FastAPI) can handle requests asynchronously - this improves performance and enables websockets and other long-lived connections.
     - `Thing` code is still, for now, threaded. In the future it may become possible to us other concurrency models in `Thing` code.
 
-Compared to `python-labthings`_, this framework updates dependencies, shrinks the codebase, and simplifies the API.
+Compared to `python-labthings`_, this framework updates dependencies, shrinks the codebase, and simplifies the API  (see :doc:`lt_core_concepts`).
 * FastAPI more or less completely eliminates OpenAPI generation code from our codebase
 * Marshmallow schemas and endpoint classes are replaced with Python type hints, eliminating double- or triple-definition of actions and their inputs/outputs.
 * Thing Description generation is very much simplified by the new structure (multiple Things instead of one massive Thing with many extensions)

docs/source/lt_core_concepts.rst

@@ -0,0 +1,52 @@
+LabThings Core Concepts
+=============
+
+LabThings FastAPI is a ground-up rewrite of LabThings using FastAPI. Many of the core concepts from FastAPI such as dependency injection are used heavily
+
+The LabThings Server
+--------------------
+
+At its core LabThings FastAPI is a server-based framework. To use LabThings FastAPI a LabThings Server is created, and `Thing`s are added to the the server to provide functionality.
+
+The server API is accessed over an HTTP requests, allowing client code (see below) to be written in any language that can send an HTTP request.
+
+Client Code
+-----------
+
+Clients or client code (Not to be confused with a ThingClient, see below) is the terminology used to describe any software that uses HTTP requests to access the LabThing Server. Clients can be written in any language that supports an HTTP request. However, LabThings FastAPI provides additional functionality that makes writing client code in Python easier.
+
+Everything is a Thing
+---------------------
+
+As described in :doc:`wot_core_concepts`, a `Thing` represents a piece of hardware or software. `labthings-fastapi` automatically generates a `Thing Description`_ to describe each `Thing`. Each function offered by the `Thing` is either a Property, Action, or Event. These are termed "interaction affordances" in WoT_ terminology.
+
+Code on the LabThings FastAPI Server is composed of Things, however these can call generic Python functions/classes. The entire HTTP API served by the server is defined by `Thing`s. As such the full API is composed of the actions and properties (and perhaps eventually events) defined in each `Thing`.
+
+ThingClients
+------------
+
+When writing client code in Python it would be possible to formulate every interaction as an HTTP request. This has two major downsides:
+
+1. The code must establish a new connection to the server for each request.
+2. Each request is formulated as a string pointing to the endpoint and `json` headers for sending any data. This leads to very messy code.
+
+Ideally the client would be able to run the `Thing` object's actions and read its properties in native python code. However, as the client code is running in a different process, and probably in a different python environment (or even on a different machine entirely!) there is no way to directly import the Python objectfor the `Thing`.
+
+To mitigate this client code can ask the server for a description of all of a `Thing`'s properties and actions, this is known as a `ThingDescription`. From this `ThingDescription` the client code can dynamically generate a new object with methods matching each `ThingAction` and properties matching each `ThingProperty`. **This dynamically generated object is called a ThingClient**.
+
+The `ThingClient` also handle supplying certain arguments to ThingActions without them needing to be explicitly passed each time the method is called. More detail on this is provided in the :doc:`dependencies` page.
+
+DirectThingClients
+------------------
+
+When writing code to run on the server one Thing will need to call another Thing. Ideally this code should be identical to code written in a client. This way the code can be prototyped in a client notebook before being ported to the server.
+
+It would be possible to directly call the Thing object, however in this case the Python API would not be the same as for client code, because the dependencies would not automatically be supplied.
+**RICHARD, Are there other reasons too?**
+
+To provide the same interface in server code as is provided in client code LabThings FastAPI can dynamically create a new object with the same (or at least very similar) API as the `ThingClient`, this is called a **DirectThingClient**.
+
+The key difference between a `ThingClient` and a `DirectThingClient` is that the `ThingClient` calls the `Thing` over HTTP from client code, whereas the `DirectThingClient` calls directly through the Python API from within the Server.
+
+
+