Specification for New Cobalt Architecture - code name: Sausalito
Jonathan Mayer, Tim Hockin
Version:  1.2





Table of contents:
-----------------

1. Objectives and Design Goals
   ---------------------------

2. Requirements
   ------------

3. Architecture
   ------------
   3.1. Overview
   
   3.2. New backend

   3.3. New Sauce layer

   3.4. New UI abstraction

   3.5. New internationalization layer

4. Design
   ------
   4.1. New backend - Cobalt Configuration Engine (CCE)

   4.2. New Sauce layer

   4.3. New UI abstraction

   4.4. New internationalization layer

   4.5. New package/module format

5. New Cobalt development methodology
   ----------------------------------
   5.1. Test harness

   5.2. Adherence to test harness

   5.3. Nightly builds

   5.4. Parallel development of modules

   5.5. API definition

Appendix A: Changelog




1. Objectives and Design Goals
======================================================================

* Branding:
	Cobalt products have historically focused on low price, simplicity,
	and ease of use.  We must continue these goals, and ensure that the
	new architecture focuses on the things that have made Cobalt
	products successful to date.  The goal is not a completely
	flexible, general purpose PC, but an appliance that meets the needs
	of the vast majority of end users, and is simple to extend by the
	vast majority of third-party developers.

* Hardware independence:
	The new software architecture must not be inherently tied to a
	hardware form-factor.  There is no reason to support some functions
	on one system, and not on another.

* Modularization:
	It is imperative that the new architecture be modular to every extent
	possible.  To ease upgrade and new development issues, and to
	enable third-party developers to be most successful, we must
	minimize change.  We must isolate independent pieces of
	functionality and provide a structure which can be extended,
	without being modified.
	
* Internationalization:
	Internationalization must be pervasive.  All aspects of the system
	must be ready for internationalization, and there must be a well
	defined way for third-party developers to internationalize their
	own extensions.
	
* Security:
	One of the most important things we must do is make sure our system
	is safe.  Safe from known malicious attacks, and, as much as
	possible, from unforseen attacks.  This includes verifying access
	to every system change.

* Robustness:
  	Part of safety is the ability to handle unknown or bad situations
	gracefully.  We must ensure that error cases and unknown situations
	are accounted for, and handled simply, elegantly, and consistently.

* Testability:
  	As the architecture develops, we must build in hooks for thorough,
	repeatable, and exhaustive testing.  This includes automated
	testing and human testing.
  
* Extensibility:
  	We must make it easy for Cobalt or third-party developers to extend
	and expand the Cobalt system.  It must be well documented, well
	abstracted, and well modularized, in order to accept new features
	easily and without system-wide changes.

* Configurability:
  	The architecture should be able to be configured in a relatively
	easy manner, with results that affect the whole system.  This
	includes colors, styles, graphics, etc.

* APIs:
  	Part of making this appliance a platform for third-party
	developers, is providing a well-defined set of constructs to
	manipulate the system.  This is a matter of abstracting operations
	cleanly and vowing to maintain interfaces through future products.
  
* Language independence:
  	It should be feasible to configure the system from any language.
	Ideally, the system will not care what language is used to access
	it, but realistically we may just work on providing as much
	compatibility as possible.  This includes
	installations/uninstallations as well as run-time events.

* Clusterability:
  	One of the long-term goals of the architecture must be to ensure
	and maintain the ability to be clustered.

* Accountability:
  	The system must be capable of logging every event and transaction,
	and optionally be verbose about its operation.


2. Requirements
======================================================================

The following is a list of requirements that must be met by the
architecture.

General:
	Development tools must be present on default system
	There must be an automated test harness with test modes  for all 
	  modules
	There must be a standard way to access services of components
	There must be a standard way of performing error checking
	Software modules must not conflict 
	There must be robust version control at the object level
	There must be a safe way of doing configuration recovery
	There must be robust dependency management between modules
	They system must be OO
	Simplicity is a key goal
	There must be a a restriction on pre-processed code in the system
	APIs must be stable and change minimally between releases
	There must be a robust event management mechanism
	There must be a robust method of package version control
	There must be an easy way to add/remove software modules
	There must be a method of protecting Intellectual Property
	There must be a general mechanism for accessing LEDs/LCD
	There must be a published technical document, covering mechanisms to
  	  configure the system, as well as extending and programming the system
Backend:
	There must be standard ways to access daemons
	There must be standard ways to add/remove hooks for ActiveMonitor
	There must be common, well defined set of data types for the system
	There must be a seperation between UI and sauce and data

Sauce:
Frontend:
	There must be a standard method to add pages/subsystems to the UI
	There must be a method to change system-wide UI configuration
	There must be a standard way to handle URL redirections/rewrites
	There must be a way to edit UI navigation controls
