complete Studio core and JavaFX boundary migration
Intrepid/Prometeu/Studio/pipeline/pr-master Build started...
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 64.01% (20482/31999)
* Branch Coverage: 54.22% (8240/15196)
* Lines of Code: 31999
* Cyclomatic Complexity: 13164
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 15, passed: 715
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
Intrepid/Prometeu/Studio/pipeline/pr-master Build started...
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 64.01% (20482/31999)
* Branch Coverage: 54.22% (8240/15196)
* Lines of Code: 31999
* Cyclomatic Complexity: 13164
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 15, passed: 715
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
This commit is contained in:
+103
@@ -0,0 +1,103 @@
|
||||
---
|
||||
id: LSN-0075
|
||||
ticket: studio-core-javafx-decoupling
|
||||
title: Studio Services Must Outlive the Current UI
|
||||
created: 2026-09-25
|
||||
tags: [studio, architecture, spring, spring-modulith, javafx, adapters]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Prometeu Studio began as a desktop application in which JavaFX controls, application workflows, provider integrations, background execution, and lifecycle management shared one Gradle module. A static `p.studio.Container` made these dependencies easy to reach, but it also made the visual adapter the practical center of the product. That shape could not support another consumer, such as a future agent adapter, without either driving the UI or duplicating Studio behavior.
|
||||
|
||||
The migration needed to preserve the existing Java product and its behavior while making JavaFX replaceable. It also needed to preserve the autonomy of compiler, LSP, runtime, and especially `p.packer`; separating Studio did not authorize absorbing those domains.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Human and non-visual adapters consume the same Studio services
|
||||
|
||||
**What:** The Studio is physically divided into `prometeu-studio-api`, `prometeu-studio-core`, `prometeu-studio-ui-javafx`, and `prometeu-app`. JavaFX depends on the neutral API, Core implements application use cases, and the application module composes concrete adapters.
|
||||
|
||||
**Why:** The stable boundary is UI versus application services, not JavaFX versus a future web framework. A future agent can depend on the same API without moving application rules out of Core.
|
||||
|
||||
**Trade-offs:** More constructor parameters and explicit contracts are required. That cost is intentional: dependencies are visible, testable, and constrained by Gradle instead of hidden behind a global container.
|
||||
|
||||
### Spring is a composition mechanism, not a domain dependency
|
||||
|
||||
**What:** Spring Boot runs in non-web mode only in `prometeu-app`. Core objects remain constructor-injected POJOs. Spring Modulith verifies the six functional Core modules: project, session, assets, shipper, runtime, and execution.
|
||||
|
||||
**Why:** Spring provides deterministic construction and lifecycle without contaminating the public API or Core. Modulith supplies executable documentation and dependency checks while Gradle remains the physical classpath boundary.
|
||||
|
||||
**Trade-offs:** The application configuration is deliberately explicit. Broad component scanning and turning JavaFX controls into Spring singletons would recreate hidden ownership and lifecycle problems.
|
||||
|
||||
### Provider boundaries follow stability, not uniformity
|
||||
|
||||
**What:** Core uses a provider's public API directly when it is stable and neutral. It owns a narrow port when the available integration is static, concrete, lifecycle-oriented, or otherwise unsuitable for Core. Packer's stable API is consumed directly; compiler static access, LSP lifecycle, and runtime process integration are isolated behind consumer-owned gateways implemented in `prometeu-app`.
|
||||
|
||||
**Why:** Wrapping every dependency creates redundant abstractions, while importing concrete implementations leaks infrastructure into Core. The useful boundary depends on the provider contract.
|
||||
|
||||
**Trade-offs:** The integration matrix must be reviewed case by case. There is no universal rule that every provider receives a gateway.
|
||||
|
||||
### Long-running work is a neutral application contract
|
||||
|
||||
**What:** Build, pack, and execution expose `OperationHandle<R>` with identity, snapshots, completion, cancellation, updates, and typed results. The application owns the executor implementation; JavaFX only projects operation state and switches to the FX thread.
|
||||
|
||||
**Why:** Background work must be equally consumable by JavaFX and future adapters. An executor or JavaFX `Task` is an implementation detail, not an application contract.
|
||||
|
||||
**Trade-offs:** Cancellation races and terminal state transitions require explicit tests. In particular, stopping execution must cancel the outer execution handle before its nested preparation handle can complete it successfully.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
The dependency pattern is:
|
||||
|
||||
```text
|
||||
JavaFX adapter ---> Studio API <--- future adapters
|
||||
^
|
||||
|
|
||||
Studio Core
|
||||
^
|
||||
|
|
||||
Spring non-web composition
|
||||
```
|
||||
|
||||
External providers remain outside the Core module graph. Stable public provider APIs may be direct Core dependencies; concrete adapters remain in the application module.
|
||||
|
||||
Operational failures that a caller can recover from are returned as typed results or diagnostics. For example, metadata writes convert I/O failures into `AssetMetadataWriteResult`. JavaFX renders that result and does not treat an unexpected exception message or stack trace as a functional contract.
|
||||
|
||||
The removal sequence for a service locator is also reusable:
|
||||
|
||||
1. establish architecture tests and final modules;
|
||||
2. introduce neutral contracts and explicit factories;
|
||||
3. move behavior slice by slice into constructor-injected services;
|
||||
4. reduce static call sites to zero;
|
||||
5. delete the static container and manual composition together;
|
||||
6. remove the mixed legacy module;
|
||||
7. run the full build, packaging, desktop smoke, and shutdown gate as one indivisible acceptance step.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Renaming packages without changing Gradle dependencies does not create a replaceable frontend.
|
||||
- Replacing `Container` with `ApplicationContext.getBean()` throughout the code is still a service locator. Context lookup belongs only at the explicit application bootstrap boundary.
|
||||
- Registering every control or dialog as a Spring singleton gives Spring ownership of visual lifecycle and makes multiple windows or future adapters harder.
|
||||
- A gateway that merely mirrors a stable provider API adds indirection without protection. Conversely, direct use of static or concrete provider entry points leaks infrastructure into Core.
|
||||
- Moving Packer behavior into `p.studio.core.assets` would reverse domain ownership. Studio coordinates Packer; `p.packer` remains independently consumable.
|
||||
- Returning raw exception messages to JavaFX turns implementation accidents into an unstable user-facing protocol. Expected failures need neutral results or diagnostics.
|
||||
- Marking the migration complete after compilation alone misses packaging, restoration, real JavaFX interaction, cancellation, and shutdown leaks.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- The durable product boundary is the Studio service surface, not the current frontend technology.
|
||||
- Spring belongs in composition; Spring Modulith belongs in verification and documentation; neither belongs in the neutral API.
|
||||
- Gradle modules enforce physical isolation, while functional Core modules express ownership and allowed dependencies.
|
||||
- JavaFX is an equivalent adapter, not the owner of project, asset, build, runtime, or execution rules.
|
||||
- `Container` removal is a completion criterion, not an optional cleanup step.
|
||||
- A future agent module can now be added as another API consumer without revisiting this migration or coupling AI concerns to JavaFX.
|
||||
|
||||
## References
|
||||
|
||||
- Decision: `DEC-0059` — Separate Studio Core from JavaFX with Spring Boot non-web and Spring Modulith.
|
||||
- Plan: `PLN-0138` — Complete Studio Core and JavaFX Boundary Migration.
|
||||
- Studio architecture: `docs/specs/studio/9. Studio Core and Adapter Architecture Specification.md`.
|
||||
- Studio specifications: `docs/specs/studio/README.md`.
|
||||
- Packer boundary: `docs/specs/packer/1. Domain and Artifact Boundary Specification.md`.
|
||||
- Packer integration: `docs/specs/packer/5. Diagnostics, Operations, and Studio Integration Specification.md`.
|
||||
Reference in New Issue
Block a user