Architecture MetaType System - osama1998H/Moca GitHub Wiki

MetaType System

Schema compiler, registry, 3-tier cache, DDL generator, and migrator.

The MetaType is Moca's core primitive. A single JSON/YAML definition describes a document type and drives database schema, validation, API endpoints, search indexing, and React UI rendering.

Overview

A MetaType definition includes:

  • Fields -- 35 field types (29 storage + 6 layout-only)
  • Naming -- 6 naming strategies (AutoIncrement, Pattern, ByField, ByHash, UUID, Custom)
  • Permissions -- Role-based CRUD permissions per DocType
  • Lifecycle -- 16 document events with hook attachment points
  • Layout -- Section, Column, and Tab breaks for UI rendering

Schema Compiler

The compiler transforms a JSON/YAML MetaType definition into a validated runtime object:

  1. Parse JSON/YAML into raw MetaType struct
  2. Validate required fields, field type compatibility, naming strategy
  3. Resolve Link fields to target MetaTypes
  4. Generate DDL (CREATE TABLE / ALTER TABLE) statements
  5. Register in the MetaType Registry

3-Tier Cache

MetaType lookups use a layered cache for performance:

  1. In-memory (Go map) -- fastest, per-process
  2. Redis (DB 0) -- shared across server instances
  3. PostgreSQL -- authoritative source of truth

Cache invalidation propagates via Redis pub/sub when a MetaType is modified.

DDL Generator

Each field type maps to a PostgreSQL column type. Every table includes:

  • name -- primary key (TEXT or BIGINT depending on naming strategy)
  • owner, creation, modified, modified_by -- audit columns
  • docstatus -- document workflow state (0=Draft, 1=Submitted, 2=Cancelled)
  • workflow_state -- current workflow state name for DocTypes with workflows
  • _extra -- JSONB column for dynamic/custom fields

Migrator

When a MetaType changes, the migrator diffs the old and new definitions and generates ALTER TABLE statements (add columns, change types, add/drop indexes).

Related