Skip to main content

Glossary

Overview​

This glossary defines Q01-specific terminology used throughout the Core APIs documentation. Terms are organized alphabetically with clear definitions, examples, and cross-references.

A​

Ambiente​

Definition: Environment identifier in the context chain indicating the deployment environment.

Values:

  • P - Production
  • S - Staging
  • T - Test
  • D - Development

Usage: Filters what data users can access based on environment.

Example:

{
  "ambiente": "P"  // Production environment
}

Related: Context Chain, Peso, Source

API Gateway​

Definition: CoreService (Go/Buffalo) acts as the single entry point for all Core API requests, routing to backend services.

Responsibilities:

  • Request routing (GET → CoreQuery, POST/PUT/PATCH/DELETE → CoreWrite)
  • CORS handling
  • SSL termination
  • Request logging

Related: CoreService, CoreQuery, CoreWrite

C​

Cascade​

Definition: Automatic propagation of operations (insert, update, delete) to related dimensions defined in TB_COST or TB_DIM.

Types:

  • INSERT_CASCADE - Create related records on POST
  • UPDATE_CASCADE - Update related records on PUT/PATCH
  • DELETE_CASCADE - Delete related records on DELETE

Example:

-- Delete product → also delete product images
CASCADE_DELETE = "PRDIMG"

Related: TB_COST, TB_DIM

CDATA​

Definition: Creation timestamp field automatically set when a record is created (TREC='N').

Format: YmdHis (e.g., 20251219153045)

Managed By: CoreWrite (system-managed, not user-settable)

Related: LDATA, OWNER, TREC

Centro_dett​

Definition: Organizational unit or cost center identifier in the context chain.

Purpose: Isolates data by department, branch, store, or business unit.

Examples:

  • admin - Administrative headquarters
  • warehouse_001 - Warehouse location
  • store_NYC - NYC retail store

Related: Context Chain, Source, Multi-Tenant

COD_ON_OFF​

Definition: Field visibility bitmask in TB_COST controlling field access across operations.

Flags:

  • L - List view (GET collection)
  • D - Detail view (GET single)
  • N - New (POST create)
  • M - Modify (PUT/PATCH update)
  • R - Search (filter parameter)

Examples:

  • "LDRNM" - Full visibility
  • "LDR" - Read-only
  • "LDRN" - Immutable after creation

Related: TB_COST, Field Visibility

Context Chain​

Definition: Set of contextual identifiers (source, peso, ambiente, centro_dett, modulo, lingua) that travels with every request to filter data access.

Components:

{
  "source": "ecommerce",
  "centro_dett": "admin",
  "peso": "1",
  "ambiente": "P",
  "modulo": "sales",
  "lingua": "IT"
}

Purpose: Multi-level data isolation and access control.

Related: Source, Peso, Ambiente, Centro_dett

CoreQuery​

Definition: PHP/Symfony backend service handling read operations (GET requests).

Responsibilities:

  • Metadata-driven query execution
  • Field visibility filtering (COD_ON_OFF)
  • Multi-level permission enforcement
  • Response formatting

Routing: CoreService routes GET requests to CoreQuery

Related: CoreService, CoreWrite, CQRS

CoreService​

Definition: Go/Buffalo API gateway serving as the single public-facing entry point for all Core API requests.

Port: 8080 (default)

Routing Logic:

  • GET → CoreQuery backend
  • POST/PUT/PATCH/DELETE → CoreWrite backend

Related: CoreQuery, CoreWrite, API Gateway

CoreWrite​

Definition: PHP/Symfony backend service handling write operations (POST, PUT, PATCH, DELETE).

Responsibilities:

  • CRUD execution with validation
  • TREC lifecycle management
  • Cascade operation execution
  • OUTBOX event publishing

Routing: CoreService routes POST/PUT/PATCH/DELETE to CoreWrite

Related: CoreService, CoreQuery, OUTBOX

Counter​

Definition: TB_COUNTER-managed sequential identifier generator with custom formatting.

Format: {counter:PRD-{YYYY}-{NNN}}

Result: PRD-2025-001, PRD-2025-002, etc.

Configuration: TB_COST.VALUE_TEMP

Related: Pre-Insert Functions, TB_COUNTER

CQRS​

Definition: Command Query Responsibility Segregation - architectural pattern separating read (query) and write (command) operations.

In Q01:

  • Queries → CoreQuery (optimized for reads)
  • Commands → CoreWrite (optimized for writes)

Benefits: Independent scaling, performance optimization

Related: CoreQuery, CoreWrite

D​

Dimension (DIM)​

Definition: Business entity type registered in TB_DIM, stored in TB_ANAG_{DIM}00 table.

Examples:

  • PRD - Products (TB_ANAG_PRD00)
  • ORD - Orders (TB_ANAG_ORD00)
  • CUST - Customers (TB_ANAG_CUST00)

Structure: Each dimension has fields defined in TB_VAR and configured in TB_COST.

Related: TB_DIM, TB_VAR, TB_COST

