High Level Architecture

High-Level Architecture

QQQ uses a metadata-driven architecture where applications are defined through configuration rather than code.

Core Architecture

┌─────────────────────────────────────────────────────────────┐
│                    QInstance (Metadata)                      │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│  │ Tables/Data  │ │ Actions/Logic│ │ Processes/Automation │ │
│  └──────────────┘ └──────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌──────────────┐     ┌──────────────┐      ┌──────────────┐
│   Backend    │     │  Middleware  │      │   Frontend   │
│   Modules    │     │    Layer     │      │              │
├──────────────┤     ├──────────────┤      ├──────────────┤
│ RDBMS        │     │ Javalin HTTP │      │ React        │
│ Filesystem   │     │ PicoCLI      │      │ Material-UI  │
│ MongoDB      │     │ Lambda       │      │              │
│ SQLite       │     │ Slack        │      │              │
└──────────────┘     └──────────────┘      └──────────────┘

Design Principles

Metadata-First

Everything is defined through metadata in the QInstance:

• Tables - Data structure, relationships, validation rules
• Actions - Business logic with Input/Output contracts
• Processes - Multi-step workflows and automation
• UI - Dashboard layouts, widgets, forms

Action-Based Architecture

Business logic lives in AbstractQActionFunction implementations that define Input/Output contracts.

Context Management

QContext provides thread-local state management for QInstance, sessions, transactions, and action execution.

Pluggable Backends

Backend modules implement QBackendModuleInterface to provide storage and processing capabilities.

Request Flow

Client → Javalin → Route Resolution → Action Execution → Backend → Database
                                                                      │
Client ← JSON/HTML ← Response ← Output ← Data ←────────────────────────

Extension Points

Extension	Interface	Purpose
Backend Modules	QBackendModuleInterface	Add storage backends
Actions	AbstractQActionFunction	Custom business logic
Metadata Producers	MetaDataProducerInterface	Define metadata types
Middleware	Various interfaces	Protocol support

See Core Modules for module details.