Internal Design Docs

This section documents the internal design and implementation of the core framework. It will primarily be of interest to committers and contributors to the framework.

We also include some design documentation - where it provides useful context - in the end-user documentation set (the user guide, reference guide, security guide and testing guide).

Modules

There is a section for most of the core modules:

CodeGen (Proxy Factory) using Byte Buddy - utliity service to create dynamic proxy objects
Commons - an extensive library of common utilities (though not intended as an end-user API)

Note that this module does not reside in core/ directory, instead it is to be found in ../commons directory instead
Interaction - declares the @InteractionScope to Spring. Also defines the internal data structures that keep track of the action invocations and property edits performed within the interaction.

An "interaction" is normally the same duration as a web request, whereby a short-lived persistence session is created using a connection from a database connection pool.
Internal Test Support - utility classes for unit testing the framework’s own classes.
MetaModel - classes that are used to build the internal metamodel by introspecting the domain classes.

Many of the services defined (as interfaces) in the applib have implementations defined in this module (the rest are defined in Runtime Services, below).

The documentation in this module explains (with diagrams) the concepts at both a high and more detailed level.

As you might have guessed, this is the largest module within the framework.
Runtime - a very small module providing a set of classes to handle the runtime context. It also has classes that trigger events for when the metamodel is fully built (after bootstrapping), and to emit events for transaction boundaries.
Runtime Services - provides an extensive set of domain services.

Many of the services defined (as interfaces) in the applib are actually implemented in this module (the rest are defined in MetaModel, above).
Transaction - a small module providing a set of classes primarily concerned with for tracking changes to entities during transactions.
Webapp - classes used to bootstrap the app itself, also providing hooks for other components to contribute their own filters and servlets into the web request pipeline.

As a simplification, the MetaModel module handles domain types (cf java.lang.Class) while the Runtime and Runtime Services modules handle domain object instances (cf java.lang.Object). That said, Spring Boot is responsible for instantiating domain service instances, while the persistence mechanisms (JPA and JDO) — which are not part of the core modules — handle the lifecycle of entity instances.

There are also two core modules not listed above, because their documentation are both part of the end-user docs:

the docs for the core/config module consistitute the Configuration Guide
the docs for the core/security module consistitute the Security Guide

Generated Index

This is probably a good place as any to mention that the documentation/website procedures include tooling to automatically create AsciiDoc reference documentation for any Java class in the codebase.

This is used extensively for the classes in the applib; these can be referenced using the form xref:refguide:applib:index/xxx.adoc[].

For example xref:refguide:applib:index/annotation/DomainObject.adoc[] resolves to @DomainObject.

But the index is also available for internal classes, such as those in core/security, which can be found under xref:refguide:core:index/security/xxx.adoc[]

For example, xref:refguide:core:index/security/authentication/Authenticator.adoc[] resolves to Authenticator.

Not every class is generated into the index, but all that is required is to include {@index} in the class-level javadoc.