From Amarok Wiki

At #kde-ruby (on irc.freenode.net) there came a plan to develope some core-apps in ruby for KDE that will make their way to kde-core. We thought some time about what app could rock KDE and thought of writing some kind of whiteboard app. Just for you reader I'll call it KlipChart at the moment.

Now some made already thoughts about what KlipChart would need, what it should contain, what should it be able to do.

Please, see the Discussion-Page also.

Contents 1 (More or less) Decided 2 kelkos idea - redesigned 2.1 Foreword 2.2 Definition 2.3 Idea 2.4 Design 2.4.1 Server 2.4.2 Client 2.4.2.1 View-Layer 2.4.2.2 Computing-Layer 2.4.2.3 Transport-Layer 2.5 Architecture 2.5.1 Server 2.5.1.1 Message Module 2.5.1.2 Manage-Module 2.5.2 Client 2.5.2.1 Message Passing 2.5.2.2 File-Manager 2.5.2.3 File-Objects 2.5.2.4 Chat-Manager 2.5.3 GUI & Use-Cases 2.5.4 Footnote 3 kelkos idea - original 3.1 What for? 3.2 Parts 3.3 Modules 3.3.1 Server 3.3.2 Client 3.4 GUI 3.4.1 Server 3.4.2 Client 3.5 "Use-Case" 3.5.1 Starting a share 3.5.2 Joining a share 3.5.3 Adding a file 3.5.4 Creating a file 3.5.5 Closing a file 3.5.6 Leaving a session 3.5.7 Editing a file 3.5.8 Chatting 3.5.9 Creating a chat-room 3.5.10 Joining a chat-room 3.5.11 Leaving a room 4 To think of

(More or less) Decided

• Server/Client-Architecture
• Use Jabber-Protocol for message passing
• Starting with developing a "distributed editor" but already with hooks and hinges in the design for extending it to a fully featured whiteboard-app
• Editing should be visible for others in realtime, no "update, edit, commit"

kelkos idea - redesigned

Foreword

This is in many cases identically to the original idea, but i tried to get it written down more understandable. Maybe some reader think that I go already too much in detail, but I want to think it quite deep to search for problems that can occur. And the more detailed I describe my thoughts the more it should become clear what my goal is and the less we talk about different things while talking about the same words.

Definition

• User - any person that is connected to KlipChart
• Master-User - the person that invoked the Session and has some kind of 'Admin'-privileges inside that session.
• Share - the bundle of files that are opened inside the session to be viewed / edited. This is more or less what the user experience when he uses KlipChart
• Session - The more technical view of the share including the share as defined above + the list of users connected at the moment + the chats running.

Idea

With KlipChart you may work in a distributed way along with other people on the same file. Depending on the file-type the files are available read-only or read-write. You can even share files that could be edited inside KlipChart read-only to prevent the other users from editing it. While editing the files you can chat along with all other users in chatroom and open even new ones at need to get a better and more effective way of communication. KlipChart is not bound to one or a few specific file-types but shall be expandable to support all file-types necessary or wanted so that it doesn't restrict your way of work. The files you edit inside KlipChart are not 'changed' in any way so that you can directly open them from any other application as well and work on them without loss of information or need to export anything. When you want to work with other people on a given file you just open KlipChart, start a share and tell other people where they shall connect. Besides you can already open the files to be shared in KlipChart and even people that connect afterwards will get every file opened. So you don't have to wait for the other users before sharing your data. If you want to start a bigger share or a company want a central KlipChart-server for all the shares with even some user-control you can start the server-part of KlipChart as standalone application and configure it either via config-files or while the server is running with a special admin-tool that connects on the KlipChart-server. If you just use to share your local data directly from your PC KlipChart starts automatically a local-server so you don't need to bother about anything, but just can tell your co-workers your IP-adress so they may connect on your maschine.

Design

For the ability of starting the server as a standalone-app I would develop it indipendent from the client so that it would be two majors parts:

• Client
• Server

Server

