Execution Lifecycle

Q-Framework processes everything from declaration to execution through a 3-stage lifecycle.

Overview

Authoring Time  →  Compile Time  →  Runtime

Developer decl.    APT processing    Metadata loading
Write annotations  Contract check    Registry setup
                   Metadata gen.     Request automation

---

Stage 1: Authoring Time

The stage where developers declare domain contracts using annotations.

// This is all a developer needs to write
@QfEntity(
    appKey = "app",
    name = @QfI18n(defaultMessage = "Product", texts = { @QfI18nText(locale = "ko", message = "상품") }),
    autoHistoryEnabled = true
)
@QfCapability(key = "product_management")
public class ProductEntity {

    @QfListAttribute(sortable = true)
    @QfDetailAttribute
    @QfCreateAttribute(requiredOn = @QfRequiredOn(always = true))
    @QfUpdateAttribute
    @QfSearch
    @QfDisplayLabel(text = "Product Name")
    private String name;

    @QfListAttribute(sortable = true)
    @QfDetailAttribute
    @QfCreateAttribute
    @QfUpdateAttribute
    @QfDisplayLabel(text = "Price")
    private Integer price;
}

Q-Framework's role at authoring time:

• Provides annotation definitions
• Supports IDE code completion and documentation
• Shows immediate errors during annotation writing (IDE plugin)

---

Stage 2: Compile Time

The stage where Java APT (Annotation Processing Tool, JSR-269) operates.

Processing Order

1. Parse source files
       ↓
2. Discover @QfEntity declarations
       ↓
3. Execute each annotation handler
       ↓
4. Contract validation (Fail-Fast)
   - Annotation combination rule checks
   - Type compatibility checks
   - Required attribute presence checks
       ↓
   Validation failure → Compile error → Build halted
       ↓
5. Generate metadata JSON files
       ↓
6. Generate registry index files
       ↓
7. Generate result code constant classes

Generated Artifacts

META-INF/
  qframework/
    entities/
      app.product.json            ← entity metadata
    capabilities/
      app.product_management.json ← capability metadata
    index/
      entity-index.json           ← entity registry index
      capability-index.json       ← capability registry index

Metadata JSON Example

{
  "schemaVersion": "1.0",
  "appKey": "app",
  "name": "product",
  "i18n": { "defaultMessage": "Product", "texts": [{ "locale": "ko", "message": "상품" }] },
  "autoHistoryEnabled": true,
  "fields": [
    {
      "name": "name",
      "type": "STRING",
      "label": "Product Name",
      "validations": [
        { "type": "REQUIRED" }
      ],
      "display": {
        "list": { "sortable": true },
        "detail": true,
        "create": true,
        "update": true,
        "search": true
      }
    }
  ]
}

This file must not be modified manually. It is a deterministically generated copy derived from the SSOT (annotations).

---

Stage 3: Runtime

The stage where compiled metadata powers actual service delivery.

Initialization Flow

Application startup
      ↓
Load META-INF/qframework/index/*.json
      ↓
Build entity registry
      ↓
Build Capability / Privilege registry
      ↓
Discover and register SPI implementations
  - QfUserProvider
  - QfOrganizationProvider
  - QfRuntimeInitializationHook
      ↓
Auto-register API routes
  - /api/{appKey}/{entityName}/**
      ↓
Execute QfRuntimeInitializationHook.onAfterInitialize()
      ↓
Service ready

Request Processing Pipeline

HTTP request received
      ↓
[1] Routing
    Identify entity name + action
      ↓
[2] Authentication / Authorization
    QfUserProvider.getCurrentUser()
    Privilege check
      ↓
[3] Input validation
    Apply metadata-based validation rules
    (@QfCreateAttribute requiredOn, @QfValidationRule, etc.)
      ↓
[4] Before hooks
    @QfOn(event = BEFORE_CREATE), etc.
      ↓
[5] Organization scope applied
    Filter / auto-set based on organization policy
      ↓
[6] Data processing
    Save: @QfCrypto encryption
    Read: @QfCrypto decryption
    Auto-record: @QfCreatedBy, @QfCreatedAt, etc.
      ↓
[7] After hooks
    @QfOn(event = AFTER_CREATE), etc.
      ↓
[8] Response returned
    Standard QfApiResponse format

Standard Response Format

{
  "success": true,
  "code": "SUCCESS",
  "data": { ... },
  "pagination": {
    "page": 1,
    "size": 20,
    "totalElements": 150,
    "totalPages": 8
  }
}

---

3-Stage Summary

Stage	Q-Framework Role	Developer Role
Authoring	Provide annotation definitions	Declare domain
Compile Time	Validate contracts + generate metadata	(none)
Runtime	Automatic processing from metadata	Implement SPI (when needed)

---

Next Steps

• Annotation Reference — Complete annotation list
• SPI Extensions — Runtime extension points