Metadata-Driven Architecture in MemberJunction

MemberJunction implements a powerful metadata-driven architecture that forms the foundation of the platform. This approach provides flexibility, extensibility, and a unified data model that accelerates development and simplifies integration.

What is Metadata-Driven Architecture?

Metadata-driven architecture is a design pattern where application behavior is determined by metadata rather than hard-coded logic. In MemberJunction, metadata describes entities, relationships, and business rules, allowing the platform to dynamically generate code, interfaces, and behaviors based on these descriptions.

Key benefits of this approach include:

• Flexibility: Changes to the application can often be made by updating metadata rather than modifying code
• Consistency: Common behaviors are defined once and applied universally
• Reduced development time: Automated code generation based on metadata eliminates repetitive coding tasks
• Simplified maintenance: Centralized metadata makes system-wide changes more manageable

The Metadata Layer

MemberJunction's metadata layer consists of several key components:

Entity Metadata

Entity metadata defines the structure and behavior of data objects in the system. This includes:

• Entity names and descriptions
• Properties (fields) with their data types and constraints
• Relationships to other entities
• Default behaviors and validation rules

Example entity metadata (simplified):

{
  "name": "Member",
  "description": "A member of the organization",
  "schema": "dbo",
  "tableName": "Members",
  "primaryKey": "MemberID",
  "properties": [
    {
      "name": "MemberID",
      "dataType": "int",
      "isRequired": true,
      "isPrimaryKey": true,
      "isAutoIncrement": true
    },
    {
      "name": "FirstName",
      "dataType": "string",
      "maxLength": 100,
      "isRequired": true
    },
    {
      "name": "LastName",
      "dataType": "string",
      "maxLength": 100,
      "isRequired": true
    },
    {
      "name": "Email",
      "dataType": "string",
      "maxLength": 255,
      "isRequired": true,
      "isUnique": true
    }
  ],
  "relationships": [
    {
      "name": "MembershipTypes",
      "entityName": "MembershipType",
      "propertyName": "MembershipTypeID",
      "foreignKeyName": "FK_Members_MembershipTypes"
    }
  ]
}

Relationship Metadata

Relationship metadata defines how entities are connected to each other. This includes:

• Foreign key relationships
• Many-to-many relationships
• Navigation properties
• Cascading behavior

View Metadata

View metadata defines how data is presented to users. This includes:

• Customized field labels and descriptions
• Field grouping and ordering
• Conditional visibility rules
• Default sorting and filtering

Permission Metadata

Permission metadata defines access control rules for entities and operations:

• Role-based access control
• Field-level security
• Operation permissions (Create, Read, Update, Delete)
• Data-driven permissions (row-level security)

CodeGen: From Metadata to Code

One of the key features of MemberJunction is its CodeGen system, which transforms metadata into executable code. This process:

1. Reads entity and relationship metadata
2. Generates TypeScript interfaces and classes
3. Creates data access layer code
4. Builds entity validation logic
5. Constructs API endpoints

Generate Entity Classes

For each entity defined in metadata, MemberJunction generates:

• A base entity class with all properties and relationships
• Validation logic based on metadata constraints
• Navigation properties for related entities
• Change tracking and dirty checking logic

Example generated entity class:

// Auto-generated code - do not modify

import { Entity, EntityBase } from '../core/entity';
import { EntityProperty } from '../core/entity-property';
import { MembershipType } from './membership-type.entity';

@Entity('Member', 'dbo', 'Members')
export class Member extends EntityBase {
  // Properties
  @EntityProperty({ isPrimaryKey: true, isAutoIncrement: true })
  MemberID: number;

  @EntityProperty({ isRequired: true, maxLength: 100 })
  FirstName: string;

  @EntityProperty({ isRequired: true, maxLength: 100 })
  LastName: string;

  @EntityProperty({ isRequired: true, maxLength: 255, isUnique: true })
  Email: string;

  @EntityProperty({ foreignKey: 'FK_Members_MembershipTypes' })
  MembershipTypeID: number;

  // Navigation properties
  MembershipType?: MembershipType;

  // Generated constructor
  constructor() {
    super();
    this.MemberID = 0;
    this.FirstName = '';
    this.LastName = '';
    this.Email = '';
    this.MembershipTypeID = 0;
  }
}

