Architecture Overview

Design Philosophy

Q-Framework's architecture is grounded in three core principles.

1. Declaration Drives Implementation

Developers declare what they want, and the framework decides how to handle it.

Declaration (What)   →       Implementation (How)
@QfCrypto            →       AES-256 encryption applied automatically
@QfOrganizationScope →       Organization filter query generated automatically
@QfCreateAttribute(requiredOn = @QfRequiredOn(always = true))  →  Server/client validation applied automatically

2. Compile Time Takes Priority Over Runtime

A build failure is far preferable to a runtime failure.

Invalid declaration
    ↓
Compile error → Build rejected → Deployment blocked
                                        ↓
                                  Runtime failure prevented

3. The Contract is Enforced for Both Humans and AI

Even if AI generates code, it must pass through the same quality gates.

---

Human-AI-System Contract Model

┌──────────────────────────────────────────────────────────┐
│                    Human (Developer)                      │
│  "Add @QfCrypto to the email field"                      │
└─────────────────────┬────────────────────────────────────┘
                      │ intent declared
                      ▼
┌──────────────────────────────────────────────────────────┐
│                    AI (Assistant)                         │
│  @QfCrypto                                               │
│  @QfDisplayLabel(text = "Email")                         │
│  private String email;                                   │
└─────────────────────┬────────────────────────────────────┘
                      │ code generated
                      ▼
┌──────────────────────────────────────────────────────────┐
│                  System (Q-Framework)                     │
│  Compile time: @QfCrypto rule validation passed          │
│  Runtime: encryption automatically enforced              │
└──────────────────────────────────────────────────────────┘

Human declares business intent. AI implements the declaration as code. System enforces the contract.

The same contract applies to all three actors equally.

---

Comparison with Ontology

Q-Framework's approach shares similarities with ontology systems.

Aspect	Ontology	Q-Framework
Knowledge representation	OWL, RDF	Annotations
Reasoning	Runtime reasoning engine	Compile-time processing
Enforcement	Inference-based	Compile rejection
Target domain	Knowledge graphs	Software domain
Language dependency	None	Java (current), language-agnostic goal
Learning curve	High	Low (annotation declarations)

Q-Framework's differentiator: A lightweight metadata system optimized for software development, focused on compile-time enforcement and runtime automation.

---

Language Independence

The current Java implementation is the first validation of the Q-Framework idea.

Language-agnostic core pattern
        │
        ├── Java implementation (current)
        │       Annotations + APT (JSR-269)
        │
        ├── TypeScript implementation (planned)
        │       Decorators + tsc plugin
        │
        └── Python implementation (planned)
                Decorators + mypy plugin

Regardless of implementation language, the following pattern is the core:

1. Declarative metadata — Express semantics and contracts in code
2. Compile-time validation — Block invalid declarations at build time
3. Runtime automation — Automatically handle behavior derived from declarations

---

Next Steps

• Module Structure — Detailed module dependencies
• Execution Lifecycle — Detailed 3-stage processing flow