1 files changed, 92 insertions, 0 deletions
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..6192f64
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,92 @@
+# HTML activities - Draft 1
+
+## Premise
+
+XXX Improve the Sugar OS developer experience
+
+XXX Cross platform sugar activities -> future
+
+XXX What is Sugar.
+
+## Modules
+
+The framework is composed of various libraries, initially
+
+* activity
+* graphics
+* datastore
+* collaboration
+
+### Interface description
+
+Each module provides one or more interface descriptions which are language
+independent. A subset of object-oriented languages should be chosen, so that
+it's possible to implement these from all the languages we are interested
+to support. The description uses the Java syntax because unlike, for example,
+python and JavaScript it's explicit about types.
+
+For example, the datastore interface could look like
+
+    class Datastore {
+        DatastoreObject load();
+        void save(DatastoreObject object);
+    }
+
+XXX The interface is totally made up!
+
+XXX What about IDL? Even if we don't use them initially the tools might be
+useful at some point.
+
+### Implementation
+
+The implementation should be written as much as possible using web languages.
+But of course we will have the necessity to interact with native system
+components. The multi language nature of the interfaces will be useful here
+because it will allow to provide system specific implementation of certain
+interfaces and generically bridge to them from JavaScript. All the modules
+should provide a web fallback, which will allow to run the activity everywhere
+even if with degraded functionality.
+
+### Code style
+
+View source is a core part of the sugar experience, so any kind of code
+obfuscation should be avoided. This includes languages that compiles to
+JavaScript, like CoffeeScript.
+
+### Namespacing and package management
+
+We are using [volo](http://volojs.org) for namespacing and package management,
+both in the libraries and in the documentation.
+
+## Activities
+
+Activities are [open web apps](https://developer.mozilla.org/en-US/docs/Apps),
+their only specificity is that can make use of our libraries framework. On some
+platforms (Sugar OS for example) it might be necessary to generate boilerplate
+code, configuration or to package the app in a certain way to have it integrate
+with the system flawlessly. We will provide scripts to fully automate those
+tasks.
+
+## Implementation notes
+
+### Sugar OS
+
+* We should probably use firefox, as provided by upstream, to run activities.
+Chrome would probably be an equally good alternative. At some point we could
+just support both.
+* We should be able to customize it to look like a native activity without
+patching the code. We need to avoid showing any chrome UI (toolbar, menubar,
+etc) and to provide the X properties Sugar expects from an activity.
+* We can generate activity.info from the webapp manifest  when building a .xo.
+* The svg icon might be provided in a native/sugar-os directory of the web
+activity or something.
+* Communication between JavaScript and native code will be handled by a firefox
+extension and it will most likely go through DBus. pythonext might be an
+alternative but I'm not convinced we should get into pyxpcom again. We can use
+dom events to communicate between content and extension.
+* Icons should be shipped as part of the graphics library, we can write a
+script to sync them with the sugar-artwork repository.
+* The datastore interface should probably make use of HTML files support. I
+hope using local paths will work in a web activity.
+* To get full permission I suspect a web app needs to be installed. We will
+have to figure out if/how we can avoid that.