Extending Generated Code

While MemberJunction generates a significant amount of code automatically, you can extend the generated classes to add custom business logic. The architecture uses a "subclass registration" pattern where:

1. Generated base classes contain core functionality
2. You create subclasses that extend the base classes
3. Your subclasses register themselves with the system
4. At runtime, the system instantiates your subclasses instead of the base classes

Example custom entity extension:

// Custom code - put your customizations here

import { Member as MemberBase } from './generated/member.entity';
import { EntityRegister } from '../core/entity-register';

export class Member extends MemberBase {
  // Custom properties
  get FullName(): string {
    return `${this.FirstName} ${this.LastName}`;
  }

  // Custom methods
  validateEmail(): boolean {
    // Custom email validation logic
    const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
    return emailRegex.test(this.Email);
  }

  // Override base methods
  override async beforeSave(): Promise<boolean> {
    // Custom logic before saving
    if (!this.validateEmail()) {
      this.addValidationError('Email', 'Invalid email format');
      return false;
    }
    return await super.beforeSave();
  }
}

// Register this subclass with the system
EntityRegister.registerEntity(Member);

Creating and Extending Metadata

MemberJunction provides several ways to define and extend metadata:

Database-First Approach

For existing databases, MemberJunction can scan your database schema and automatically generate entity metadata:

1. Connect to your database
2. Run the metadata extraction process
3. Review and refine the generated metadata
4. Generate code based on the metadata

Code-First Approach

For new projects, you can define your metadata in code using decorators or configuration files:

import { Entity, Property, Relationship } from '@memberjunction/core';

@Entity({
  description: 'A member of the organization',
  schema: 'dbo',
  tableName: 'Members'
})
export class Member {
  @Property({
    isPrimaryKey: true,
    isAutoIncrement: true,
    description: 'Unique identifier'
  })
  MemberID: number;

  @Property({
    isRequired: true,
    maxLength: 100,
    description: 'Member first name'
  })
  FirstName: string;

  @Property({
    isRequired: true,
    maxLength: 100,
    description: 'Member last name'
  })
  LastName: string;

  @Property({
    isRequired: true,
    maxLength: 255,
    isUnique: true,
    description: 'Email address'
  })
  Email: string;

  @Relationship({
    entity: 'MembershipType',
    description: 'Type of membership'
  })
  MembershipTypeID: number;
}

Hybrid Approach

For most projects, a hybrid approach works best:

1. Start with database or code-first metadata generation
2. Refine the metadata through the MemberJunction Explorer interface
3. Add business rules and validation logic
4. Generate code based on the metadata

The Metadata Repository

MemberJunction stores all metadata in a central repository, which consists of several database tables:

• Entities: Defines entities and their properties
• EntityFields: Defines fields (properties) for each entity
• EntityRelationships: Defines relationships between entities
• EntityPermissions: Defines access control for entities
• EntityViews: Defines custom views of entities

The metadata repository is accessible through both the API and the MemberJunction Explorer interface, allowing you to view and modify metadata at runtime.

Practical Applications

The metadata-driven architecture of MemberJunction empowers several key scenarios:

Dynamic UI Generation

MemberJunction can generate user interfaces based on metadata, including:

• Forms for creating and editing entities
• List views with sorting and filtering
• Detail views with related data
• Search interfaces

Flexible Reporting

Metadata powers the reporting system, allowing users to:

• Create ad-hoc reports
• Define custom calculations
• Apply complex filters
• Export data in various formats

APIs and Integration

The metadata is used to generate APIs for integration, including:

• GraphQL API with automatic schema generation
• REST API endpoints for all entities
• Import/export utilities
• Integration with external systems

Best Practices

When working with MemberJunction's metadata architecture, follow these best practices:

1. Start with a clean data model: Take time to design your entities and relationships properly
2. Use meaningful names and descriptions: These will be used in the UI and documentation
3. Leverage validation rules: Define them in metadata rather than custom code when possible
4. Extend rather than modify: Use subclassing instead of changing generated code
5. Keep metadata in version control: Treat metadata changes like code changes
6. Document custom extensions: Especially business logic that isn't obvious from the metadata