qbit-custom-apps/README.md

qbit-custom-apps

Status: 0.1 release line, built on QQQ 4.1 (4.1.0-RC.22) and qbit-user-role-permissions 0.33.0-RC.1. Published to the QRun-IO Gitea Maven registry only (https://git.kof22.com/api/packages/QRun-IO/maven); release candidates are 0.1.0-RC.N.

QBit that aims to let qqq apps register custom application screens declaratively — pages built from widgets, forms, and table views — without writing dedicated front-end components.

Type: Application QBit For: Developers building qqq apps that need bespoke screens beyond standard table CRUD

Why this exists

qqq's standard dashboard renders auto-generated screens from table metadata. Most apps eventually need pages that don't map to a single table — operator dashboards, configurator wizards, multi-step workflows that pull data from several sources, embedded Looker dashboards, etc. qbit-custom-apps is intended to let those screens be declared as metadata.

What it provides

The repository contains the following package layout:

src/main/java/com/kingsrook/qbits/customapps/
├── definition/   # CustomAppDefinition and related metadata
├── model/        # Data models backing custom apps
├── metadata/     # Metadata producers and registrators
└── widgets/      # Widget composition utilities

How it relates to other qqq repos

• Declared dependencies: qqq-backend-core, qqq-middleware-api (optional), qqq-middleware-javalin, qbit-user-role-permissions; test scope: qqq-backend-module-rdbms, qqq-backend-module-postgres. All versions come from the qqq-bom-pom import (4.1.0-RC.22).
• Inherits from: qbit-build-parent (in the qbit-bom repo).
• Frontend pair: Custom apps render via the standard qqq dashboard; no separate frontend component needed.

Known gaps

• Integration tests (CustomAppsPostgresTest) use a PostgreSQL Testcontainer, so building needs Docker.
• Pre-1.0: the metadata and permission model may still change between release candidates.
• Depends on QQQ 4.1 release candidates, so it is not yet pinned to a final QQQ 4.1.0.

License

Apache License 2.0 — see LICENSE.

Contributing

See CONTRIBUTING.md, CODE_OF_CONDUCT.md, CODE_STYLE.md, and SECURITY.md.