The server is rather some kind of routing-system then a real central file-server. It just handles the passing of all message send by any client and giving them an unique stamp so you can see which message came before which afterward. While doing that it keeps a copy of each message and compute it on a copy of each open file so it has a recent version of all files there. This way new connected users can easily download every file opened and just start to work with the others.

So the Server does have two layers:

• Message passing
• Message logging

And beside that there is the whole managment of the users, sessions, ...

Client

The client is the most complex. Beside the communication-layer to talk to the server it needs all the KParts and GUI and the computing of the message that shall be send or that were recieved. For being able to handle that complexity I would split that app into different layers:

• View-Layer (GUI)
• Computing-Layer (Diff, Patch)
• Transport-Layer (sending and recieving the diffs)

This way the above mentioned chat just would be a special kind of file and we doesn't have to bother that much about that.

View-Layer

The easiest and fastest way would be just to use the KParts for the file-types for handling the display of the files. This way we can spare a lot of work

Computing-Layer

That layer will be a bit tricky. In the end the layer is some kind of wrapper for the View-Layer. It takes a KPart and enables it to create diffs of what have changed in the file in real-time and apply diffs from other clients on the file, letting the view inside the KPart be refreshed. Also in real-time.

Transport-Layer

That's where the magic gonna happen. You get the diffs from the Computing-Layer and pass them to the server on top of the Jabber-Protocol and recieve from the server the diffs from the other clients. While the Jabber-Protocol handle the message passing through the net this layer handles the in-application message passing. So that the diff of each file will be passed to the right file.

Architecture

Server

The Server has the two grand modules. First the Message-Module and second the Manage-Module.

