This is the primary catalog for all hoist-core documentation. It indexes feature-area docs, upgrade notes, and supporting guides — with descriptions and key topics to support fast, targeted retrieval.
AI coding agents: Scan the tables below and match the Key Topics column against the APIs, classes, or patterns you're working with. Use the Quick Reference by Task table to map natural-language goals to the right document.
Application developers: Navigate by feature area to find architecture, configuration, and usage patterns. Start with the Core Framework table for foundational concepts, then drill into Core Features or Infrastructure.
Library developers: In addition to the docs below, see
/AGENTS.md for coding conventions, architecture patterns, and code style guidance.
See planning/docs-roadmap.md for documentation coverage tracking
and conventions.
| If you need to... | Start here |
|---|---|
| Understand a Hoist app's directory structure and boilerplate | application-structure.md |
| Choose a JDK for your app build, or work around the Gradle 8.x / JDK 25 incompatibility | application-structure.md |
| Understand BaseService lifecycle and resource factories | base-classes.md |
| Understand BaseController / RestController patterns | base-classes.md |
| Trace an HTTP request through the framework | request-flow.md |
| Implement authentication in your app | authentication.md |
| Set up roles and access control | authorization.md |
| Resolve role memberships from LDAP / Active Directory or Entra ID groups | directory-services.md |
| Query a corporate directory for users or groups | directory-services.md |
| Work with AppConfig (soft configuration) | configuration.md |
| Work with user preferences | preferences.md |
| Cache computed or fetched data in a service | caching.md |
Work out why a cache onChange handler fires when it does |
caching.md |
| Understand Hazelcast clustering and distributed resources | clustering.md |
| Add activity tracking or review track logs | activity-tracking.md |
| Serialize or parse JSON | json-handling.md |
| Set up application monitors | monitoring.md |
| Publish observable metrics (Prometheus, OTLP) | metrics.md |
| Add distributed tracing to your app | tracing.md |
| Push messages to clients via WebSocket | websocket.md |
| Make HTTP calls to external services | http-client.md |
| Send emails from your app | email.md |
| Understand the exception hierarchy | exception-handling.md |
| Configure logging or read logs | logging.md |
| Work with GORM domain objects and Hibernate | gorm-domain-objects.md |
| Understand the build pipeline and GitHub Actions | build-and-publish.md |
| Publish a release to Maven Central | build-and-publish.md |
| Write or review a hoist-core library CHANGELOG entry | changelog-format.md |
| Look up the authoritative coding conventions for hoist-core | coding-conventions.md |
| Install or extend the hoist-core MCP server and CLI tools | ../mcp/README.md |
| Upgrade to a new major hoist-core version | Upgrade Notes |
Foundational patterns that everything else builds on.
| Document | Description | Key Topics |
|---|---|---|
base-classes.md |
Base classes for services and controllers — lifecycle, resource factories, CRUD patterns | BaseService, init/destroy, createCache, createCachedValue, createTimer, createIMap, BaseController, renderJSON, parseRequestJSON, RestController, doCreate/doList/doUpdate/doDelete |
request-flow.md |
How an HTTP request flows through the Hoist framework | HoistCoreGrailsPlugin, HoistFilter, UrlMappings, HoistInterceptor, controller dispatch, JSON response |
authentication.md |
Authentication service contract and user identity | BaseAuthenticationService, BaseUserService, HoistUser, IdentityService, impersonation |
authorization.md |
Role-based access control and controller security annotations | BaseRoleService, DefaultRoleService, Role, RoleMember, @AccessRequiresRole, @AccessAll, built-in roles |
directory-services.md |
Corporate directory integration for role resolution, username mapping, and LDAP-backed login | DirectoryService, LdapService, EntraIdService, Active Directory, Microsoft Graph, xhLdapConfig, xhEntraIdConfig, directoryGroupProvider, usernameAttribute, ErrorOr |
Bread-and-butter features used by every Hoist application.
| Document | Description | Key Topics |
|---|---|---|
configuration.md |
Database-backed soft configuration with typed values | AppConfig, ConfigService, clientVisible, pwd encryption, xhConfigChanged, required configs |
preferences.md |
User-specific settings and preference management | Preference, UserPreference, PrefService, local flag, required prefs |
caching.md |
Managed in-memory caching with optional expiry and cluster replication | Cache, CachedValue, CacheEntry, createCache, createCachedValue, expireTime, expireFn, replicate, onChange handlers, ensureAvailable, culling |
clustering.md |
Hazelcast-based multi-instance coordination and distributed data structures | ClusterService, Cache, CachedValue, IMap, ReplicatedMap, Topic, primaryOnly timers |
activity-tracking.md |
Usage and performance logging with email notifications | TrackLog, TrackService, categories, elapsed timing, client error emails, feedback emails |
json-handling.md |
Jackson-based JSON serialization and parsing | JSONSerializer, JSONParser, JSONFormat, custom serializer modules, renderJSON, parseRequestJSON |
Features supporting production operations, integrations, and system health.
| Document | Description | Key Topics |
|---|---|---|
monitoring.md |
Application health monitoring with configurable checks and email alerting | Monitor, MonitorResult, MonitorService, MonitorEvalService, MonitorReportService, MonitorDefinitionService, email alerts |
metrics.md |
Micrometer-based observable metrics with Prometheus and OTLP export | MetricsService, CompositeMeterRegistry, BuiltInMetricsService, MonitorMetricsService, TrackMetricsService, Prometheus, OTLP, xhMetricsConfig, xhMetricsPublished |
tracing.md |
OpenTelemetry-based distributed tracing with OTLP export | TraceService, withSpan, traceparent, OTLP, Zipkin, xhTraceConfig, OpenTelemetry |
websocket.md |
Cluster-aware server push to connected clients | WebSocketService, HoistWebSocketHandler, HoistWebSocketChannel, channel subscriptions |
http-client.md |
HTTP client for external API calls and request proxying | JSONClient, BaseProxyService, HttpUtils |
email.md |
Email sending with config-driven filtering and overrides | EmailService, xhEmailFilter, xhEmailOverride, support address config |
exception-handling.md |
Exception hierarchy and error rendering | HttpException, RoutineException, ExceptionHandler, HTTP status mapping |
logging.md |
Logging infrastructure with dynamic configuration | LogSupport, logDebug/logInfo/logWarn/logError, LogLevelService, LogReaderService |
Guides to Grails framework concepts as used within Hoist applications.
| Document | Description | Key Topics |
|---|---|---|
gorm-domain-objects.md |
GORM domain classes, querying, transactions, caching, associations, and performance optimization | Domain classes, @Transactional, @ReadOnly, second-level cache, N+1 queries, fetch strategies, SQL logging |
Guides to building, structuring, and deploying Hoist applications.
| Document | Description | Key Topics |
|---|---|---|
application-structure.md |
Standard Hoist application repository layout — server and client structure, build configuration, deployment, JDK choice | build.gradle, gradle.properties, grails-app/init/, client-app/, Bootstrap.ts, AppModel, Docker, Nginx, Tomcat, JDK 17/21/25, Gradle toolchain |
build-and-publish.md |
Gradle build, GitHub Actions CI, and Maven Central publishing | GitHub Actions, deployRelease.yml, deploySnapshot.yml, Sonatype, GPG signing, nexus-publish-plugin, publishToSonatype, hoist-core-mcp, Toolbox repository_dispatch, XH Build Bot GitHub App, maven-archive.xh.io (legacy 36.x-and-earlier hoist-core releases) |
../mcp/README.md |
Hoist-core MCP server and CLI tools — architecture, app-side install snippet, tools reference, and maintenance checklist | hoist-core-mcp, hoist-core-docs, hoist-core-symbols, installHoistCoreTools, BundledContentSource, ContentSource, bootstrap.sh, doc-registry.json |
changelog-format.md |
Conventions for writing and reviewing hoist-core library CHANGELOG entries | Section headers, voice/tense, Simplified Technical English, difficulty ratings, breaking changes, libraries, application changelogs |
Authoritative standards references for working with hoist-core code and the surrounding workflow.
| Document | Description | Key Topics |
|---|---|---|
coding-conventions.md |
Authoritative coding conventions for hoist-core framework and applications | Naming (xh prefix, env vars), logging (LogSupport, withInfo/withDebug), exceptions (RoutineRuntimeException, HttpException), services (BaseService, resource factories, clearCaches discipline), controllers (mandatory access annotations, renderJSON/parseRequestJSON), GORM (@ReadOnly/@Transactional, N+1 avoidance, JSONFormat), clustering (primaryOnly, replicate, serializability), HTTP/email/background work, Groovy idioms, commit/PR formatting |
Step-by-step guides for upgrading applications across major hoist-core versions, with breaking changes, before/after code examples, and verification checklists.
Always check the latest version of these notes on the
developbranch on GitHub. Upgrade notes are refined after release as developers report issues and new patterns emerge.
| Version | Key Changes |
|---|---|
| v41.0.0 | EntraIdService + DirectoryService for Entra ID directory groups, typed ErrorOr results from doLoadUsersForDirectoryGroups, xhLdapConfig.usernameAttribute |
| v40.0.1 | Grails 7.1, MetricsService registration API, BaseService.telemetryPrefix, ObservedRun metrics by-name, hoist.* → xh.* built-in metric rename, client-side metrics endpoint |
| v39.0.0 | Typed ConfigSpec / PreferenceSpec / RoleSpec, optional TypedConfigMap opt-in, telemetry package restructuring, alwaysSampleErrors removed, JDK 25 toolchain |
| v38.0.0 | LogLevel schema additions, OTEL tag alignment, rule-based span sampling |
| v37.0.0 | OpenTelemetry distributed tracing (TraceService), MCP server for AI agents, xhMetricsPublished opt-in, MetricsService namespace prefixing removed |
| v36.0.0 | Cluster-aware WebSockets, new @AccessRequiresXXX annotations, @Access deprecated |
| v35.0.0 | CacheEntry generic key type, TrackLog clientAppCode, POI 5.x |
| v34.0.1 | Grails 7, Gradle 8, Tomcat 10, Jakarta EE |
/AGENTS.md— AI coding assistant guidance: architecture patterns, coding conventions, and key dependenciesplanning/docs-roadmap.md— Documentation coverage tracking, conventions, and guidelines/CHANGELOG.md— Version history and release notes/README.md— Project overview: what Hoist is, the role of the server, and how a Hoist app is built and deployed- hoist-react docs — Client-side counterpart documentation