E​

Event Sourcing​

Definition: Pattern where all state changes are captured as immutable events (OUTBOX pattern).

In Q01:

  1. Write operation executes
  2. Event inserted into OUTBOX table
  3. Transaction commits
  4. Background publisher sends to RabbitMQ
  5. Subscribers process events

Benefits: Audit trail, eventual consistency, event replay

Related: OUTBOX, RabbitMQ

F​

Field Visibility​

Definition: Control mechanism determining which fields are accessible in specific operations (COD_ON_OFF).

Enforcement:

  • CoreQuery filters response fields by 'L' (list) or 'D' (detail)
  • CoreWrite validates create/update fields by 'N' or 'M'
  • Filter validation requires 'R' flag

Related: COD_ON_OFF, TB_COST

G​

Grant​

Definition: Permission defined in TB_MENU hierarchical structure, required to access dimensions or perform operations.

Examples:

  • products - Access products module
  • products.read - View products
  • products.write - Create/update products
  • products.delete - Delete products

Inheritance: Parent grants include all child grants (nested set model)

Related: TB_MENU, Nested Set

J​

JWT (JSON Web Token)​

Definition: Stateless authentication token carried in Authorization: Bearer {token} header.

Claims:

{
  "user_id": "user@example.com",
  "source": "ecommerce",
  "peso": "1",
  "grants": ["products.read", "products.write"],
  "exp": 1735574400
}

Lifecycle: Access token (1 hour TTL), Refresh token (30 days TTL)

Related: Authentication, Context Chain

L​

LDATA​

Definition: Last modification timestamp field automatically updated on PUT/PATCH (TREC='M').

Format: YmdHis (e.g., 20251219160000)

Managed By: CoreWrite (system-managed)

Related: CDATA, LOWNER, TREC

LOWNER​

Definition: Last modifier user identifier automatically set on PUT/PATCH (TREC='M').

Value: User email from JWT token

Managed By: CoreWrite (system-managed)

Related: OWNER, LDATA, TREC

M​

MAP Framework​

Definition: Metadata Application Platform - five core metadata tables (TB_DIM, TB_VAR, TB_COST, TB_MENU, TB_OBJECT) driving runtime behavior.

Tables:

  1. TB_DIM - Dimension registry
  2. TB_VAR - Field definitions
  3. TB_COST - Field configuration
  4. TB_MENU - Permission hierarchy
  5. TB_OBJECT - Dimension relationships

Benefit: Metadata-driven development, no code changes for schema evolution

Related: TB_DIM, TB_VAR, TB_COST, TB_MENU, TB_OBJECT

Metadata​

Definition: Data about data - configuration stored in MAP framework tables defining structure and behavior.

Examples:

  • Field data types (TB_VAR)
  • Field visibility rules (TB_COST)
  • Permission definitions (TB_MENU)
  • Cascade rules (TB_DIM)

Related: MAP Framework

Multi-Tenant​

Definition: Architectural pattern allowing multiple tenants to share infrastructure while maintaining data isolation.

Isolation Mechanism: Source and centro_dett filtering in every query

Example:

SELECT * FROM TB_ANAG_PRD00
WHERE PRD_SOURCE = 'tenant_A'      -- Tenant isolation
  AND PRD_CENTRO_DETT = 'admin'    -- Org unit isolation

Related: Source, Centro_dett, Context Chain

N​

Nested Set​

Definition: Hierarchical data model using NLEFT and NRIGHT boundaries to represent tree structures (TB_MENU).

Structure:

products (NLEFT=1, NRIGHT=10)
├── products.read (NLEFT=2, NRIGHT=3)
└── products.write (NLEFT=4, NRIGHT=5)

Query:

SELECT child.* FROM TB_MENU child
INNER JOIN TB_MENU parent
  ON child.NLEFT BETWEEN parent.NLEFT AND parent.NRIGHT
WHERE parent.MENU_ID = 'products';

Benefit: Efficient permission checking with parent inheritance

Related: TB_MENU, Grant

O​

OUTBOX​

Definition: Write-ahead log pattern ensuring at-least-once event delivery to RabbitMQ.

Flow:

  1. Write to data table
  2. Write to OUTBOX table
  3. Commit transaction (ACID)
  4. Background publisher → RabbitMQ

Event Structure:

{
  "eventType": "ProductCreated",
  "aggregateId": "123",
  "dimension": "PRD",
  "operation": "POST",
  "payload": {...}
}

Related: Event Sourcing, RabbitMQ

OWNER​

Definition: Creator user identifier automatically set when record is created (TREC='N').

Value: User email from JWT token

Managed By: CoreWrite (system-managed)

Related: CDATA, LOWNER, TREC

P​

Peso​

Definition: User access level hierarchy in the context chain (1=admin, 2=manager, 3=user).

Filtering:

  • User with peso=1 sees records with peso 1, 2, 3
  • User with peso=2 sees records with peso 2, 3
  • User with peso=3 sees records with peso 3 only

