kokkoja-rel/docs/introduction.md

# Kokkoja: an introduction

Kokkoja lets people at different computers write together on a shared
*page*.  Everyone in a session sees the same page.  Anyone can write on it
by hand or type on it, and what one person writes appears on the others'
screens as it is written.  A page can begin blank, or it can begin with an
image, such as a scanned sheet or a photograph, which everyone then writes
on.  Every page is saved automatically to a *notebook* on each person's
own computer, so that after the session each participant keeps a complete
copy of everything that was written.

Kokkoja runs in a web browser, beside whatever video call you are already
using.  It replaces the screen sharing and annotation of a video call
application with something made for writing together, and it leaves the
voice and video to the call.

## What Kokkoja does

**A shared page, not a shared screen.**  In a video call one person's
screen is transmitted as a picture, and annotations float on top of that
picture.  In Kokkoja every participant's computer holds the page itself:
the image, if there is one, and every mark made on it.  Only the changes
travel over the network.  The marks belong to the page, are saved with it,
and can be shown or hidden later.

**Handwriting and typing.**  Kokkoja is made for a pen on a drawing
tablet, with pressure giving the line its thickness, but a mouse or a
finger will do.  Typed text is placed anywhere on the page and wraps at a
width you choose.  Both come in any colour.

**Everyone writes on their own layer.**  Each participant's writing is a
layer of its own.  You can erase your own writing and nothing else; nobody
else can erase yours.  Any layer can be hidden on your own screen without
affecting anyone else's view.

**A page that grows.**  A page is an A4 sheet, lying on its side.  When writing approaches an
edge, the sheet grows in that direction, so you are never short of room.
An image is placed at its natural size; one wider than the sheet is
scaled down to fit, and the sheet grows downward to hold further images.

**Saved without a save command.**  The page you are on is written to your
notebook continuously, as it changes.  Nothing is lost if a connection
drops or a computer crashes.  When the session moves to another page, the
page being left is kept as a dated file.  You can also keep a dated copy
of a page at any moment, and export a picture of it as a PNG file.

**Notebooks are yours.**  A notebook is a directory on your own computer
and a page is a single file in it, an ordinary SVG file that any
image viewer or vector drawing program can open.  Nothing is stored on any
server, and there are no accounts: you choose the name the others will
see, and that is all.

**Private.**  Everything that travels between participants is encrypted
on their own computers.  The relay server that passes the messages cannot
read them.  The invitation to a session carries the key, so only those
who were invited can read the page.

**Nothing to install for guests.**  A guest joins by opening a link in a
web browser.  Someone who wants a notebook of real files on their own
computer installs the small Kokkoja program instead; that is also how a
host runs Kokkoja.

**Free software.**  Kokkoja is free and open-source.  Anyone can use it
without paying, and nobody depends on a company's service.  It runs in
Firefox, in browsers built on the Chromium engine, such as Brave or
Chrome, and in Safari, on Linux and macOS; a guest can also join from
Safari on an iPad or an iPhone, writing with a pencil or a finger.

## Who uses it

Kokkoja is a general tool for working on a page together at a distance:
going through a document with a colleague, sketching a diagram while
talking it over, correcting a draft, teaching anything that is done on
paper.  Wherever two people would otherwise lean over one sheet, Kokkoja
puts the sheet between their computers.

Its ideal use, and the one it was made for first, is teaching a foreign
language over a video call.  The teacher puts a scanned exercise on the
page.  The student fills it in by hand or by typing, during the lesson,
while the teacher watches, corrects mistakes as they are made, and adds
notes in the margin.  Each correction is in the teacher's own hand and
colour, on the teacher's own layer, where the student cannot change it.
When the lesson is over, the student's notebook holds every exercise of
the lesson, with the student's answers and the teacher's corrections
together on one page, and the teacher's notebook holds the same pages as
a record of what the student was given.  The teacher's notebooks of
exercises become a library: loading a page from one of them puts a fresh
copy in front of a new student, and the original is never changed.

## Hosts and guests

A session has one *host*, the person who starts it, and any number of
*guests*.  In a lesson the teacher is the host and the students are the
guests.  The host sends the guests an invitation, by email, in a chat
message, or by any other means.  The host *drives*: only the host puts
images on the page, starts new pages or loads pages from a notebook, and
everyone follows.  The host can make any guest a *co-host*, with the
same powers, for a discussion among colleagues.

## What runs where

Three kinds of machine take part, and it helps to have the picture in
mind before reading on.

```
   Host's computer                 Server                    Guests
   ---------------                 ------                    ------
   Kokkoja program            kokkoja.andykopra.com      Guest A: a browser
     serves the client  -+        |                        opens the link
     to the browser at   |   +----+-----+                  the server serves
     localhost:8760      |   |  relay   | <------------->  the client to it;
     keeps the notebook  |   | (passes  |                  notebook in the
     as files            |   | messages,|                  browser, downloads
          |              |   | reads    |
     browser <-----------+   | nothing) | <------------->  Guest B: has the
       |                     +----------+                  Kokkoja program too;
       +---- encrypted ----------^  |                      joins from its own
             messages               |                      start screen; note-
                              web site:                    book as files
                              the client's files
```

* **The host** runs the small Kokkoja program on their own computer.
  It shows Kokkoja in the host's browser, at the address
  `http://localhost:8760/`, and it keeps the host's notebooks as
  directories of files.  It must be running for as long as the host is
  in a session; the browser alone cannot reach the notebooks.

* **The server** does two things for everyone.  Its *relay* passes the
  participants' messages, which are encrypted before they leave each
  computer, so the relay reads nothing.  Its *web site* serves the
  Kokkoja client to guests who join by link.  The host's program is
  told the server's address once, when it is started.

* **A guest** needs only a browser: opening the invitation link fetches
  the client from the server's web site, and the guest's notebook lives
  in that browser, with kept pages and exports offered as downloads.  A
  guest who wants a notebook of real files runs the Kokkoja program as
  the host does, and joins from the program's own start screen.

Every participant's computer holds the whole page.  Only changes travel,
through the relay, to everyone else.  Nothing is stored on the server.

The rest of this documentation describes Kokkoja from the guest's point of
view first, since the host sees the same screen and has a few more
buttons, then from the host's, and finally explains how it works
underneath, for those who want to run their own server or read the code.

* [Kokkoja in five minutes](quickstart.md), the shortest path for
  someone at home in a terminal
* [A guest's Kokkoja](guest.md)
* [A host's Kokkoja](host.md)
* [How Kokkoja works](implementation.md)