hsweb-framework: End-to-End Reactive Admin Panel Architecture

Reactive from end to end, not just in name

Spring Boot 2.x runs hsweb through every layer, from the HTTP handler to the database query. Rather than bolting Project Reactor callbacks onto a synchronous Spring MVC app, hsweb commits to reactive code paths throughout: Spring WebFlux handles the web layer, R2DBC with the hsweb easy-orm wrapper handles database access, and transaction control operates reactively. Most Java frameworks patch async onto synchronous cores; hsweb builds the core async. A steep learning curve follows if you have not used Project Reactor before. According to the README, you should understand Project Reactor and Spring Boot before adopting hsweb. If you have built with Reactor elsewhere, hsweb follows patterns you already know. If you have not, expect weeks of ramp-up before your team writes code confidently.

Permission and role management as a first-class feature

Multi-dimensional permission control comes with hsweb by default, including role-based access control (RBAC) and data-level permissions. You can write rules that let a manager see only their division's data without fetching the full table and filtering in code. According to the README, mark a controller method with @SaveAction, and hsweb wraps it with permission checks. Built-in user management and permission assignment mean a new admin system does not start from scratch. Note that two-factor authentication remains unimplemented.

DSL-driven queries that sidestep SQL injection

Query construction happens through a fluent Java API, not string concatenation. According to the README, createQuery().where("name", name).fetch() becomes a prepared statement with the name parameter bound by hsweb. No template syntax to parse exists, and no risk of a developer dropping user input directly into a string follows. Updates work the same way: createUpdate().set(user::getName).where(user::getId).execute(). Compile-time type safety eliminates entire classes of injection flaws. JPA-like annotations (@Table, @Id, @Column) make data classes look familiar to anyone who has used Hibernate.

Setting up an entity and querying it

Start by defining an entity class with hsweb annotations. According to the README, mark it with @Table and name the database table, then mark each field with @Column. Here is the example from the README:

@Table(name = "s_entity")
public class MyEntity {

    @Id
    private String id;

    @Column
    private String name;

    @Column
    private Long createTime;
}

Once defined, inject the reactive repository and use it to query and save. According to the README, the pattern is:

@Autowire
private ReactiveRepository<MyEntity, String> repository;

With the repository injected, you can save, update and query without writing SQL. Create a new entity, call repository.save(entity), and hsweb handles the insert. Read the examples linked in the README for more complete patterns.

Eight modular components for selective adoption

Rather than pulling the entire framework, you choose which modules your application needs. hsweb-authorization handles permission control, hsweb-datasource manages database connections, hsweb-concurrent covers caching, and hsweb-system provides user and permission management. According to the README, cloning the repository and building from source is not recommended; instead, depend on specific modules from Maven. Once released to the central repository, each module can be versioned independently. hsweb-logging handles logging and hsweb-starter bootstraps modules, reducing boilerplate in a new application.

Database support limited to R2DBC drivers

hsweb commits to reactive-only access and supports only databases with R2DBC drivers: H2, MySQL, SQL Server and PostgreSQL. If your system relies on a database without a maintained R2DBC implementation, hsweb cannot be used. No path to synchronous JDBC access exists; the README lists non-reactive support (Spring MVC, JDBC) as a planned but incomplete feature. Not a limitation of the framework's design, but a choice: hybrid applications cannot use hsweb for the reactive parts and JdbcTemplate for the others.

Project Reactor as a prerequisite, not an option

Every piece of code you write in hsweb works with Project Reactor types: Mono for single values, Flux for streams. No wrapper hides them behind a simpler API. Hiding Reactor would obscure what your code actually does and lead to surprises when reactive behavior becomes visible (errors do not throw; they emit to an error handler). You must be comfortable reading Reactor documentation and debugging reactive pipelines. Learning cost is front-loaded; after ramp-up, the mental model stays consistent.

Editorial conclusion

hsweb-framework is for Java teams building admin or backend management systems and ready to adopt reactive programming throughout the stack. Do not choose it if your team has no experience with Project Reactor, or if you need synchronous database access alongside the reactive parts. Verify that your database driver supports r2dbc before committing; the framework supports H2, MySQL, SQL Server and PostgreSQL, but your specific version and configuration may not.

Frequently asked questions

Official sources

1. hs-web/hsweb-framework on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases