Introduction to Q-Framework

Q-Framework is a domain metadata-driven development framework. Declare your domain with annotations and get CRUD APIs, UI, validation, access control, and organization-based data isolation — all automatically.

Human declares, AI implements, System enforces — this is the core philosophy of Q-Framework.

Problems Q-Framework Solves

Traditional enterprise development repeats the same patterns endlessly.

CRUD Boilerplate Explosion

For a single entity, developers must write:

• Entity class
• Repository interface
• Service class (CRUD methods × 4–6)
• Controller class (API endpoints × 6+)
• Multiple Request/Response DTOs
• Validation logic (Service layer + Bean Validation)
• Frontend list / detail / create / update screens × 4
• API integration code

Less than 10% of this code carries real business value.

Inconsistent Validation

Different validation approaches across teams, inconsistent error response formats across APIs, and the inefficiency of duplicating validation logic between server and client.

Duplicated Access Control

Permission logic implemented separately for screens, APIs, and data filtering is prone to gaps when requirements change.

Benefits for Developers

Traditional Approach	Q-Framework
Hundreds of lines of boilerplate per entity	A single annotation declaration
Errors discovered at runtime	Fail-Fast at compile time
Different patterns per team	Consistency enforced by the framework
Manually managed permission rules	Declaration-based automatic enforcement
No quality guarantee on AI-generated code	Same contract enforced for all code

Just 1 Entity — What Gets Automated

Declaring a single entity triggers all of the following automatically.

@QfEntity(
    appKey = "app",
    name = @QfI18n(
        defaultMessage = "User",
        texts = { @QfI18nText(locale = "ko", message = "사용자") }
    ),
    organizationPolicy = @QfOrganizationPolicy(enabled = true, attribute = "organizationId"),
    capabilityKey = "user-management"
)
public class UserEntity {

    private String organizationId;   // org filter target (declared in organizationPolicy.attribute)

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

    @QfDetailAttribute
    @QfCreateAttribute
    @QfCrypto
    @QfControlType(QfControlType.Type.email)
    @QfDisplayLabel(text = "Email")
    private String email;
}

Backend — automatically handled:

• GET /api/app/users — list with pagination and search
• GET /api/app/users/{id} — detail
• POST /api/app/users — create
• PUT /api/app/users/{id} — update
• DELETE /api/app/users/{id} — delete
• GET /api/app/users/history — change history
• GET /api/app/users/excel/download — Excel export
• POST /api/app/users/excel/upload — Excel import
• Compile-time validation rule enforcement
• Automatic organization-scoped data filtering
• Automatic encryption/decryption for the email field

Frontend — automatically handled:

• List screen (search, sort, pagination)
• Detail screen
• Create/update form (with validation)
• Excel upload/download UI

Collaboration with AI

Q-Framework becomes even more powerful in the age of AI.

Human  →  "Add an email field to the user entity, needs encryption"
  ↓
AI     →  @QfDetailAttribute @QfCrypto @QfControlType(Type.email) private String email;
  ↓
System →  Compile time: @QfCrypto + @QfSearch conflict check, type validation
          Runtime: encryption automatically applied

Q-Framework's role:

• Provides annotation contracts to express human intent precisely
• Forces AI-generated code through the same quality gates
• Blocks annotation violations and policy conflicts at compile time

Even if AI generates incorrect code, Q-Framework refuses to compile it.

Java Implementation and Language Independence

Q-Framework is currently validating its first implementation in Java.

The core pattern is not tied to any specific language:

Declarative metadata → Compile-time validation → Runtime automation

Language	Declaration Mechanism	Compile-time Tool
Java	Annotations (APT/JSR-269)	Annotation Processor
TypeScript	Decorators	tsc plugin
Kotlin	Annotations (KSP)	KSP Processor
Python	Decorators	mypy plugin
Rust	Macros	Macro expansion

Only the design principles need to be ported — not any specific language API.

Next Steps

• Quick Start — Run your first entity in 5 minutes
• Core Concepts — Understand SSOT, metadata contracts, and lifecycle
• Architecture Overview — Deep dive into the internal structure