A JVM Runtime Governance Framework For Long-Running Systems

English | 中文

LingFrame is a JVM runtime governance framework for long-running systems.

It does not ask you to rewrite the system immediately, and it does not force an instant move to microservices.
It cares more about something more practical:

When a system has already been running for many years, cannot easily stop, and keeps getting harder to change,
can we first make it understandable, controllable, and evolvable again?

Many systems are not poorly designed.
They have simply lived too long and changed too fast.

If you remember LingFrame in only one sentence, let it be this:

LingFrame is not only responsible for loading lings into one JVM,
but also for keeping them governable, convergent, and cleanly unloadable over long-running runtime life.

• First time reading LingFrame: start with getting-started.md
• Want to quickly understand what problem it solves: read practical-entry.md
• Want to see how far the 0.3.0 architecture has already converged: read technical-entry.md
• Want to understand why LingFrame is designed this way: read WHY.md
• Want to understand what LingFrame insists on: read MANIFESTO.md

You do not need to read the whole documentation set in one pass.
LingFrame lets you stop at any point and continue later.

The current dashboard is already a usable governance control surface, not just a display page.

LingFrame is not just a plugin framework with a different name.
It is not a universal cure for monolith modernization either.

More precisely, it is:

• a runtime governance framework for long-running single-process systems
• a structural tool that helps legacy systems recover boundaries and control
• a governance model that allows lings to exist, but does not tolerate ling chaos

Its focus is not to add one more layer of features,
but to bring back under order the complexity that already exists in the system and is becoming increasingly uncontrolled.

• It does not only emphasize hot loading; it emphasizes disciplined hot unload: a ling is not considered done just because it can go offline, it should go through draining, cleanup, resource release, and state convergence
• It treats zero-leak hot unload as a formal goal: not simply by dropping the ClassLoader, but by making unload cleanup, resource eviction, and leak diagnostics part of long-running runtime mechanisms
• It converges long-running runtime order into one spine: invocation governance, runtime state, control surface, and monitoring events are not scattered pieces, but are being converged into one runtime kernel
• It stays strict about hot-update boundaries: for process-level contracts such as Shared API, it does not market unsafe-but-cool hot-update abilities

• monolithic systems that have been running for years and cannot be easily stopped or rewritten
• teams that want to gradually introduce ling isolation, canary release, rate limiting, circuit breaking, permission, and audit capabilities
• scenarios where runtime order needs to be restored first without completely overturning the existing system

• treating it as a replacement for microservices
• treating it as a pure front-end plugin marketplace or low-code assembly platform
• expecting one framework to eliminate business complexity automatically

LingFrame does not make decisions for the system.
It only tries to put decisions back where they should happen.

The focus of this stage is not to keep adding scattered outward-facing capabilities,
but to truly converge the governance mechanisms that already exist into a stable, reusable, explainable runtime spine.

The core scope clearly delivered in the current release includes:

• converging a unified governance pipeline around InvocationPipelineEngine and FilterRegistry
• making three execution modes explicit: NORMAL, SIMULATION, and GOVERN_ONLY
• letting ling invocation, Spring Boot 2 / 3 web governance, LingCore bean interception, and dashboard simulation share the same governance kernel
• converging runtime state into the dual-layer model of InstanceStatus and RuntimeStatus, written respectively by InstanceCoordinator and RuntimeCoordinator
• making DefaultLingLifecycleEngine explicitly responsible for lifecycle orchestration of deploy, reload, and unload
• formally bringing unload cleanup, resource eviction, and leak diagnostics into long-running runtime responsibilities, continuing to converge toward disciplined hot unload and a zero-leak goal
• letting SharedApiManager make the bootstrap boundary of Shared API explicit: preload, register packages, freeze the boundary, then load lings
• making the dashboard a real governance control surface with lifecycle operations, canary configuration, governance patches, simulation, metrics, and SSE event streams

In other words, LingFrame is no longer just a mechanism assembly.
It is converging toward a runtime governance kernel that can truly be maintained over the long term.

In real systems, the issue is often not missing features, but the growing frequency of situations like these:

• the system is still running, but no one dares to touch it
• boundaries still exist in name, but in reality they are getting blurrier and blurrier
• canary, circuit breaking, permission, and audit each exist somewhere, but without one unified runtime landing point
• restart is not absolutely unacceptable; unpredictability is

What LingFrame really cares about is only one question:

How do we keep a system from falling out of control during long-running life?

Not by piling on more rules,
but through clearer boundaries, a more stable governance spine, and more honest runtime feedback.

• JVM: JDK 17 / JDK 8
• Spring Boot: 3.x / 2.x
• the current public architecture is still ling isolation and governance inside a single process
• Shared API is a process-level public contract boundary: a brand-new shared package may be hot-loaded, but an already loaded contract does not support hot update or hot unload; contract changes require a process restart
• native support exists for canary release, circuit breaking, rate limiting, audit, permission, simulation, and governance observability
• external registries, configuration centers, and similar infrastructure may be integrated non-invasively

LingFrame does not pretend complexity does not exist.
It simply refuses to dump all complexity onto the user at once.

• Want to run it first: read getting-started.md
• Want to understand 0.3.0 from the implementation side: read technical-entry.md
• Want to see what role the dashboard plays in the current version: read dashboard.md
• Want terminology help: read glossary.md

If you stop here, that is completely fine too.

Special thanks to Gitee official channels and the open-source community for their recommendation and support!

Thanks to Gitee and Teacher Hongshu for providing fertile ground for the local open-source ecosystem, so that even foundational wheels can be seen. 👉 Visit the official Gitee primary repository

This project is an AtomGit G-Star Incubated Project.
Thanks to AtomGit for supporting and promoting open-source projects.