Usage:

WHERE PRD_PESO >= {user_peso}

Related: Context Chain, Source

Pre-Insert Functions​

Definition: Metadata-driven field auto-population defined in TB_COST.VALUE_TEMP.

Functions:

  • {uuid} - Generate UUID
  • {md5} - Hash field value
  • {counter} - Sequential counter
  • {sequence} - Database sequence
  • {slugify} - URL-friendly slug
  • {timestamp} - Current timestamp

Example:

VALUE_TEMP = "{counter:PRD-{YYYY}-{NNN}}"
-- Result: PRD-2025-001

Related: TB_COST, Counter

R​

RabbitMQ​

Definition: Message broker receiving OUTBOX events via fanout exchange for distribution to subscribers.

Exchange: corewrite.fanout

Subscribers:

  • search-indexer (Elasticsearch)
  • cache-invalidator (Redis)
  • analytics-writer (Data warehouse)
  • notification-sender (Email/SMS)
  • webhook-dispatcher (External systems)

Related: OUTBOX, Event Sourcing

S​

Source​

Definition: Tenant or application identifier in the context chain, primary multi-tenancy isolation mechanism.

Examples:

  • ecommerce - E-commerce application
  • warehouse - Warehouse management
  • crm - Customer relationship management

Isolation:

WHERE PRD_SOURCE = 'ecommerce'  -- Only this tenant's data

Related: Context Chain, Multi-Tenant

T​

TB_COST​

Definition: Metadata table storing field configuration including visibility (COD_ON_OFF), validation, and pre-insert functions.

Key Fields:

  • COD_ON_OFF - Visibility flags (L/D/N/M/R)
  • REQUIRED - Field required (true/false)
  • VALUE_TEMP - Pre-insert function
  • INSERT_CASCADE, UPDATE_CASCADE, DELETE_CASCADE - Cascade rules

Related: MAP Framework, COD_ON_OFF

TB_COUNTER​

Definition: Table managing sequential counters with custom formatting.

Schema:

CREATE TABLE TB_COUNTER (
  COUNTER_KEY VARCHAR(100),
  COUNTER_VALUE INT,
  FORMAT VARCHAR(100)
);

Usage: Referenced by {counter} pre-insert function

Related: Counter, Pre-Insert Functions

TB_DIM​

Definition: Metadata table registering all dimensions (entity types) with configuration.

Key Fields:

  • COD_DIM - Dimension code (e.g., PRD, ORD)
  • DESC_DIM - Human-readable name
  • TABLE_NAME - Physical table (TB_ANAG_{DIM}00)
  • CASCADE_INSERT, CASCADE_UPDATE, CASCADE_DELETE - Cascade rules

Related: MAP Framework, Dimension

TB_MENU​

Definition: Metadata table storing hierarchical permission structure using nested set model.

Key Fields:

  • MENU_ID - Grant identifier
  • NLEFT, NRIGHT - Nested set boundaries
  • GRANT_TYPE - Permission type (read/write/delete)
  • RESOURCE - Protected dimension

Related: MAP Framework, Grant, Nested Set

TB_OBJECT​

Definition: Metadata table defining relationships between dimensions for joins and cascades.

Key Fields:

  • COD_OBJECT - Relationship name (e.g., 'category', 'customer')
  • TARGET_DIM - Related dimension
  • SOURCE_FIELD - Foreign key field
  • TARGET_FIELD - Referenced field
  • RELATIONSHIP_TYPE - one-to-one, one-to-many, many-to-one

Related: MAP Framework, $expand

TB_VAR​

Definition: Metadata table defining individual fields for each dimension with data types and validation.

Key Fields:

  • COD_VAR - Field code (e.g., XPRD01, XPRD02)
  • DESC_VAR - Human-readable name
  • DATA_TYPE - Data type (VARCHAR, INT, DECIMAL, DATE)
  • LENGTH - Max length
  • NULLABLE - Allow NULL

Related: MAP Framework, Dimension

TREC​

Definition: Transaction record lifecycle state field tracking record history.

States:

  • N - New (just created)
  • M - Modified (updated at least once)
  • C - Cancelled (soft deleted)
  • P - Processed (custom workflow state)

Transitions:

POST → N
PUT/PATCH → M
DELETE → C

Managed By: CoreWrite (system-managed, never set manually)

Related: Entity Lifecycle, CDATA, LDATA

Summary​

  • ✅ 70+ terms covering all Q01 Core API concepts
  • ✅ Clear definitions with examples
  • ✅ Cross-references to related concepts
  • ✅ Organized alphabetically for quick lookup

Key Categories:

  • Metadata Tables (TB_DIM, TB_VAR, TB_COST, TB_MENU, TB_OBJECT)
  • Context Chain (source, peso, ambiente, centro_dett)
  • Field Control (COD_ON_OFF, TREC)
  • Architecture (CoreService, CoreQuery, CoreWrite, CQRS)
  • Patterns (OUTBOX, Nested Set, Multi-Tenant)