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 document 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 A4 in size, lying on its side. When writing approaches an edge, the page grows in that direction, so you are never short of room. An image is placed at its natural size; one wider than the page is scaled down to fit, and the page grows to hold an image taller than it or further images below.

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. A guest joins by opening a link in a web browser, and a host can start a session from the web site in the same way. Someone who wants a notebook of real files on their own computer, a teacher with a notebook per student for instance, installs the small Kokkoja program instead.

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 of paper, Kokkoja puts that page 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 in the picture 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. A host can also do without it and start the session from the web site, like guest A, with the notebooks in the browser.

• 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, the shortest path for someone at home in a terminal
• A guest's Kokkoja
• A host's Kokkoja
• How Kokkoja works