lumiera_documentation/doc/design/application/index.txt

The Application Realm
=====================

// Menu :  prepend child ApplicationStart

Shaping the outside world through software requires a variety of effective mechanisms
that capture, represent, and transform elements of reality. A well-designed part is
focused on a single aspect, is coherent and cohesive in itself, with links to other
parts based on concepts and abstraction rather then on shared technology. Yet this
structural perspective must be complemented by a meaningful overall arrangement that
supports the desired workflow and can be adapted to circumstances.

In software systems, such coherency does not emerge spontaneously. It must be supported
by definition work to establish suitable terms and interfaces, components must be
interconnected and configured, and the overall state needs coordination.
An application is therefore more than just a collection of software components.

In the Lumiera Architecture, this application realm is embodied into a structure
called the »**Vessel**«:

- it is built as a library with only basic linkage to the support library
- it can be invoked from a `main()` function, with an argument parser
- at source code level, it provides all the types and definitions
  required to express the _binding_ between components
- _conceptually,_ all layers are encased in the _application vessel_
- and while the Vessel can not just ``control'' the configuration of parts
  on upper layers, it has to bootstrap their ability to adapt to circumstances.

--
&nbsp;
--

Dependencies::
  While the code base is organised into _three layers,_ the actual implementation
  structures are arranged into **Subsystems** that _depend_ on each other and
  can be _started and shut down_
+
-> link:ApplicationStart.html[Subsystems and Lifecycle]

Configuration::
  As a means to adapt to the environment and enable flexibility,
  this topic is surprisingly intricate and development has barely scratched
  the surface: while the effective configuration is assembled from several
  layered sources, the meaning (and documentation) of individual settings
  is scoped, and users can expect the ability to override some settings
  from within the application.
+
-> link:Config.html[Configuration]
Application: Adjustments to the Layer structure During the last months, a lot of gradual changes to policies and guidelines had been finalised and documented. Moreover, recent clarifications regarding memory management in the render engine will lead to a clearer definition of the »Vault« Layer's role, with some ''engine code'' expected to move down. On this occasion, I reworked relevant sections in the documentation to confirm the role that now falls to central parts of the overall architecture. Notably I decided to rename those parts related to the application backbone as »Vessel« — to underpin the more active and defining role they assumed. 2026-02-28 22:55:09 +01:00			`The Application Realm`
			`=====================`
Move in the existing documentation outline from the Website-repository 2010-11-14 23:19:07 +01:00
DOC: rename the old SubsystemLifecycle page ..at that time, that page was hastily written do document an somewhat controversial implementation draft, which later on evolved into the Application-main object Lumiera relied on since then. Recently, a dedicated page dealing with subsystems and lifecycle has been added to the Architecture section; so this page here should be rewritten to focus on the "Application realm" as such. 2020-02-23 03:06:31 +01:00			`// Menu : prepend child ApplicationStart`

Application: Adjustments to the Layer structure During the last months, a lot of gradual changes to policies and guidelines had been finalised and documented. Moreover, recent clarifications regarding memory management in the render engine will lead to a clearer definition of the »Vault« Layer's role, with some ''engine code'' expected to move down. On this occasion, I reworked relevant sections in the documentation to confirm the role that now falls to central parts of the overall architecture. Notably I decided to rename those parts related to the application backbone as »Vessel« — to underpin the more active and defining role they assumed. 2026-02-28 22:55:09 +01:00			`Shaping the outside world through software requires a variety of effective mechanisms`
			`that capture, represent, and transform elements of reality. A well-designed part is`
			`focused on a single aspect, is coherent and cohesive in itself, with links to other`
			`parts based on concepts and abstraction rather then on shared technology. Yet this`
			`structural perspective must be complemented by a meaningful overall arrangement that`
			`supports the desired workflow and can be adapted to circumstances.`
Move in the existing documentation outline from the Website-repository 2010-11-14 23:19:07 +01:00
Application: Adjustments to the Layer structure During the last months, a lot of gradual changes to policies and guidelines had been finalised and documented. Moreover, recent clarifications regarding memory management in the render engine will lead to a clearer definition of the »Vault« Layer's role, with some ''engine code'' expected to move down. On this occasion, I reworked relevant sections in the documentation to confirm the role that now falls to central parts of the overall architecture. Notably I decided to rename those parts related to the application backbone as »Vessel« — to underpin the more active and defining role they assumed. 2026-02-28 22:55:09 +01:00			`In software systems, such coherency does not emerge spontaneously. It must be supported`
			`by definition work to establish suitable terms and interfaces, components must be`
			`interconnected and configured, and the overall state needs coordination.`
			`An application is therefore more than just a collection of software components.`
Move in the existing documentation outline from the Website-repository 2010-11-14 23:19:07 +01:00
Application: Adjustments to the Layer structure During the last months, a lot of gradual changes to policies and guidelines had been finalised and documented. Moreover, recent clarifications regarding memory management in the render engine will lead to a clearer definition of the »Vault« Layer's role, with some ''engine code'' expected to move down. On this occasion, I reworked relevant sections in the documentation to confirm the role that now falls to central parts of the overall architecture. Notably I decided to rename those parts related to the application backbone as »Vessel« — to underpin the more active and defining role they assumed. 2026-02-28 22:55:09 +01:00			`In the Lumiera Architecture, this application realm is embodied into a structure`
			`called the »Vessel«:`

			`- it is built as a library with only basic linkage to the support library`
			- it can be invoked from a `main()` function, with an argument parser
			`- at source code level, it provides all the types and definitions`
			`required to express the _binding_ between components`
DOC: minor wording improvements 2026-03-04 12:52:04 +01:00			`- _conceptually,_ all layers are encased in the _application vessel_`
Application: Adjustments to the Layer structure During the last months, a lot of gradual changes to policies and guidelines had been finalised and documented. Moreover, recent clarifications regarding memory management in the render engine will lead to a clearer definition of the »Vault« Layer's role, with some ''engine code'' expected to move down. On this occasion, I reworked relevant sections in the documentation to confirm the role that now falls to central parts of the overall architecture. Notably I decided to rename those parts related to the application backbone as »Vessel« — to underpin the more active and defining role they assumed. 2026-02-28 22:55:09 +01:00			- and while the Vessel can not just ``control'' the configuration of parts
			`on upper layers, it has to bootstrap their ability to adapt to circumstances.`

			`--`
			` `
			`--`

			`Dependencies::`
			`While the code base is organised into _three layers,_ the actual implementation`
			`structures are arranged into Subsystems that _depend_ on each other and`
			`can be _started and shut down_`
			`+`
			`-> link:ApplicationStart.html[Subsystems and Lifecycle]`

			`Configuration::`
			`As a means to adapt to the environment and enable flexibility,`
			`this topic is surprisingly intricate and development has barely scratched`
			`the surface: while the effective configuration is assembled from several`
			`layered sources, the meaning (and documentation) of individual settings`
			`is scoped, and users can expect the ability to override some settings`
			`from within the application.`
			`+`
			`-> link:Config.html[Configuration]`