🏛️ @damarkuncoro/meta-architecture

The Constitutional Layer for Digital Systems.

Contracts are law. Everything must obey.

Enterprise-grade Contract-Driven Meta Design (CDMD) kernel. Not a UI framework. Not a config manager. This is the Constitutional Layer for your software ecosystem.

📋 Table of Contents

• Overview
• Key Features
• Architecture
• Quick Start
• Runtime Transaction Validation
• Ecosystem
• Security
• Contributing
• License

🎯 Overview

🏛️ What is this?

This is a Contract Governance Engine.

It sits above your frameworks (React, Vue, Node.js) and below your business requirements. It acts as the single source of truth for what is "legal" in your system.

• For GovTech: It acts as the digital regulation engine.
• For AI Platforms: It acts as the safety guardrail (AI generates content, CDMD validates it).
• For Enterprise: It acts as the architectural compliance layer.

⚖️ Contract as Law (Non-Negotiable)

In this architecture, a Contract is not a suggestion, a configuration file, or a hint. It is the law.

• Contract != Config: Configuration can be changed at runtime; Contracts are immutable laws that govern the system.
• No Bypass: The Runtime Engine, UI Renderers, and AI Agents MUST NOT bypass contract constraints under any circumstances.
• Universal Subjection: User input, API responses, and AI-generated content are all subject to the contract. If they violate the contract, they are rejected immediately.

@damarkuncoro/meta-architecture is an enterprise-grade TypeScript package that implements Clean Architecture principles for contract management. It provides a robust foundation for building scalable, maintainable, and secure contract-based systems with domain-driven design.

🧠 Why Not X?

Understanding what @damarkuncoro/meta-architecture is NOT helps clarify what it IS.

Why Not JSON Schema?

| Aspect | JSON Schema | Meta-Architecture | |--------|-------------|-------------------| | Purpose | Validates data shape | Governs behavior & legality | | Scope | Local (data structure) | Global & systemic (entire system) | | Enforcement | Optional/Manual | Mandatory/Automatic | | Lifecycle | No lifecycle awareness | Contract lifecycle (draft → active → deprecated → archived) | | Governance | None | Constitutional layer | | Audit Trail | None | Complete traceability |

Key Difference:

• JSON Schema validates that data has the right shape (e.g., "email is a string")
• Meta-Architecture governs what is legal in the system (e.g., "email must be validated, encrypted, and logged")

Why Not Policy Engines (OPA, Cedar)?

| Aspect | Policy Engines | Meta-Architecture | |--------|---------------|-------------------| | Purpose | Decide yes/no for specific requests | Define what is legal to exist | | Scope | Request-level decisions | System-level governance | | Focus | Authorization & access control | Constitutional constraints | | Definition | Policies (rules) | Contracts (laws) | | Enforcement | Per-request | System-wide | | Lifecycle | Policy versioning | Contract lifecycle with formal approval |

Key Difference:

• Policy Engines decide whether a specific request is allowed (e.g., "Can user X access resource Y?")
• Meta-Architecture defines what is legal to exist in the system (e.g., "What properties MUST a user have?")

Why Not Clean Architecture Only?

| Aspect | Clean Architecture | Meta-Architecture | |--------|-------------------|-------------------| | Purpose | Define structure and dependencies | Define constitutional constraints | | Scope | Code organization | System governance | | Focus | Layer separation (Domain, Application, Infrastructure) | Contract enforcement | | Validation | Compile-time (TypeScript) | Compile-time + Runtime | | Governance | None | Constitutional layer | | Compliance | Manual | Automated |

Key Difference:

• Clean Architecture defines how code should be organized (e.g., "Domain layer shouldn't depend on Infrastructure")
• Meta-Architecture defines what is legal in the system (e.g., "All user data must be encrypted")

Summary: The Constitutional Layer

| Approach | What It Does | What It Doesn't Do | |-----------|---------------|---------------------| | JSON Schema | Validates data shape | Governs behavior, enforces laws | | Policy Engines | Decides authorization | Defines what can exist | | Clean Architecture | Organizes code structure | Enforces constitutional constraints | | Meta-Architecture | Governs system behavior | Replaces all of the above |

Meta-Architecture IS:

• ✅ A Constitutional Layer that sits above all of these
• ✅ Defines what is legal in the system
• ✅ Enforces governance across all layers
• ✅ Provides audit trails for compliance
• ✅ Ensures AI safety through guardrails

🚀 Key Features

Core Architecture

• 🏛️ Clean Architecture with proper layer separation
• 🎯 Domain-Driven Design with entities, value objects, and aggregates
• 📦 SOLID Principles implemented throughout
• 🔄 Dependency Injection for testability and flexibility

Enterprise Features