While the Message-Module handles the routing and the message-flow (so it's in action permanently) the Manage-Module handles the permissions and get only in action if a user logs on the server, connects to a share or does anything on the share.

Message Module

The Message-Module has two sub-modules, the two layers mentioned in the design:

• Message passing
• Message logging

Since the message passing will be done mostly by jabber I won't write anything about it now. And the message logging will much look like the client for it will be doing more or less the very same thing:

   Take the diff and apply it on the prior version of the file so you get the recent version of the file

Manage-Module

The other major module is the Manage-Module. It has several sub-modules:

• User-Manager
• Session-Manager
• File-Manager

The Manage-Module interacts quite a lot with the Message-Module for it watches over it. Whether the right user get the right informations and may send that information he wants to ... It's doing all the permission stuff also. May that user log on, may he connect to that share. May he close a file?!, ...

Client

The Client has three sub-modules:

• Message Passing
• File-Manager
• Chat-Manager

Message Passing

That module handle the complete Transport-Layer. It wraps the diffs from the Computing-Layer into special envelopes that will be send via the Jabber-Protocol to the server which gets the information and passes them. So the informations from the other clients will be recieved by that module also. That information will be unenveloped and then passed inside the app to the right File-Object (got from the File-Manager) or the right Chat-Object (got from the Chat-Manager) (depends on the envelope) which then computes the information and shows the result in the GUI.

This would work quite easily, for the servers message module doesn't need to know anything about the content it's passes. Only the servers logging module. But that is more or less just a build-in client inside the server-app. We would only need to define the "look" of the envelope so the File-Object creates a valid envelope the other clients can handle. And the content inside the envelope doesn't matter the whole message passing system, neither on server nor on client side. Only the corresponding File-Objects, have to understand it. And if on both side works the same version of File-Object that can be guaranteed.

File-Manager

The File-Manager is inside the Computation-Layer, but a bit beside it. The Manager itself does no computing, but it holds and manages all the File-Objects that are open. So they can be accessed quite easily and all the loading / saving runs throught the File-Manager. That's why it stands a bit beside the Layers, for it is not directly involved in passing and computing the message but it does the administration stuff needed.

File-Objects

The File-Objects are really doing the computing. They contain the current version of the file and compute the diffs got by the message passing module. And if something changes inside the File-Object creates the diff and passes it to the message passing module. It also holds the KPart for displaying the file inside the GUI for the KPart is tight to the file it displays. So both of them are inside the File-Object and can be accessed as one from outside.

   Note : we have to think about forcing which kpart is used for a mime-type (Master-User ?) because one can have several kparts installed that can edit one mime-type.

Chat-Manager

Works quite like the File-Manager, but for specialized files: the Chats. So the Chat-Objects are quite like the File-Objects also.

GUI & Use-Cases

I haven't copied the things I wrote about the GUI and the use cases from my original idea, because it can be still read and I haven't really changed anything of that.

Footnote

The general idea of wrapping the KParts so they provide methods for the real-time distributed editing / viewing (the Computing-Layer) came from eskatos inside #kde-ruby. Thanks to him for that. I think this way the app is way easier and way more powerfull. For by this approach you can wrap each and every KPart that already exists and use it inside KlipChart.

kelkos idea - original

What for?

You can edit a text-document or an bitmap-image and share all you do with other ppl. For that you can either log on a central server or you can start up an local-server others may log onto. Then you can add files to that share and work together on them or create new files inside during the session. Each document added by any party to the session will be accessible for everyone logging into that session, even if loged into after the file was created or added. The session-master (the one that started the share) may close files from the session, the content of them will no longer be accessible for ppl joining afterwards. When someone disconnects from the session he will be able to save all files onto the disc. When the session-master disconnects the session will be closed, unless he names another one new session-master. During all the editing there will be a chat displayed below where you can discuss the changes you make or explain. You can create new "rooms" inside the session for better communication.

Once a session is closed it can't be opened again. You can only start a new session and adding all files again so it "looks like" the old session.

omur's comments/additions: [brain storming type]
* SVG images may be used instead of bitmap images
* I think, for convenience, server code must  be embedded into clients.
After user opens his client he may start a server session, then other
clients can connect to this server which lives in first client's
application. It would be very nice if we could add a feature to
transfer server role to another client in case of planned disconnection
of server or in case of a failure (crash, power outage etc.). Client with
server role will have admin rights (which are to be determined).
* Files should be added to a pool. They will reside on the storage of
contributing client. When other client wants to use/edit it, she will
download it to her computer first. A file may be added as read-only;
in this case it will not be available for real-time editing of multiple
clients.
File operations are:
1) View it: File will be copied to clients computer and will be opened in
a viewer or internally (depending on the preference probably).
2) Edit it:
 a) File type is supported for real-time editing of multiple clients
 (what's a short description of this :^) : File will be downloaded (what
 about big files?) and and white board magic will be applied.
 b) File type is not supported internally or user prefers to edit it by
 herself: File will be optionally locked (in the pool) and downloaded
 & opened with associated program. [Locking details to be discussed]
3) Download file.
4) Add, remove, move in the pool structure (folders etc. should be
available).
5) ?
* Server/admin user should be able to save list of files in a pool.
Those files will be available in the pool when the user supplying them
becomes online again. Clients should be able to save their list of
shares too.

Parts

So, if we want to achieve that we would need two major parts: client and server. The server can either be a standalone server or started from within a client (local-session).

omur's:
See above.

Modules

Server

The Server would have the following major modules:

• Connection-Manager
• Session-Manager
• User-Manager
• File-Manager
• Chat-Manager

The Connection-Manager is a singleton, handling all incoming network-connection and linking them to the right session. For every share that will be started the Connection-Manager invokes one Session-Manager. The Connection-Manager checks whether a given user (username & pw) may log onto the server and connect to a given session by asking the global User-Manager.

The Session-Manager will be the the main-object for every session / share started. It has an local User-Manager for handling what users may connect to the session, which user is the session-master and who is logged on. And it contains a File- and a Chat-Manager. The File-Manager hold all files and distributes the diffs when something changed. The Chat-Manager does similar, but for the chat. If you want to, the chat are nothing more then write-once files ;-)

