Skip to main content

Core Concepts ⭐ START HERE

Why This Section Matters​

This is the most important section of the documentation. Everything else builds on these concepts.

If you're new to Q01, start here and read through all 13 concepts. Skipping this section will lead to:

  • ❌ Confusion about field visibility and permissions
  • ❌ Validation errors you don't understand
  • ❌ Security issues from bypassing metadata
  • ❌ Inconsistent data from ignoring cascades

Understanding these concepts will enable you to:

  • ✅ Design dimensions (entity types) correctly
  • ✅ Configure field visibility and permissions properly
  • ✅ Use context chain effectively (source, center_dett, peso, ambiente)
  • ✅ Avoid common anti-patterns
  • ✅ Troubleshoot issues quickly

The 13 Essential Concepts​

1. Dimensions​

What it is: A dimension is a business entity type (like products, customers, orders) registered in metadata.

Why it matters: Dimensions are the primary abstraction - once registered, Core APIs automatically provide full CRUD operations.

Key learning: Understand TB_DIM, TB_ANAG_{DIM}00 naming, and dimension types.

2. MAP Framework​

What it is: Metadata Application Platform - interconnected metadata tables (TB_DIM, TB_COST, TB_TYPE_FIELDS, TB_MENU, TB_OBJECT, TB_COUNTER) defining all behavior.

Why it matters: MAP is the heart of Q01's metadata-driven approach. Everything is configured through metadata, not code.

Key learning: Understand the role of each metadata table and how they work together.

3. Context Chain​

What it is: Every request carries context (source, modulo, center_dett, peso, ambiente, lingua) that determines visibility and permissions.

Why it matters: Context controls what fields you see, what data is accessible, and what operations are permitted.

Key learning: Know which context parameters to use for each operation.

4. Field Visibility - COD_ON_OFF​

What it is: A compact bitmask (L/D/N/M/R) controlling field visibility across UI contexts.

Why it matters: One field can specify "show in list, detail, and search but not in create form" with a single string.

Key learning: Master COD_ON_OFF flags and how center_dett filters fields.

5. Nested Set Model​

What it is: TB_MENU uses nested set model (NLEFT, NRIGHT, NLEVEL) for hierarchical security areas.

Why it matters: Menu hierarchy defines permission boundaries - your position in the tree determines access.

Key learning: Understand how security areas work and how to query hierarchies efficiently.

6. Multi-Level Permissions​

What it is: Permissions enforced at multiple simultaneous layers: peso, source, ambiente, COD_ON_OFF, grants.

Why it matters: Defense in depth - no single permission failure exposes unauthorized data.

Key learning: Understand all five permission layers and how they interact.

7. Entity Lifecycle - TREC​

What it is: The TREC field tracks entity state (N=new, M=modified, C=cancelled, P=provvisorio).

Why it matters: Supports soft deletes (non-destructive data management) and audit trails.

Key learning: Know when to use soft delete vs force delete.

8. Cascade Operations​

What it is: Metadata-driven automatic propagation of create/update/delete across related dimensions.

Why it matters: Maintains referential integrity without hardcoded logic - add relationships in metadata, Core APIs handle them.

Key learning: Configure INSERT_CASCADE, UPDATE_CASCADE, DELETE_CASCADE correctly.

9. Outbox Pattern​

What it is: Write-ahead log pattern for eventual consistency - all changes stored in TB_ANAG_OUTBOX00 before publishing to RabbitMQ.

Why it matters: Guarantees at-least-once delivery even if message broker fails. Critical for distributed systems.

Key learning: Understand the dual-write pattern and how consistency is guaranteed.

10. Pre-Insert Functions​

What it is: Special functions (uuid, md5, sequence, counter, slugify, current_user) that auto-populate fields during creation.

Why it matters: Eliminates boilerplate - fields auto-populated based on metadata.

Key learning: Know which functions are available and when to use each.

11. Counter Management​

What it is: System for generating unique, formatted sequential identifiers (e.g., "INV-2025-00123") based on TB_COUNTER.

Why it matters: Business-friendly IDs with formatting and business rules, concurrent-safe.

Key learning: Configure counters properly with format templates and SQL queries.

12. Database Abstraction​

What it is: PDO-based abstraction supporting MySQL and Oracle with three connection types (meta, data, auth).

Why it matters: Applications don't need to know which database engine is used - Core APIs handle differences.

Key learning: Understand connection separation and database-specific handling.

13. Source Parameter​

What it is: Required business logic identifier (format: {microservice}-{number}) linking TB_MENU.COD_MENU to dimensions.

Why it matters: Binds every API call to a security area, enabling multi-level permission validation and tenant isolation.

