Update READEME.md

README.md

@@ -7,76 +7,134 @@
 
 # nextline-graphql
 
-A GraphQL API for Nextline
-
-_Nextline_ allows line-by-line execution of concurrent Python scripts by
-multiple users simultaneously from web browsers. Nextline is being developed as
-a DAQ sequencer of the [Observatory Control System
-(OCS)](https://github.com/simonsobs/ocs/).
+The plugin-based framework of the backend API server of Nextline.
+
+**Table of Contents**
+
+- [Introduction](#introduction)
+- [Packages](#packages)
+  - [Core package](#core-package)
+  - [Plugin system](#plugin-system)
+  - [Plugins](#plugins)
+    - [Internal plugins](#internal-plugins)
+    - [External plugins](#external-plugins)
+  - [Web App](#web-app)
+- [How to run the Nextline backend API server](#how-to-run-the-nextline-backend-api-server)
+  - [As a Docker container](#as-a-docker-container)
+  - [In a virtual environment](#in-a-virtual-environment)
+- [Configuration](#configuration)
+- [Check out code for development](#check-out-code-for-development)
+- [License](#license)
+- [Contact](#contact)
+
+## Introduction
+
+_Nextline_ is a DAQ sequencer of the [Observatory Control System
+(OCS)](https://github.com/simonsobs/ocs/). Nextline allows line-by-line
+execution of concurrent Python scripts, which control telescopes, by multiple
+users simultaneously from web browsers.
+
+Nextline consists of multiple packages. This package, _nextline-graphql_, provides the
+framework for the backend API server. It is a plugin-based framework. Features
+are added by plugins.
 
 ## Packages
 
-- [**nextline:**](https://github.com/simonsobs/nextline) (Python) the core functionality. imported in _nextline-graphql._
-- [**nextline-graphql:**](https://github.com/simonsobs/nextline-graphql) (Python) this package. the GraphQL API
-- [**nextline-web:**](https://github.com/simonsobs/nextline-web) (JavaScript) the client website
+### Core package
+
+- [**nextline:**](https://github.com/simonsobs/nextline) The core functionality
+  of Nextline. It controls the execution of the Python scripts. It is used by
+  the plugin _ctrl_.
+
+### Plugin system
+
+The plugin system of _nextline-graphql_ is _apluggy_.
+
+- [**apluggy:**](https://github.com/simonsobs/apluggy) A wrapper of
+  [pluggy](https://pluggy.readthedocs.io/) to support asyncio and context
+  managers.
+
+### Plugins
+
+#### Internal plugins
+
+These plugins are included in this package.
+
+- [**graphql:**](./nextlinegraphql/plugins/graphql/) The entry point of the
+  GraphQL API, implemented with [strawberry-graphql](https://strawberry.rocks/).
+- [**ctrl:**](./nextlinegraphql/plugins/ctrl/) The core plugin that controls
+  the execution of the Python scripts. It uses the package
+  [_nextline_](https://github.com/simonsobs/nextline).
+
+#### External plugins
+
+These plugins are not included in this package. They can be installed separately.
+
+- [**nextline-rdb:**](https://github.com/simonsobs/nextline-rdb) A relational database for nextline. It stores configuration, execution history, and other information. It is implemented with [SQLAlchemy 2](https://www.sqlalchemy.org/).
+- [**nextline-scheduler:**](https://github.com/simonsobs/nextline-schedule) An interface to the [_SO scheduler_](https://github.com/simonsobs/scheduler).
+- [**nextline-alert:**](https://github.com/simonsobs/nextline-alert) An interface to the alert system [_campana_](https://github.com/simonsobs/campana).
+
+### Web App
+
+The front-end web app is currently in a single package. The development of a
+plugin-based system is planned.
+
+- [**nextline-web:**](https://github.com/simonsobs/nextline-web) (TypeScript)
+  The front-end web app of Nextline. It is a Vue.js app.
 
-## How to run the Nextline GraphQL API
+## How to run the Nextline backend API server
 
-The section shows how to run the Nextline GraphQL API server. How to run the
-client website will be described
+The section shows how to run the Nextline backend API server. How to run the
+front-end web app is described
 [elsewhere](https://github.com/simonsobs/nextline-web).
 
 ### As a Docker container
 
-Docker images of the Nextline GraphQL API server are created as
+Docker images of the Nextline backend API server are created as
 [ghcr.io/simonsobs/nextline-graphql](https://github.com/simonsobs/nextline-graphql/pkgs/container/nextline-graphql).
 These images are created by the
 [Dockerfile](https://github.com/simonsobs/nextline-graphql/blob/main/Dockerfile).
+No external plugins are included in the images.
 
 Use, for example, the following command to run as a Docker container.
 
 ```bash
 docker run -p 8080:8000 ghcr.io/simonsobs/nextline-graphql
 ```
 
-If you access to the API server with a web browser, you will see the GraphQL IDE: <http://localhost:8080/>.
+If you access to the API server with a web browser, you will see the GraphQL
+IDE: <http://localhost:8080/>.
 
-### With a persistent DB
+To include external plugins, you can create a new Docker image with
+_ghcr.io/simonsobs/nextline-graphql_ as the base image. For example,
+[nextline-rdb](https://github.com/simonsobs/nextline-rdb) shows how to create a
+new Docker image with _nextline-rdb_ as an external plugin.
 
-Nextline-graphql stores the execution history and other information in the DB.
-It uses [SQLAlchemy](https://www.sqlalchemy.org/), with, by default, a [SQLite
-in-memory database](https://www.sqlite.org/inmemorydb.html).
+### In a virtual environment
 
-#### An environment variable in the container
-
-The container has one environment variable, which is to change the [DB URL](https://docs.sqlalchemy.org/en/14/core/engines.html#database-urls) of SQLAlchemy.
-
-| Environment variable | Default value                                | Description                                                                                   |
-| -------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `NEXTLINE_DB__URL`   | `sqlite+aiosqlite://` | The [DB URL](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls) of SQLAlchemy |
-
-For example, the following command uses a file on the host machine
-`db/db.sqlite3` as the persistent DB. The directory `db/` and the file
-`db.sqlite3` will be created if they don't exist.
-
-```bash
-docker run -p 8080:8000 --env NEXTLINE_DB__URL='sqlite+aiosqlite:////db/db.sqlite3' -v "$(pwd)/db:/db" ghcr.io/simonsobs/nextline-graphql
-```
-
-### from PyPI
-
-It is also possible to install with pip and run.
+You can create a virtual environment, install packages, and run the API server
+as follows.
 
 ```bash
+python -m venv venv
+source venv/bin/activate
 pip install nextline-graphql
+pip install uvicorn
 uvicorn --lifespan on --factory --port 8080 nextlinegraphql:create_app
 ```
 
-The environment variable `NEXTLINE_DB__URL` mentioned above can be used to
-specify the SQLAlchemy DB URL.
-
 Check with a web browser at <http://localhost:8080/>.
 
+If you check out external plugins, nextline-graphql automatically detects them
+as plugins. An example can be found in
+[nextline-rdb](https://github.com/simonsobs/nextline-rdb).
+
+## Configuration
+
+nextline-graphql uses [dynaconf](https://www.dynaconf.com/) for configuration
+management. nextline-graphql itself does not have any configuration except for
+logging. External plugins have configurations.
+
 ## Check out code for development
 
 This section shows an example way to check out code from GitHub for development.