qqq-frontend-material-dashboard

ℹ️ Future direction: The qqq admin UI is being rewritten as qqq-frontend-next (Next.js 15 + Tailwind 4 + shadcn/ui). qqq-frontend-material-dashboard remains the supported choice today and will continue to receive fixes until existing qqq apps complete migration to qqq-frontend-next. New qqq apps starting in 2026 should evaluate qqq-frontend-next first.

React admin dashboard for QQQ applications.

For: Teams using QQQ who want a ready-to-use admin UI without writing frontend code
Status: Stable (on long-term deprecation track — see banner above)

Why This Exists

QQQ generates backend APIs automatically, but you still need a UI. This dashboard connects to any QQQ backend and renders:

• Table views with sorting, filtering, and pagination
• Record forms with validation
• Process execution screens
• Navigation based on your QQQ metadata

No frontend code required. The dashboard reads your QQQ metadata and builds the interface dynamically.

If you need a custom UI, use qqq-frontend-core directly instead.

Features

• Auto-generated screens - Tables, forms, and processes from QQQ metadata
• Material-UI styling - Clean, professional appearance out of the box
• Authentication - Auth0, OAuth2, or anonymous modes
• Customizable - Override components when defaults aren't enough
• Responsive - Works on desktop and tablet

Quick Start

Prerequisites: Node.js 20+, running QQQ backend

git clone https://github.com/QRun-IO/qqq-frontend-material-dashboard
cd qqq-frontend-material-dashboard
npm run install:legacy
npm start

Opens at http://localhost:3000. Point it at your QQQ server.

Configuration

Create .env:

REACT_APP_QQQ_API_BASE_URL=https://your-qqq-server.com/api

For authentication:

REACT_APP_AUTH0_DOMAIN=your-domain.auth0.com
REACT_APP_AUTH0_CLIENT_ID=your-client-id

Usage

Development

npm start              # Start dev server
npm test               # Run tests
npm run build          # Production build

Production Build

npm run build
# Output in build/ directory

With Maven (full QQQ integration)

mvn clean package -Pci

Verify published JAR notices

After staging the built UI in src/main/resources/material-dashboard/ (as the publishing orb does), package with the release profile to produce main, sources, tests and Javadoc JARs. Before publication, run the archive guard with the actual version's archive prefix:

mvn -Prelease -DskipTests -Dgpg.skip=true clean package
./scripts/check-packaged-notices.py target/qqq-frontend-material-dashboard-0.41.0-SNAPSHOT

This command verifies packaging only: it skips runtime tests and does not sign or publish. Existing runtime and hosted release gates are still required. The guard requires Python 3 and checks that every JAR contains exactly one META-INF/LICENSE and META-INF/NOTICE, byte-identical to the root files. It exits nonzero for missing archives, missing/duplicate entries or altered text. This is an explicit post-package check; the unchanged Circle orb does not invoke it automatically. It supplements the existing runtime and hosted release gates.

Project Status

Maturity: Stable, production use
Breaking changes: Follows QQQ versioning

Contributing

Submit issues and PRs to the main QQQ repository.

npm run install:legacy
npm test

License

Apache-2.0 - See LICENSE for details.