As already mentioned, there are two types of User-Manager: One global for checking whether a user may log on a server, may create shares, .... and a local that is session-bound and handling in-session permissions.

If you want to, the Server is nothing more then some kind of "router" with a build-in logging function. It passes all change-event from one client to all others, stamping them with an unique-id (to garantee a safe state of the doc) and the clients perform the actual change locally, displaying the new, changed, text. And the logging is done so that every newly logged on client can get a valid copy of the file directly from the central server.

omur's:
You're of course free to think/discuss these details; but I think it's
still early for this stage of design.

Client

The Client has similar parts:

• Connection-Manager
• File-Manager
• Chat-Manager

The Connection-Manager handles all the network-stuff for loging into a session. And the File-Manager and Chat-Manager are some kind of clients for their counterpart on the server. They read all the server-side Manager tell them and display that.

GUI

Server

At first point: none. Complete administration about a client that logs on and "chats" with the server giving it the commands. And of course config-files. At a later point the admin-tool to log on the server and send the right commands can be made graphical also.

Client

Quite similar to like Kate looks now. But with some added Menubar-Items and a chat-window (expandable) below the editor-pane.

omur's:
Should be splitable like emacs, so user can see what other's are typing
etc.
Should have a file pool view (naturally).

"Use-Case"

Starting a share

A logs on the server (with username and password) and choose to start a new share (with a unique name [~ id]). So A will be the session-master and can set permissions who (of the server-users) may enter that session (default: all). After that everyone can join the session.

Joining a share

B logs on the server (with username and password) and chooses to join a session. He choose the name of the session to join and if he may he will be added to that session. If some files are added to the session already he downloads the most recent version of them.

Adding a file

Someone (A or B) just goes to "Menu"->"Open" and chooses what file he wants to add to the session. The file will be uploaded to the server and all clients got a notification, that the file is there.

Creating a file

Someone (A or B) chooses "Menu"->"New" and a blank file will be created (later he may choose what type of file he wants to create) and all clients get a notification, that the file is there.

Closing a file

The session-master (A) may choose to close a file. The file then will be deleted on server-side and all clients get a notification, so they may save the content before it will be closed.

Leaving a session

A normal user (B) choose "Menu"->"Leave" (to only leave the session) or "Menu"->"Disconnect" (to disconnect completly from the server). He will be able to save all files before the connection is shutted down. If he leaves (not disconnects) he may choose a new session to join or to start a new share. If the session-master (A) leaves or disconnects (same way as normal users do) he will be asked whether he wants to name a new session-master. If he does he leaves like any other user and his permissions will be moved to the user he chooses. If he don't name any new session-master all other users will be forced to leave the channel, allowing them to save the content.

Editing a file

Just focus the editor-pane and edit it like a normal text-editor ;-)

Chatting

Focus the input-line of the chat and write your message. Hit "enter" or the "Send"-button to send you're message to the server.

Creating a chat-room

"Chat"->"New room" and give the name of the room. No permission to be set, everyone inside a session may join every room inside the session.

Joining a chat-room

"Chat"->"Join room" and give the room to join. The room "Default" will always be created and everyone joining a session will automatically join that room.

Leaving a room

"Chat"->"Leave room" or just closing the tab.

--Kelko 23:36, 11 October 2006 (UTC)

To think of

• local server for just one share will be shut down once the share is closed
• no way to name a new session-master on local-server
• local server allow all that want to join (without pw or with one default-pw) to log onto it
• Saving session-data for some time (say, 1 month?)
• Permanent sessions for long-term projects?
• Chats have a log-funtion?
• Will files I add automaticly edited locally when edited inside KlipChart or do I have to choose after the editing whether the version inside KlipChart shall be stored locally?
• If a new file is available, do I have to choose where to save it at that moment, or after the session closed?
• When the Master-User disconnects, what should happen?
  • Close the whole session
  • Make another participant the Master-User?
    • Somebody, that has to be defined, before any work can be done in this session.
    • The one, that joined the session right after the Master-User
  • Make this behaviour configurable.