djbarnwal/iodide-proposed-architecture.html

## iodide-proposed-architecture.html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Iodide proposed architecture - iodide</title>
<link rel="stylesheet" type="text/css" href="iodide.iodide-server.css">
</head>
<body>
<script id="jsmd" type="text/jsmd">
%% meta
{
  "title": "Iodide proposed architecture",
  "lastExport": "2018-08-14T02:22:40.463Z"
}

%% md
## Iodsdsdide Server

%% md
# Proposed architecture

This architecture is designed to support a relatively small number of users
(hundreds, perhaps) with relatively small notebooks. We will continue to use
github for authentication and identification.

For this first pass, we will only provide "just enough" functionality for the following tasks:

* Allow authenticated users to create notebooks and update existing notebooks
* Allow anyone to list the notebooks associated with a particular user
* List all notebooks in the system

## Software used

I propose building off the existing node.js / heroku / express implementation.

Using an ORM can simplify some things for a small application like this. It seems like sequelize is well-supported, I would recommend starting with it:

https://sequelize.readthedocs.io/en/1.7.0/articles/heroku/

## Frontend pieces

Somewhat unusually for an application like this, we still want to support running iodide notebooks in “standalone” mode-- that is, self-contained pieces of html and jsmd that have no connection to a particular iodide server.

When running in server-side mode, we will support the following views:


## Database model

This is a minimal model designed only to allow users to save notebooks. It is assumed that the entire notebook
contents will be saved inside the database for now.

### User table

Columns: [id] [github user id] [github user id] [session token]

We use this to distinguish authenticated users on the system. The [session
token](https://developer.github.com/v3/guides/basics-of-authentication/#implementing-persistent-authentication)
allows us to verify that a user has permissions to perform privileged
operations (i.e. create notebooks, modify notebooks that they own)

### Notebook table

Columns: [id] [owner (foreign key to user id)] [notebook title] [notebook contents in jsmd format] [date last updated]

## API endpoints

#### `/api/notebook/`

##### HTTP GET: Retrieves a summary list of notebooks in json format

Example output:

```json
[
  {
    id: 1,
    title: "first notebook created",
    lastUpdated: "2018-06-01T21:05:00Z"
  },
  {
    id: 2,
    title: "scientific facts, visualized",
    lastUpdated: "2018-06-02T21:05:00Z"
  },
  ...
]
```

##### HTTP POST: Create a new notebook (requires user to be authenticated)

Example input:

```json
{
  title: "My new notebook name",
  content: "..."
}
```

If successful, it will return a reference to the id of the just-created notebook:

```json
{
  id: 5
}
```

If unsuccessful, it should return the appropriate http error code (most likely `401 unauthorized`)

#### `/api/notebook/<id>`

##### HTTP GET: Retrieves the notebook's content

Example output:

```json
{
  title: "first notebook created",
  content: "..."
}
```

##### HTTP PUT: Updates the notebook's content

Example input:

```json
{
  title: "My new notebook name",
  content: "..."
}
```

If successful, it will return a success error code. If unsuccessful, it will return some kind of error (most likely `401 unauthorized`)

#### `/api/user/<id>`

##### HTTP GET: Retrieves metadata associated with a user


```json
{
   username: "wlach",
   notebooks: [
     {
       id: 1,
       title: "first notebook created",
       lastUpdated: "2018-06-01T21:05:00Z"
     },
     ...
   ]
}

%% js
</script>
<div id='page'></div>
<script src='iodide.iodide-server.js'></script>
</body>
</html>
	<!DOCTYPE html>
	<html>
	<head>
	<meta charset="UTF-8">
	<title>Iodide proposed architecture - iodide</title>
	<link rel="stylesheet" type="text/css" href="iodide.iodide-server.css">
	</head>
	<body>
	<script id="jsmd" type="text/jsmd">
	%% meta
	{
	"title": "Iodide proposed architecture",
	"lastExport": "2018-08-14T02:22:40.463Z"
	}

	%% md
	## Iodsdsdide Server

	%% md
	# Proposed architecture

	This architecture is designed to support a relatively small number of users
	(hundreds, perhaps) with relatively small notebooks. We will continue to use
	github for authentication and identification.

	For this first pass, we will only provide "just enough" functionality for the following tasks:

	* Allow authenticated users to create notebooks and update existing notebooks
	* Allow anyone to list the notebooks associated with a particular user
	* List all notebooks in the system

	## Software used

	I propose building off the existing node.js / heroku / express implementation.

	Using an ORM can simplify some things for a small application like this. It seems like sequelize is well-supported, I would recommend starting with it:

	https://sequelize.readthedocs.io/en/1.7.0/articles/heroku/

	## Frontend pieces

	Somewhat unusually for an application like this, we still want to support running iodide notebooks in “standalone” mode-- that is, self-contained pieces of html and jsmd that have no connection to a particular iodide server.

	When running in server-side mode, we will support the following views:



	## Database model

	This is a minimal model designed only to allow users to save notebooks. It is assumed that the entire notebook
	contents will be saved inside the database for now.

	### User table

	Columns: [id] [github user id] [github user id] [session token]

	We use this to distinguish authenticated users on the system. The [session
	token](https://developer.github.com/v3/guides/basics-of-authentication/#implementing-persistent-authentication)
	allows us to verify that a user has permissions to perform privileged
	operations (i.e. create notebooks, modify notebooks that they own)

	### Notebook table

	Columns: [id] [owner (foreign key to user id)] [notebook title] [notebook contents in jsmd format] [date last updated]

	## API endpoints

	#### `/api/notebook/`

	##### HTTP GET: Retrieves a summary list of notebooks in json format

	Example output:

	```json
	[
	{
	id: 1,
	title: "first notebook created",
	lastUpdated: "2018-06-01T21:05:00Z"
	},
	{
	id: 2,
	title: "scientific facts, visualized",
	lastUpdated: "2018-06-02T21:05:00Z"
	},
	...
	]
	```

	##### HTTP POST: Create a new notebook (requires user to be authenticated)

	Example input:

	```json
	{
	title: "My new notebook name",
	content: "..."
	}
	```

	If successful, it will return a reference to the id of the just-created notebook:

	```json
	{
	id: 5
	}
	```

	If unsuccessful, it should return the appropriate http error code (most likely `401 unauthorized`)

	#### `/api/notebook/<id>`

	##### HTTP GET: Retrieves the notebook's content

	Example output:

	```json
	{
	title: "first notebook created",
	content: "..."
	}
	```

	##### HTTP PUT: Updates the notebook's content

	Example input:

	```json
	{
	title: "My new notebook name",
	content: "..."
	}
	```

	If successful, it will return a success error code. If unsuccessful, it will return some kind of error (most likely `401 unauthorized`)

	#### `/api/user/<id>`

	##### HTTP GET: Retrieves metadata associated with a user


	```json
	{
	username: "wlach",
	notebooks: [
	{
	id: 1,
	title: "first notebook created",
	lastUpdated: "2018-06-01T21:05:00Z"
	},
	...
	]
	}

	%% js
	</script>
	<div id='page'></div>
	<script src='iodide.iodide-server.js'></script>
	</body>
	</html>