How scc-digitalhub/digitalhub-core works
DigitalHub CORE is a multi-module Java platform built around one central Spring Boot application, plus a large set of optional modules that plug in domain capabilities, execution backends, authentication, search, storage, and triggers.
Core application as the composition root
The application module is the runtime entry point. It wires together:
• REST controllers for the main resources
• security and token handling
• persistence configuration
• web socket configuration
• OpenAPI publishing
• API versioning and request handling
• configuration exposure and environment export
• the console UI
The application exposes resource-oriented controllers for:
• functions, projects, runs, tasks, workflows
• models, artifacts, data items, schemas, secrets
• users and user tokens
• logs
• context-specific operations such as search, trigger execution, and contextual resource views
It also has endpoint classes for:
• configuration
• well-known/discovery metadata
• versioned API handling and advice
The application is the central integration point where all modules converge.
Shared platform modules
Several modules provide the common substrate used everywhere else:
Common model and infrastructure layer
modules/commons defines:
• base resource types and DTOs
• metadata, spec, status, and state abstractions
• shared exceptions
• configuration property objects
• generic infrastructure interfaces such as Framework, Runtime, Processor, ProcessorRegistry, SpecFactory, ConfigurationProvider
• shared utility classes, Jackson helpers, and schema utilities
This module is the type system of the platform. It standardizes how resources, specs, statuses, and runtime abstractions look across the whole codebase.
Entity base layer
modules/entity-base provides:
• generic persistence entities
• base repositories and builders
• generic entity services and finalizers
• metadata builders for audit/versioning
• entity event abstractions
• query/filter support
• CBOR and map-to-CBOR conversion support
This is the persistence and lifecycle foundation used by each domain entity module.
FSM/lifecycle layer
modules/fsm provides:
• generic finite-state-machine support
• lifecycle managers and state transitions
• transition logic and invalid-transition protection
• lifecycle event types
This is used by run, trigger, and other stateful resources to keep state transitions consistent.
Relationship layer
modules/component-relationships adds:
• relationship metadata and persistence
• reusable relationships-aware entity services
• relationship managers
This is how the platform models links such as project ownership, run/function associations, and other cross-resource references.
Search layer
modules/component-search provides:
• generic indexing and search services
• search result and grouping models
• indexable entity service abstractions
This is the abstraction used by Lucene and Solr-backed search implementations.
Files and storage layer
modules/component-files provides:
• file store abstractions
• file metadata persistence
• upload/download models
• HTTP-based store support
This is the platform’s file/data artifact access boundary.
Authorization and credentials
modules/authorization manages:
• JWT/OAuth2 token issuance and validation
• user authentication context
• refresh/access token lifecycle
• resource sharing
• credentials service and schedulers
• dynamic credential providers used by jobs and user tools
This module is important because the platform gives executions temporary credentials derived from the authenticated user context.
Cloud and notifications
modules/component-cloud contains:
• cloud event listener abstractions
• entity event models
• websocket user notifications
This is the outbound event/notification path from entity changes to UI and external broadcasters.
Extensions
modules/component-extensions is the extensibility boundary:
• extension scanning
• extension definitions and schemas
• extension-aware entity services and controllers
This allows the platform to add new entity types or UI/API extensions without changing the core resource flow.
Labels, metrics, proxy, Envoy gateway
These modules add supporting concerns:
• labels as metadata resources
• metrics persistence and service abstractions
• proxy routing
• Envoy Gateway custom resource generation and management
Domain entity modules
Each entity module follows a very similar internal structure:
• model/spec/status types
• persistence entity and repository
• DTO/entity builders
• filters for query/search
• services or managers
• lifecycle/listener hooks
• relationship managers when needed
• optional indexing, metrics, or cloud listeners
Examples:
• entities/entity-project
• entities/entity-function
• entities/entity-run
• entities/entity-task
• entities/entity-workflow
• entities/entity-model
• entities/entity-dataitem
• entities/entity-artifact
• entities/entity-secret
• entities/entity-log
• entities/entity-trigger
Important patterns inside entity modules
• Persistence: repositories store entity state in the shared relational database.
• Filtering/search: entity-specific filters are converted to query criteria.
• Lifecycle: listeners and lifecycle managers handle state changes.
• Relationships: associated resources are tracked separately from the main entity row.
• Finalization: when a resource is removed or transitions, finalizers handle cleanup.
• DTO builders: internal entities are mapped to API-facing objects.
Runs, tasks, and lifecycles: the core execution flow
The most important functional flow in the platform is:
function definition -> runtime selection -> run creation -> task generation -> framework execution -> status/log updates -> persisted run state
Runs are central because they represent executable instances of functions. Tasks are the lower-level execution units produced from a run. Lifecycles ensure the run progresses through valid states.
The repository contains several layers that enforce this:
• modules/fsm for generic state transitions
• modules/runtime-base for runnable persistence and run lifecycle management
• application/core/runs for run-specific lifecycle processors and listeners
• entities/entity-run for persisted run state and metrics
• entities/entity-task for task-level records
The run lifecycle path is typically:
1
Main entry points: CoreApplication.java Core app · K8sBaseFramework.java K8s fw · FunctionEntityServiceImpl.java Functions · BaseCloudListener.java Cloud events
Components 34
Application
Spring Boot composition root and public API
- Core app · Main application wiring controllers, security, persistence, versioning, and UI hosting
application/src/main/java/it/smartcommunitylabdhub/core/CoreApplication.java - API layer · Versioned resource endpoints, context controllers, and advice
application/src/main/java/it/smartcommunitylabdhub/core/controllers/v1/base/FunctionController.java - App config · Security, OpenAPI, websocket, persistence, async, and versioning configuration
application/src/main/java/it/smartcommunitylabdhub/core/config/AppConfig.java - Run lifecycle · Run managers, lifecycle processors, listeners, and task coordination
application/src/main/java/it/smartcommunitylabdhub/core/runs/service/RunManagerImpl.java
Shared modules
Cross-cutting platform foundations and reusable services
- Commons · Shared resource model, spec/status abstractions, infrastructure interfaces, and schema utilities
modules/commons/src/main/java/it/smartcommunitylabdhub/commons/models/base/BaseSpec.java - Entity base · Generic entity persistence, repositories, DTO builders, and versioning support
modules/entity-base/src/main/java/it/smartcommunitylabdhub/core/services/BaseEntityServiceImpl.java - FSM · Finite-state-machine and lifecycle transition framework
modules/fsm/src/main/java/it/smartcommunitylabdhub/fsm/Fsm.java - Relationships · Reusable relationship metadata and services between entities
modules/component-relationships/src/main/java/it/smartcommunitylabdhub/relationships/RelationshipsManager.java - Search · Search and indexing abstractions shared by Lucene and Solr implementations
modules/component-search/src/main/java/it/smartcommunitylabdhub/search/service/SearchService.java - Files · Artifact/file storage abstractions and HTTP-backed stores
modules/component-files/src/main/java/it/smartcommunitylabdhub/files/service/FilesService.java - Auth · Authentication, token lifecycle, resource sharing, and dynamic credentials
modules/authorization/src/main/java/it/smartcommunitylabdhub/authorization/services/TokenService.java - Cloud events · Entity events and websocket notification path
modules/component-cloud/src/main/java/it/smartcommunitylabdhub/components/cloud/BaseCloudListener.java - Extensions · Extension scanning, schemas, and extensible entity controllers
modules/component-extensions/src/main/java/it/smartcommunitylabdhub/extensions/ExtensionManager.java
Domain entities
Resource-specific modules for core business objects
- Projects · Project entities, authorization-aware services, and sharing support
entities/entity-project/src/main/java/it/smartcommunitylabdhub/projects/service/ProjectEntityServiceImpl.java - Functions · Function model, persistence, relationships, indexing, and versioning
entities/entity-function/src/main/java/it/smartcommunitylabdhub/functions/service/FunctionEntityServiceImpl.java - Runs · Persisted run state, metrics, relationships, and notifications
entities/entity-run/src/main/java/it/smartcommunitylabdhub/runs/service/RunEntityServiceImpl.java - Tasks · Task persistence and filtering for execution units
entities/entity-task/src/main/java/it/smartcommunitylabdhub/tasks/persistence/TaskEntity.java - Workflows · Workflow entities, relationship handling, and versioned service layer
entities/entity-workflow/src/main/java/it/smartcommunitylabdhub/workflows/service/WorkflowEntityServiceImpl.java - Models · Model entities and metrics-aware lifecycle services
entities/entity-model/src/main/java/it/smartcommunitylabdhub/models/services/ModelManagerImpl.java - Artifacts · Artifact persistence, lifecycle, and relationship management
entities/entity-artifact/src/main/java/it/smartcommunitylabdhub/artifacts/services/ArtifactManagerImpl.java - Data items · Data item and table schema resources
entities/entity-dataitem/src/main/java/it/smartcommunitylabdhub/dataitems/services/DataItemManagerImpl.java - Secrets · Secret resource service and persistence
entities/entity-secret/src/main/java/it/smartcommunitylabdhub/secrets/SecretServiceImpl.java - Logs · Log persistence and query service
entities/entity-log/src/main/java/it/smartcommunitylabdhub/logs/service/LogServiceImpl.java - Triggers · Trigger resources and execution relationships
entities/entity-trigger/src/main/java/it/smartcommunitylabdhub/triggers/service/TriggerManagerImpl.java
Execution runtimes
Function and workflow execution adapters
- Runtime base · Runnable persistence, lifecycle, and runtime abstractions
modules/runtime-base/src/main/java/it/smartcommunitylabdhub/runtimes/base/AbstractBaseRuntime.java - Container rt · Container build/deploy/job/serve runtime implementation
runtimes/runtime-container/src/main/java/it/smartcommunitylabdhub/runtime/container/ContainerRuntime.java - Python rt · Python build/job/serve plus guardrail and openinference runtimes
runtimes/runtime-python/src/main/java/it/smartcommunitylabdhub/runtime/python/PythonRuntime.java - Model serve rt · Model-serving runtimes for MLflow, HuggingFace, sklearn, VLLM, and variants
runtimes/runtime-model-serve/src/main/java/it/smartcommunitylabdhub/runtime/huggingface/HuggingfaceServeRuntime.java - DBT rt · DBT transform runtime
runtimes/runtime-dbt/src/main/java/it/smartcommunitylabdhub/runtime/dbt/DbtRuntime.java - Flower rt · Flower client/server/application training runtimes
runtimes/runtime-flower/src/main/java/it/smartcommunitylabdhub/runtime/flower/app/FlowerAppRuntime.java - Hera rt · Hera build and pipeline runtime
runtimes/runtime-hera/src/main/java/it/smartcommunitylabdhub/runtime/hera/HeraRuntime.java - KFP rt · Kubeflow Pipelines build and pipeline runtime
runtimes/runtime-kfp/src/main/java/it/smartcommunitylabdhub/runtime/kfp/KFPRuntime.java - KubeAI rt · KubeAI text and speech serving runtime
runtimes/runtime-kubeai/src/main/java/it/smartcommunitylabdhub/runtime/kubeai/base/KubeAIRuntime.java
Infrastructure frameworks
Kubernetes, build, and orchestration backends
- K8s fw · Shared Kubernetes execution primitives, monitors, watchers, and runnable helpers
frameworks/framework-k8s/src/main/java/it/smartcommunitylabdhub/framework/k8s/infrastructure/k8s/K8sBaseFramework.java
Connections 48
- Core app → API layer: exposes · Publishes public REST surface
- Core app → App config: wires · Bootstraps infrastructure and security
- Core app → Run lifecycle: coordinates · Drives run lifecycle services
- Core app → Commons: uses · Shares platform model and interfaces
- Core app → Entity base: uses · Builds on base persistence services
- Core app → Auth: uses · Authenticates users and issues tokens
- Core app → Cloud events: notifies · Publishes entity events to UI and broadcasters
- Core app → Extensions: extends · Supports extensible entity/API surfaces
- Core app → Projects: manages · Hosts core project resource service
- Core app → Functions: manages · Hosts function resource service
- Core app → Runs: manages · Hosts run resource service
- Core app → Tasks: manages · Hosts task resource service
- Core app → Workflows: manages · Hosts workflow resource service
- Core app → Models: manages · Hosts model resource service
- Core app → Artifacts: manages · Hosts artifact resource service
- Core app → Data items: manages · Hosts data item resource service
- Core app → Secrets: manages · Hosts secret resource service
- Core app → Logs: manages · Hosts log resource service
- Core app → Triggers: manages · Hosts trigger resource service
- Core app → Container rt: loads · Activates container runtime module
- Core app → Python rt: loads · Activates Python runtime module
- Core app → Model serve rt: loads · Activates model-serving runtimes
- Core app → DBT rt: loads · Activates DBT runtime module
- Core app → Flower rt: loads · Activates Flower runtime module
- Core app → Hera rt: loads · Activates Hera runtime module
- Core app → KFP rt: loads · Activates KFP runtime module
- Core app → KubeAI rt: loads · Activates KubeAI runtime module
- Container rt → K8s fw: executes on · Uses Kubernetes primitives for build/deploy/job/serve
- Python rt → K8s fw: executes on · Uses Kubernetes-backed runtime primitives
- Model serve rt → K8s fw: executes on · Uses Kubernetes-backed serving infrastructure
- DBT rt → K8s fw: executes on · Uses Kubernetes-backed jobs
- Flower rt → K8s fw: executes on · Uses Kubernetes-backed runners
- Hera rt → K8s fw: executes on · Uses Kubernetes-backed pipelines
- KFP rt → K8s fw: executes on · Uses Kubernetes-backed pipelines
- KubeAI rt → K8s fw: executes on · Uses Kubernetes-backed serve workloads
- Run lifecycle → Runtime base: depends on · Run orchestration is built on runtime base abstractions
- Run lifecycle → FSM: uses · Applies lifecycle state machines
- Runs → Runtime base: persists · Run entity is stored via runtime base layer
- Runs → Cloud events: emits · Broadcasts run state changes
- Functions → Relationships: links · Tracks function relationships
- Functions → Search: indexes · Provides function search/index support
- Functions → Cloud events: emits · Broadcasts function changes
- Workflows → Relationships: links · Tracks workflow relationships
- Workflows → Search: indexes · Provides workflow search/index support
- Models → Cloud events: emits · Broadcasts model changes
- Artifacts → Files: stores · Uses file storage boundary for artifacts
- Data items → Files: stores · Uses file storage boundary for data items
- Secrets → Auth: secures · Uses credential and auth services