FAQ

FAQ

Frequently asked questions about QQQ framework development and usage. This document covers common questions from contributors and users.

Quick Links

• Home
• Developer Onboarding
• Common Errors
• Public API Overview

General Questions

What is QQQ?

QQQ is a Low-code Application Framework for Engineers that provides a complete foundation for building business applications. It uses a metadata-driven architecture where you define your data models, business logic, and UI through configuration rather than starting from scratch.

Who is QQQ for?

QQQ is designed for:

• Engineers who want to build applications quickly without boilerplate
• Teams that need consistent, maintainable application architecture
• Organizations that want to standardize their application development process
• Contributors who want to extend and improve the framework

Is QQQ open source?

Yes! QQQ is open source and welcomes contributions from the community. See Contribution Guidelines for how to get involved.

Development Questions

How do I get started with QQQ development?

1. Set up environment: Follow Developer Onboarding
2. Build locally: Use Building Locally guide
3. Understand architecture: Read High-Level Architecture
4. Pick an issue: Start with something marked "good first issue"

What are the system requirements?

• Java 17+ (required for QQQ features)
• Maven 3.8+ (for build system)
• Git (for version control)
• macOS (QQQ dev tools are macOS-optimized)

How do I build QQQ from source?

# Clone repository
git clone git@github.com:QRun-IO/qqq.git
cd qqq

# Install QQQ dev tools
./qqq-dev-tools/install.sh

# Build everything
mvn clean install

What's the difference between developing QQQ vs. using QQQ?

• Developing QQQ: Working on the framework itself (adding features, fixing bugs)
• Using QQQ: Building applications with the QQQ framework

This wiki focuses on developing QQQ - extending the framework for others to use.

Architecture Questions

What is QQQ's architecture?

QQQ uses a metadata-driven architecture with these key components:

• QInstance: Central metadata container for applications
• Actions: Business logic implemented as typed functions
• Backend Modules: Pluggable storage and data processing
• Middleware: HTTP servers, CLI tools, Lambda functions
• Frontend: React dashboard with Material-UI

See High-Level Architecture for detailed information.

How does QQQ handle data?

QQQ provides a unified data layer through backend modules:

• RDBMS: MySQL, PostgreSQL, SQL Server support
• MongoDB: Document database operations
• Filesystem: Local files and S3 integration
• SQLite: Embedded database for development

All backends implement the same interfaces, so your code works with any storage backend.

What is QContext?

QContext provides thread-local state management for QQQ operations:

• QInstance: Current application metadata
• QSession: User session and authentication
• Transaction: Database transaction context
• Action Stack: Call chain for debugging

Always initialize and clean up QContext when executing QQQ actions.

Contributing Questions

How do I contribute to QQQ?

1. Find an issue: Look for issues marked "good first issue" or "help wanted"
2. Set up environment: Follow Developer Onboarding
3. Create branch: Use GitFlow branching strategy
4. Make changes: Follow Code Review Standards
5. Submit PR: Follow Contribution Guidelines

What coding standards does QQQ use?

QQQ enforces strict standards:

• Checkstyle: Kingsrook-specific code style rules
• Coverage: 80% instruction, 95% class coverage minimum
• Formatting: 3-space indentation, next-line braces
• Documentation: Javadoc on public methods, flower-box comments

See Code Review Standards for complete details.

How do I add a new feature?

1. Design: Understand how it fits into QQQ's architecture
2. Implement: Follow established patterns and interfaces
3. Test: Meet coverage requirements and test thoroughly
4. Document: Update relevant documentation and examples
5. Submit: Create PR following contribution guidelines

See Feature Development for detailed guidance.

What if I find a bug?

1. Search issues: Check if it's already reported
2. Create issue: Provide clear reproduction steps
3. Fix it: If you can, create a fix following contribution guidelines
4. Test: Ensure your fix resolves the issue
5. Submit PR: Include issue reference and test coverage

Testing Questions

What testing framework does QQQ use?

QQQ uses modern Java testing tools:

• JUnit 5: Testing framework with lifecycle hooks
• AssertJ: Fluent assertions for readable tests
• JaCoCo: Code coverage analysis and enforcement
• BaseTest: QQQ's common test base class

See Testing for complete testing strategy.

How do I run tests?

# Run all tests
mvn test

# Run specific module tests
mvn test -pl qqq-backend-core

# Run with coverage
mvn test jacoco:report

# Check coverage thresholds
mvn verify

What test coverage is required?

