# qbit-custom-apps

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

> **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](./LICENSE).

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md), [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md), [CODE_STYLE.md](./CODE_STYLE.md), and [SECURITY.md](./SECURITY.md).