Module Structure

Q-Framework separates modules by layer. Each layer follows a unidirectional dependency principle.

Architecture Layers

┌─────────────────────────────────────────────────────────┐
│                   Application Layer                       │
│       (entities, capabilities, hooks written by devs)    │
├─────────────────────────────────────────────────────────┤
│                Q-Framework Layer                          │
│         (q-apt-*, q-context, q-runtime, q-util)         │
├─────────────────────────────────────────────────────────┤
│                  Q-Adapter Layer                          │
│         (q-spring-jpa, q-spring-boot, q-spring-webmvc)  │
├─────────────────────────────────────────────────────────┤
│                Host Framework Layer                       │
│              (Spring Boot, Spring MVC, JPA)             │
├─────────────────────────────────────────────────────────┤
│                Infrastructure Layer                       │
│                  (DB, filesystem, message queue)         │
└─────────────────────────────────────────────────────────┘

Dependency direction: top → bottom (unidirectional)

The Q-Framework layer does not depend directly on the host framework. The adapter layer handles that connection.

---

Backend Module List

Q-Framework Core Layer

Module	Role
q-apt-entity	Processes @QfEntity and entity field annotations (APT)
q-apt-capability	Processes @QfCapability, @QfPrivilege (APT)
q-apt-result-code	Processes @QfResultCode and generates code constants (APT)
q-context	Request context, user information, and organization information management
q-runtime	Metadata loading, registry, CRUD pipeline
q-util	Common utilities, encryption, serialization
q-management	CLI and operations tooling server

Q-Adapter Layer

Module	Role
q-spring-boot	Provides Spring Boot Auto-configuration
q-spring-webmvc	Auto-registers API endpoints via Spring MVC
q-spring-jpa	Implements data access via JPA

Dependency Diagram (Backend)

Application code
    │
    ├── q-apt-entity (annotationProcessor)
    ├── q-apt-capability (annotationProcessor)
    │
    ├── q-context
    ├── q-runtime
    │       └── q-util
    │
    ├── q-spring-boot
    │       ├── q-runtime
    │       └── spring-boot-autoconfigure
    │
    ├── q-spring-webmvc
    │       └── spring-webmvc
    │
    └── q-spring-jpa
            └── spring-data-jpa

---

Frontend Modules

Frontend modules are provided as npm packages (under the @softminds scope).

Module	Role
@softminds/q-ui-runtime	Backend metadata API integration and UI rendering engine
@softminds/q-coreui	Common UI components (framework-agnostic)
@softminds/q-vue	Vue 3 adapter
@softminds/q-nuxt	Nuxt 3 adapter

Frontend Dependency Principle

@softminds/q-coreui
    ← (does NOT depend on) @softminds/q-nuxt
    ← (does NOT depend on) @softminds/q-vue

q-coreui does not depend on any specific UI framework. q-vue and q-nuxt each serve as adapters.

Vue 3 Example

<script setup>
import { QfEntityView, QfEntityForm } from '@softminds/q-vue'
</script>

<template>
  <!-- Auto-renders list/detail/create/update views -->
  <QfEntityView client-app="app" entity="product" />
</template>

Nuxt 3 Example

<!-- pages/products/index.vue -->
<script setup>
// Nuxt auto-import
</script>

<template>
  <QfEntityView client-app="app" entity="product" />
</template>

---

Dependency Direction Rules

Allowed:     upper layer → lower layer
Prohibited:  lower layer → upper layer
Prohibited:  Q-Framework layer → Host Framework layer (direct)
Allowed:     Q-Framework layer → Host Framework layer (via adapter)

These rules are enforced by compile-time dependency checking.

---

Next Steps

• Execution Lifecycle — Compile-to-runtime processing flow
• SPI Extensions — Customizing the adapter layer