• 📊 Contract Registry with centralized management and discovery
• ✅ Validation Pipeline with modular architecture (Security, Performance, Rules)
• 🧩 Plugin System for extensible validation (Fraud Detection, Balance Checks)
• 🛡️ Complex Validation support (Regex, Range, Enum, Custom Rules)
• 📜 Spec v1.1 Compliance ensuring strict adherence to the Formal Contract Specification
• 🚀 High-Performance Caching with LRU eviction and intelligent invalidation
• 🔒 Security Sandboxing with code execution safety and input sanitization
• 🌐 Browser/Edge Compatible (ESM & CJS Dual Build)

🧬 Contract-Driven Meta Architecture (CDMA)

This project fully implements the CDMA specification, ensuring contracts are the single source of truth for all system behavior.

• Formal Specification: Contracts are validated against a strict grammar.
• Runtime Validation: Validate runtime data securely against contracts.
• Safe Sandboxing: Custom validation logic is executed in a secure, isolated sandbox.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    PRESENTATION LAYER                       │
│  (React/Vue/Angular Components, CLI, HTTP Controllers)     │
└─────────────────────┬───────────────────────────────────────┘
                       │
┌─────────────────────▼───────────────────────────────────────┐
│                 APPLICATION LAYER                           │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ ContractRegistry     │ ValidationPipeline         │    │
│  │ CachedContractRegistry │ SecuritySandbox          │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────┬───────────────────────────────────────┘
                       │
┌─────────────────────▼───────────────────────────────────────┐
│                  DOMAIN LAYER                               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ ContractEntity     │ ContractName VO              │    │
│  │ ContractVariant    │ ContractCategory VO          │    │
│  │ ContractProp       │ ContractStatus VO            │    │
│  │ Domain Events      │ Domain Errors                │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────┬───────────────────────────────────────┘
                       │
┌─────────────────────▼───────────────────────────────────────┐
│               INFRASTRUCTURE LAYER                          │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ InMemoryContractRepository │ LruCache             │    │
│  │ InMemoryDomainEventPublisher │ SafeSandbox        │    │
│  │ ContractDefinitionValidator │ InputSanitizer     │    │
│  │ HealthChecker              │ SecurityPolicies    │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

🏃 Quick Start

Installation

Node.js (NPM/Yarn/PNPM):

npm install @damarkuncoro/meta-architecture
# or
yarn add @damarkuncoro/meta-architecture
# or
pnpm add @damarkuncoro/meta-architecture

Basic Usage

import {
  ContractEntity,
  ContractRegistry,
  InMemoryContractRepository,
  InMemoryDomainEventPublisher,
  ValidationPipeline,
  ContractCategory
} from '@damarkuncoro/meta-architecture';

// 1. Define a Contract (The Law)
const buttonContract = ContractEntity.create({
  name: 'Button Component',
  category: ContractCategory.COMPONENT,
  variants: [
    {
      name: 'variant',
      type: 'string',
      values: ['primary', 'secondary'],
      defaultValue: 'primary'
    }
  ],
  props: [
    {
      name: 'label',
      type: 'string',
      required: true
    }
  ]
});

// 2. Set up the Registry
const repository = new InMemoryContractRepository();
const eventPublisher = new InMemoryDomainEventPublisher();
const registry = ContractRegistry.getInstance(repository, eventPublisher);

// 3. Validate & Register
const validationPipeline = new ValidationPipeline();
const validationResult = await validationPipeline.validateContract(buttonContract, {
  existingContracts: [],
  environment: 'production',
  userPermissions: ['admin']
});

if (validationResult.isSuccess) {
  await registry.register(buttonContract);
  console.log('✅ Contract registered successfully!');
} else {
  console.error('❌ Validation failed:', validationResult.error.message);
}

Advanced Usage with Plugins & Monitoring

import {
  ValidationPipeline,
  ValidationPluginRegistry,
  ValidationLogger,
  ContractEntity,
  ContractCategory
} from '@damarkuncoro/meta-architecture';

// Custom validation plugin
const customPlugin = {
  metadata: {
    name: 'enterprise-security-plugin',
    version: '1.0.0',
    description: 'Enterprise security validation rules',
    author: 'Your Company',
    dependencies: {}
  },
  rules: [
    {
      name: 'enterprise-security-check',
      description: 'Check enterprise security compliance',
      category: 'security',
      severity: 'error',
      validate: async (contract, context) => {
        // Custom security validation logic
        if (contract.category.value === 'COMPONENT' && !contract.accessibility.supported) {
          return {
             valid: false,
             message: 'Enterprise components must have accessibility support',
             code: 'ENTERPRISE_SECURITY_VIOLATION'
          };
        }
        return null;
      }
    }
  ],
  initialize: async (config) => {
    console.log('Enterprise security plugin initialized');
  },
  destroy: async () => {
    console.log('Enterprise security plugin destroyed');
  },
  getHealth: async () => ({ status: 'healthy' })
};

