From d60ff44c8161f970d9852982979a3523cebb1ec6 Mon Sep 17 00:00:00 2001
From: Ben Fortuna <fortuna@nodelogic.au>
Date: Fri, 12 Apr 2024 09:59:24 +1000
Subject: [PATCH] Updated docs

---
 README.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 96 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 388b1c5..229961f 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,104 @@
 # Coucal
 
-A mixed content API for collaborative data.
+A platform built for collaboration.
 
 ## Overview
 
-Coucal is an application that provides support for managing a variety of collaborative activities through a mixed
-content API.
+Coucal is a modular application for managing a variety of collaborative activities. Coucal can be run in different
+configurations, supporting both serverless and embedded web server options.
+
+Coucal consists of four distinct modules: The Core, Commands, Channels, API and Stream Handlers. All modules utilize 
+HK2 for dependency injection and Java reactive steams for asynchronous message passing.
+
+
+## The Core
+
+The Core module implements persistence and management of user content and system data. The Coucal data model is based
+on utilizing standard formats such as iCalendar and vCard to represent both system and user data.
+
+System and content managers provide an abstraction layer to managing CRUD operations for calendar and card data,
+including support for filtering, versioning and auditing consistency.
+
+Change notifications are published to registered subscribers asynchronously via reactive streams.
+
+The Core is independent of all other modules, and can be used to manage calendar and contact information stored in
+compatible data stores.
+
+
+## Stream Handlers
+
+The Stream Handlers module provides reactive stream subscribers that respond to specific notifications with predefined
+and configurable actions.
+
+Handlers use dependency injection to discover and subscribe to relevant streams.
+
+Some handlers may act as both a subscriber and publisher of stream data, whereby they implement a transformation 
+of data for consumption of other stream handlers.
+
+### Change Handlers
+
+Change handlers subscribe to change notifications from data managers, and may include both configurable
+(e.g. workflows) and fixed action implementations.
+
+### Channel Handlers
+
+Channel handlers subscribe to channel notifications and are concerned with data flowing in and out of the Coucal
+platform.
+
+
+## Channels
+
+The Channels module supports integration with external channels for sending and receiving data. Channels are
+configurable, and may include multiple simultaneous options for publish and ingestion of data.
+
+
+## Commands
+
+The Command module provides encapsulated actions invoked by Stream Handlers in response to stream activity.
+Commands may be used to interact with channels directly or update content. 
+
+Coucal defines a default collection of commands, however is designed to be extensible for customization of workflows.
+
+
+## API
+
+The API is the primary interface for Coucal, supporting authenticated access to content and system
+management functions. The API consists of RESTful controllers, Channel callbacks and other API-related concerns
+(e.g. serialization, authentication, etc.).
+
+
+## Runtime Modes
+
+Coucal provides multiple runtime modes to support different use-cases. Specifically these are a command line
+interface (CLI), embedded web server, and serverless.
+
+### Command Line Interface
+
+The Coucal CLI is actually used to bootstrap all runtime modes, however it also supports command execution without
+bootstrap. For example, you can invoke a command to create a new event, which will exit on completion of that
+command.
+
+A full list of CLI commands is available using the following command:
+
+    $ coucal --help
+
+### Embedded Web Server
+
+The embedded web server exposes endpoints use to access the Coucal API and callbacks for Coucal channels. You can
+bootstrap the web server with the following command:
+
+    $ coucal server
+
+### Serverless
+
+The serverless runtime mode is actually just a proxy to the embedded web server, deployed to a compatible serverless
+environment. Currently only AWS Lambda is supported.
+
+
+
+
+
+
 
 ### What is mixed content?