i18n:
	There must be a way to add/remove locales 
	There must be a way to add/remove localized resources
	Internationalization must be pervasive


3. Architecture
======================================================================

3.1. Overview

   	The new architecture consists of several parts.  The system is
	divided into tiers of resposibility, and abstracted so that any
	layer can change its internal design, and keep the API to other
	tiers consistent.  This has implications that all cases must be
	cleanly provided for by tier boundaries, and that data displayed to
	users is isolated from internal representations.

Diagram 1: Architectural overview
---------------------------------
  -----------               ----
 | UI Engine |---outputs-->| UI |--uses---|           
  -----------               ----          V 
    |   -------                      -------------
    |->| Sauce |                    | i18n Engine |<----|
        -------                      -------------      |
           |                                          uses
           |         ---------              ---------   |
           |-calls->| Backend |--invokes-->| Handler |--| 
                     ---------              ---------

3.2. New backend

   	The backend, which is responsible for storing data and making
	system changes, is a database of persistent objects.  These objects
	track data about various entities in the system, and have
	mechanisms to actuate data changes.  Communication with the backend
	is via a socket and defined API.  The database is the final stop
	for data, and when a conflict is detected, the database is
	considered to have the correct data.  Transactions must be
	protected, and data rolled back if errors are found in a
	transaction.

3.3. New Sauce layer

   	The middle tier is what has historically been the special-sauce.
	The new sauce will be wrapper calls to backend functionality and
	libraries tied in to the UI engine.  This will be PHP3, called from
	code inline in UI pages.  Common functions will be provided as
	libraries.

3.4. New UI abstraction

	The UI layer, which has historically been HTML and CGI must be
	abstracted.  We can use PHP3 - an inline programming language - to do
	dynamic generation of UI pages.  This allows us to move towards
	themability, to have packages register their own UI components, and
	to implement internationalization seamlessly.

3.5. New internationalization layer

	The internationalization engine is a C library, which is provided to
	the sauce as a set of PHP3 routines.  There may also be Perl wrappers
	for this library, as well as wrappers for commonly needed languages.


4. Design
======================================================================

4.1. New backend - Cobalt Configuration Engine (CCE)
	See CCE.specification.txt
	See CSCP.spec

4.2. New Sauce layer
	See UI abstraction section

4.3. New UI abstraction
	See uiArchDesign.txt

4.4. New internationalization layer
	See spec.i18n.lib.txt

4.5. New package/module format
	FIXME: TBD


5. New Cobalt development methodology
======================================================================
FIXME: TBD



Appendix A - Changelog
======================================================================
$Log: Sausalito.spec.txt,v $
Revision 1.1  2000/03/16 00:27:31  jmayer
One more old spec file.

Revision 1.10  1999/12/15 01:17:09  thockin
Added references to UI Arch Design spec

Revision 1.9  1999/12/15 00:55:36  thockin
Some changes:
Implementation section removed - this is a spec
Sauce/i18n references cleaned up
Closer to a finished document...

Revision 1.8  1999/12/14 21:21:34  thockin
Tue Dec 14 1999  Tim Hockin <thockin@cobalt.com>
 - Some reorg
 - started list implementation
 - need to pause and create test routines, before I continue
 - need to pause to finish docs

Revision 1.7  1999/12/09 20:39:50  thockin
Some doc updates
Checking in before revising the (currently hodgepodge) internal API for i
the ODB - a lot of reuse can be found.

Revision 1.6  1999/12/02 19:43:50  thockin
* Wed Dec 02, 1999  Tim Hockin <thockin@cobalt.com>
- Merged CSCP spec with jonathans overview of states.
- Added 'bogo-object' concept to spec
- lots of FIXMEs taken care of
- general cleanup, typos
- updated Security Model to reflect new discussions
- BG command allows transition from status -> read state
- more still needed wrt permissions
- almost done with CCE section.  merges/references from Sausalito.spec.txt
  still needed.

Revision 1.5  1999/12/01 21:49:23  tim
o Fixed some typos as I read through.

Revision 1.4  1999/11/19 21:45:42  thockin
Small changes, reqs section

Revision 1.3  1999/11/17 19:47:21  thockin
Overhaul:
   * Sausalito.spec is underway
   * CSCP.spec and ESCP.spec have been split from CCE.spec
   * lots of comments added to various files - grep for FIXME for my
     questions so far
   * I will continue on this more today, I just wanted to do a commit
     before I forgot

Revision 1.2  1999/11/13 03:49:55  thockin
Small updates to TOC sec 5

Revision 1.1  1999/11/13 03:36:49  thockin
First check in.  TOC is partly done, document fill-out to come.