// Monitoring hooks
const monitoringHooks = {
  onValidationStart: (context) => {
    console.log(`Starting validation: ${context.operation}`);
  },
  onValidationComplete: (context) => {
    console.log(`Validation completed in ${context.duration}ms`);
  },
  onPerformanceThresholdExceeded: (context) => {
    console.warn(`Performance threshold exceeded: ${context.metric} = ${context.value}`);
  }
};

// Set up enhanced pipeline
const logger = new ValidationLogger();
const pluginRegistry = new ValidationPluginRegistry();

const pipeline = new ValidationPipeline({
  logger,
  pluginRegistry,
  monitoringHooks
});

// Register plugin
await pipeline.registerPlugin(customPlugin, {
  enabled: true,
  priority: 10
});

🛡️ Runtime Transaction Validation

Beyond validating contract definitions, this package provides a robust engine for validating runtime transactions against those contracts.

Complex Property Validation

Define strict rules for your contract properties directly in the definition:

const transferContract = ContractEntity.create({
  name: 'Fund Transfer',
  category: ContractCategory.TRANSACTION,
  variants: [{ name: 'type', type: 'string', values: ['internal', 'external'] }],
  props: [
    {
      name: 'amount',
      type: 'number',
      required: true,
      validation: {
        min: 1000,
        max: 5000000,
        message: 'Amount must be between 1,000 and 5,000,000'
      }
    },
    {
      name: 'currency',
      type: 'string',
      required: true,
      validation: {
        enum: ['IDR', 'USD', 'SGD']
      }
    },
    {
      name: 'notes',
      type: 'string',
      required: false,
      validation: {
        pattern: '^[a-zA-Z0-9 ]+$', // Alphanumeric only
        message: 'Notes contains invalid characters'
      }
    }
  ]
});

Transaction Plugins

Inject external logic (e.g., Fraud Detection, Balance Checks) into the validation pipeline without modifying core code.

1. Create a Plugin

import { ITransactionPlugin, Result, TransactionContext } from '@damarkuncoro/meta-architecture';

export class FraudDetectionPlugin implements ITransactionPlugin {
  readonly name = 'fraud-detection';
  readonly version = '1.0.0';

  async validate(context: TransactionContext): Promise<Result<void, string>> {
    // Access runtime context (User IP, ID, etc.)
    if (context.userContext?.ip === '1.2.3.4') {
      return Result.failure('Suspicious IP Address detected');
    }
    return Result.success(undefined);
  }
}

2. Load Plugins Dynamically (Factory Pattern)

Use the PluginLoaderService to load plugins from configuration (JSON/Env):

import { 
  TransactionPluginFactory, 
  PluginLoaderService, 
  TransactionPluginRegistry,
  ValidateTransactionUseCase
} from '@damarkuncoro/meta-architecture';

// 1. Register Plugin Type (Auto-registration supported)
TransactionPluginFactory.registerPluginType('fraud-detection', FraudDetectionPlugin);

// 2. Load from Config
const registry = new TransactionPluginRegistry();
const loader = new PluginLoaderService(registry);

await loader.loadPlugins([
  { type: 'fraud-detection', config: { strictMode: true } },
  { type: 'external-balance-check' }
]);

// 3. Execute Validation
const useCase = new ValidateTransactionUseCase(contractRepository, registry);
const result = await useCase.execute({
  contractId: 'fund-transfer-01',
  payload: { amount: 50000, currency: 'IDR' },
  userContext: { ip: '10.0.0.1', userId: 'user-123' }
});

🌍 Ecosystem

This package is the kernel of the Satu Raya Integrasi ecosystem. It powers the following packages:

| Package | Description | |---------|-------------| | @damarkuncoro/meta-architecture | The Core Kernel. Governance, Validation, and Registry logic. | | @damarkuncoro/ui-core | Contract Definitions. Reusable atomic/molecule contracts and types. | | @damarkuncoro/ui-components | Headless UI. Framework-agnostic implementations. | | @damarkuncoro/ui-renderers | React/Vue Renderers. Maps contracts to visual components. |

🏗️ Project Structure

This project follows strict architectural guidelines:

• 1 File 1 Class: Strict file separation.
• Barrel Exports: Clean index.ts APIs.
• Strict Layering: Infrastructure → Application → Domain.

src/
├── domain/           # Pure business logic & interfaces
├── application/      # Use cases & application services
├── schemas/          # Contract schemas & definitions
├── infrastructure/   # External implementations
└── shared/           # Shared utilities

🔒 Security & Performance

• Sandboxing: Uses Node.js vm or browser-compatible safe evaluation for custom logic.
• Input Sanitization: Automatic stripping of dangerous characters.
• LRU Caching: Built-in caching for high-throughput registry access.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide (coming soon) for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.