QQQ enforces strict coverage requirements:

• Instructions: 80% minimum (build fails if below)
• Classes: 95% minimum (build fails if below)
• Lines: Monitored but not enforced
• Branches: Monitored but not enforced

How do I write tests for QQQ?

Extend QQQ's BaseTest class for consistent test setup:

public class MyActionTest extends BaseTest
{
   @Test
   void testMyFeature()
   {
      // BaseTest provides QContext and test setup
      // Your test logic here
   }
}

Build Questions

How do I build QQQ?

# Build everything
mvn clean install

# Build specific module
mvn clean install -pl qqq-backend-core

# Build with sample project
mvn clean install -P withSample

# Build for release
mvn clean install -P release

What build profiles are available?

QQQ has three build modes:

• Default: Core framework only
• Sample: Include sample project for testing
• Release: Maven Central publishing preparation

How does QQQ handle versioning?

QQQ uses custom versioning with GitFlow integration:

• develop: Continuous SNAPSHOT builds
• release/*: Release candidate builds
• main: Production releases
• hotfix/*: Emergency patch releases

See Branching & Versioning for details.

Module Questions

What modules should I include?

Start with the core and add what you need:

<!-- Always include core -->
<dependency>
    <groupId>com.kingsrook.qqq</groupId>
    <artifactId>qqq-backend-core</artifactId>
</dependency>

<!-- Add backend modules as needed -->
<dependency>
    <groupId>com.kingsrook.qqq</groupId>
    <artifactId>qqq-backend-module-rdbms</artifactId>
</dependency>

<!-- Add middleware as needed -->
<dependency>
    <groupId>com.kingsrook.qqq</groupId>
    <artifactId>qqq-middleware-javalin</artifactId>
</dependency>

How do I create a new backend module?

1. Implement interface: Extend QBackendModuleInterface
2. Register module: Use static initialization block
3. Add to project: Include in parent pom.xml
4. Test thoroughly: Ensure integration with QQQ core

See Feature Development for examples.

How do I extend the frontend?

QQQ's React dashboard is extensible:

• Custom widgets: Implement widget interfaces
• New components: Add React components
• Theme customization: Override Material-UI themes
• API integration: Connect to QQQ backend actions

Troubleshooting Questions

Build is failing - what do I do?

1. Check Java version: Must be Java 17+
2. Check Maven version: Must be 3.8+
3. Check coverage: Ensure tests meet thresholds
4. Check style: Run mvn checkstyle:check
5. Clean and rebuild: mvn clean install

Tests are failing - how do I debug?

1. Check test output: Look in target/surefire-reports/
2. Run single test: mvn test -Dtest=ClassName#methodName
3. Check coverage: Ensure you meet thresholds
4. Verify setup: Check QContext and test data setup

Checkstyle violations - how do I fix?

1. Import IDE settings: Use Kingsrook code style
2. Run locally: mvn checkstyle:check
3. Fix formatting: Use IDE auto-format
4. Check headers: Ensure Kingsrook copyright headers

Coverage too low - what do I do?

1. Add unit tests: Test all code paths
2. Test edge cases: Include error conditions
3. Mock dependencies: Use mocks for external calls
4. Check thresholds: Verify 80% instruction, 95% class coverage

Community Questions

How do I get help?

• Documentation: Start with this wiki
• Issues: Search existing GitHub issues
• Discussions: Use GitHub discussions for questions
• Team: Ask in team channels for urgent issues

How do I report a bug?

1. Search first: Check if already reported
2. Create issue: Use bug report template
3. Be specific: Include steps to reproduce
4. Provide context: Environment, versions, logs

How do I request a feature?

1. Search first: Check if already requested
2. Create issue: Use feature request template
3. Explain use case: Why is this feature needed?
4. Consider implementation: Is this feasible for QQQ?

How do I contribute documentation?

Documentation contributions are welcome:

• Wiki updates: Improve existing pages
• Code comments: Add Javadoc and examples
• Examples: Create working code samples
• Tutorials: Write how-to guides

Getting Help

Still have questions?

• Check documentation: This wiki covers most topics
• Search issues: Look for similar problems
• Ask community: Use GitHub discussions
• Team support: Reach out to maintainers

Want to contribute?

• Start small: Fix typos, improve documentation
• Pick issues: Look for "good first issue" labels
• Follow guidelines: Read Contribution Guidelines
• Ask questions: We're here to help you succeed

See Also

• Developer Onboarding - Development setup
• Common Errors - Troubleshooting