Key learning: Understand source format, how it's generated from TB_MENU, and why it's required in all calls.

How to Use This Section​

For Beginners​

Read concepts in order (1-13). Each builds on previous concepts.

Estimated time: 2-3 hours for all 13 concepts.

For Experienced Developers​

Skim the overview, then deep-dive into concepts you're less familiar with.

Focus on:

  • Context Chain (#3) - controls everything
  • COD_ON_OFF (#4) - most common source of confusion
  • Permissions (#6) - defense in depth
  • Outbox Pattern (#9) - consistency guarantees

For Troubleshooting​

Having issues? Check these concepts first:

Permission denied? → Multi-Level Permissions

Fields not showing? → Field Visibility - COD_ON_OFF

Validation errors? → Context Chain (check center_dett)

Data not isolated? → Context Chain (check ambiente)

Cascades not working? → Cascade Operations

Events not publishing? → Outbox Pattern

Concept Relationships​

Understanding how concepts relate helps build mental models:

┌─────────────┐
│  Dimension  │  ← Foundation: everything is a dimension
└──────┬──────┘
       │
       v
┌─────────────────────┐
│   MAP Framework     │  ← Metadata defines behavior
│ (TB_DIM, TB_COST,   │
│  TB_VAR, TB_MENU)   │
└──────┬──────────────┘
       │
       ├──────────────────────────────┐
       │                              │
       v                              v
┌─────────────────┐           ┌─────────────────┐
│  Context Chain  │           │  COD_ON_OFF     │
│ (source, peso,  │──filters──│ (field          │
│  center_dett)   │           │  visibility)    │
└─────────────────┘           └─────────────────┘
       │
       v
┌─────────────────────────────────────┐
│     Multi-Level Permissions         │
│ (peso, source, ambiente, COD_ON_OFF)│
└─────────────────────────────────────┘
       │
       v
┌─────────────────────────────────────┐
│  CRUD Operations                    │
│ (create, read, update, delete)      │
└──────┬──────────────────────────────┘
       │
       ├──────────┬──────────┬──────────┐
       v          v          v          v
 ┌─────────┐ ┌────────┐ ┌────────┐ ┌────────┐
 │  TREC   │ │Cascades│ │Outbox  │ │Counters│
 │Lifecycle│ │        │ │Pattern │ │        │
 └─────────┘ └────────┘ └────────┘ └────────┘

Practical Application​

After understanding these concepts, you'll be able to:

Design a New Dimension​

1. Define dimension in TB_DIM (Concept #1)
2. Define fields in TB_COST with COD_ON_OFF (Concept #4)
3. Configure permissions in TB_MENU (Concept #5, #6)
4. Add pre-insert functions (Concept #10)
5. Configure counters if needed (Concept #11)
6. Define cascades for relationships (Concept #8)
→ Core APIs now handle full CRUD automatically!

Query Data Correctly​

1. Choose appropriate source (security area - Concept #3, #6)
2. Choose appropriate center_dett (field visibility - Concept #4)
3. Ensure JWT has correct peso (permission weight - Concept #6)
4. Ensure JWT has correct ambiente (tenant isolation - Concept #3)
→ Core APIs return only fields you're permitted to see!

Create Data Correctly​

1. Include source in request body (Concept #3)
2. Include only fields with COD_ON_OFF='N' (Concept #4)
3. Ensure grant level 4 for source (Concept #6)
4. Let pre-insert functions auto-populate fields (Concept #10)
5. Trust outbox pattern to publish events (Concept #9)
→ Core APIs validate, create, and publish automatically!

Common Misconceptions​

❌ "I can skip metadata and hardcode field names"​

Reality: Field names are dynamic based on metadata. Fields can be added/removed/renamed via TB_COST updates.

❌ "center_dett is just a label"​

Reality: center_dett actively filters which fields are returned based on COD_ON_OFF matching.

❌ "peso is just a number"​

Reality: peso is compared against TB_COST.COD_UTENTE to enforce field-level access control.

❌ "source is optional"​

Reality: source is required for permission validation via TB_MENU and grant checking.

❌ "TREC is just a status field"​

Reality: TREC drives soft delete behavior and audit trails throughout the system.

❌ "Outbox pattern is just logging"​

Reality: Outbox guarantees at-least-once delivery with ACID semantics - critical for consistency.

Next Steps​

Ready to dive in?

  1. Start with Dimensions - the foundation
  2. Progress through all 13 concepts in order
  3. Reference back to this overview as you go
  4. Apply concepts in Quick Start examples

Time investment: 2-3 hours to read all concepts thoroughly.

Payoff: Deep understanding enabling you to use Q01 Core APIs correctly and avoid 90% of common mistakes.

Let's begin! →