QBits are modular extensions that add functionality to QQQ applications. This guide covers QBit types, creation, development, and publishing.

• Home
• QBit Templates
• Existing QBits
• High-Level Architecture

QBits fall into three categories based on their purpose and scope:

Extend QQQ's infrastructure with new backends, authentication methods, or framework capabilities.

Examples:

• qbit-sftp-data-integration - SFTP file import/export
• qbit-webhooks - Inbound/outbound webhook support
• qbit-standard-process-trace - Process execution tracing

Use When:

• Adding new backend types (databases, APIs, storage)
• Implementing authentication/authorization systems
• Extending framework capabilities

Provide reference data that applications commonly need, with sync processes to keep data current.

Examples:

• US States and cities data
• Currency codes and exchange rates
• Industry classification codes

Use When:

• Sharing standardized reference data
• Data requires periodic synchronization
• Multiple applications need the same data

Complete mini-applications with entities, processes, and UI components.

Examples:

• qbit-user-role-permissions - Role-based access control
• qbit-workflows - User-defined workflow automation
• qbit-customizable-table-views - Table view customization

Use When:

• Building reusable application features
• Functionality includes user interface components
• Feature is complete and self-contained

Select the appropriate template for your QBit type:

# For extension QBits
gh repo create my-qbit --template QRun-IO/qbit-template-extension

# For data QBits
gh repo create my-qbit --template QRun-IO/qbit-template-data

# For application QBits
gh repo create my-qbit --template QRun-IO/qbit-template-application

Update Maven coordinates and dependencies:

<parent>
   <groupId>com.kingsrook.qqq</groupId>
   <artifactId>qbit-bom</artifactId>
   <version>LATEST</version>
</parent>

<artifactId>qbit-your-qbit-name</artifactId>
<name>QBit: Your QBit Name</name>

Each QBit must implement QBitInterface:

public class YourQBit implements QBitInterface
{
   @Override
   public String getName()
   {
      return "yourQBit";
   }

   @Override
   public QBitMetaData getMetaData()
   {
      return new QBitMetaData()
         .withName(getName())
         .withDescription("Description of your QBit")
         .withVersion("1.0.0");
   }

   @Override
   public void register(QInstance qInstance) throws QException
   {
      // Register tables, processes, widgets, etc.
   }
}

Depending on QBit type, add:

• Tables - Define entities and their metadata
• Processes - Business logic and workflows
• Widgets - Dashboard components
• Scripts - Automation scripts
• Reports - Report definitions

src/main/java/com/kingsrook/qqq/qbit/yourqbit/
├── YourQBit.java           # Main QBit class
├── model/
│   └── YourEntity.java     # Entity classes
├── metadata/
│   └── YourTableMetaDataProducer.java
├── process/
│   └── YourProcess.java
└── widget/
    └── YourWidget.java

QBits register their components during application startup:

@Override
public void register(QInstance qInstance) throws QException
{
   // Register tables
   qInstance.addTable(new YourTableMetaDataProducer().produce(qInstance));

   // Register processes
   qInstance.addProcess(new YourProcessMetaDataProducer().produce(qInstance));

   // Register widgets
   qInstance.addWidget(new YourWidgetMetaDataProducer().produce(qInstance));
}

QBits can depend on other QBits:

@Override
public List<QBitDependency> getDependencies()
{
   return List.of(
      new QBitDependency("qbit-user-role-permissions", "1.0.0")
   );
}

• Repository: qbit-descriptive-name
• Package: com.kingsrook.qqq.qbit.descriptivename
• Class: DescriptiveNameQBit
• Metadata names: Use lowerCaseFirstCamelStyle

Make QBits configurable:

public class YourQBitConfig
{
   private Boolean enableFeatureX = true;
   private String defaultValue = "default";

   // Fluent setters
   public YourQBitConfig withEnableFeatureX(Boolean enable)
   {
      this.enableFeatureX = enable;
      return this;
   }
}

• Minimum 80% instruction coverage
• Minimum 95% class coverage
• Test all registration paths
• Test integration with other QBits

Each QBit should include:

• README.md - Overview, installation, configuration
• CHANGELOG.md - Version history
• Javadoc - API documentation

QBits follow semantic versioning aligned with QQQ core:

• Use qbit-bom as parent POM
• Inherit version management from BOM
• Release alongside QQQ when breaking changes occur

QBits are published to Maven Central:

<dependency>
   <groupId>com.kingsrook.qqq</groupId>
   <artifactId>qbit-your-qbit-name</artifactId>
   <version>1.0.0</version>
</dependency>

1. Update version in pom.xml
2. Update CHANGELOG.md
3. Create release branch
4. Run CI/CD pipeline (uses qqq-orb)
5. Tag and publish to Maven Central

• High-Level Architecture - QQQ architecture overview
• Core Modules - Core framework modules
• Compatibility Matrix - Version compatibility
• QBIT_TYPE_TAXONOMY.md - Detailed type definitions