Developer Guide

This guide provides detailed information for developers working with the MemberJunction platform, including architecture overview, database design, business logic implementation, and UI development.

MemberJunction Architecture and Key Concepts

MemberJunction is built on a modern, layered architecture that combines metadata-driven design with powerful business logic capabilities.

Metadata

MemberJunction uses a metadata-driven approach to define and manage application structure:

Entity Metadata: Describes database tables, fields, and relationships
UI Metadata: Defines forms, views, dashboards, and navigation
Authorization Metadata: Controls access to entities and fields
Business Logic Metadata: Configures rules, workflows, and validations

This metadata-driven approach enables:

Rapid application development
Consistent user experience
Dynamic customization without code changes
Simplified maintenance and upgrades

CodeGen

The CodeGen system automatically generates TypeScript code based on the metadata:

Generates strongly typed entity classes
Creates service classes for API interactions
Builds GraphQL schemas and resolvers
Produces UI components based on metadata

Benefits of the CodeGen approach:

Ensures type safety and consistency
Reduces manual coding effort
Maintains alignment between database and code
Facilitates rapid iteration and changes

CDP and Database Design

The Customer Data Platform (CDP) design in MemberJunction:

Centralizes customer data from multiple sources
Provides a unified view of customer information
Supports data segmentation and analysis
Enables personalized experiences and communications

GraphQL

MemberJunction uses GraphQL as its API layer:

Provides a flexible query language for clients
Allows clients to request exactly the data they need
Reduces over-fetching and under-fetching of data
Supports complex queries across related entities

Example GraphQL query:

query {
  organization(id: "12345") {
    id
    name
    contacts {
      id
      firstName
      lastName
      email
    }
    transactions {
      id
      date
      amount
    }
  }
}

Provider Architecture

MemberJunction uses a provider architecture for flexibility:

Data Providers: Abstract database access
Authentication Providers: Support multiple authentication methods
Storage Providers: Handle file storage and retrieval
LLM Providers: Integrate with AI language models

This provider model allows:

Swapping implementations without affecting consumers
Supporting multiple backends
Extending functionality through new providers
Testing with mock providers

Business Logic

The business logic layer in MemberJunction:

Enforces data integrity and validation
Implements business rules and workflows
Manages calculated fields and derived data
Handles complex operations across entities

Subclass Registration

The subclass registration system allows extending base entity classes:

Register custom entity classes that inherit from base classes
Override default behavior for specific entities
Add entity-specific methods and properties
Implement specialized business logic

Base Entity Object Model

All entities in MemberJunction inherit from a base entity model:

Standard CRUD operations
Change tracking
Validation
Permission checking
Event firing

MemberJunction Explorer

MemberJunction Explorer is the main user interface built on this architecture:

Uses Angular framework
Leverages metadata for dynamic UI generation
Provides consistent user experience
Supports customization and extension

Recommended Development Skills

To develop with MemberJunction, the following skills are recommended:

TypeScript/JavaScript: For client and server-side development
SQL: For database design and query optimization
Angular: For UI development
GraphQL: For API interactions
Git: For source control
Node.js: For server-side development
Azure: For cloud deployment (if using Azure)

Development Environment Requirements

Set up your development environment with:

Node.js (v14 or higher)
SQL Server or Azure SQL Database
Git
Visual Studio Code (recommended)
Angular CLI
MemberJunction CLI tools

Database Design

Database Design and Provider Model

MemberJunction's database design follows these principles:

Relational database model with proper normalization
Consistent naming conventions
Standard fields for tracking and auditing
Foreign key relationships with referential integrity
Support for multiple database providers

Database Structure and Metadata

The core database includes several key schema areas:

Admin Schema: System configuration and metadata
Entity Schema: Business data entities
Security Schema: Users, roles, and permissions
Audit Schema: Change tracking and history
Integration Schema: External system connections

The metadata tables define:

Entities (tables) and their properties
Fields and data types
Relationships between entities
UI presentation information
Validation rules and constraints

Key Design Requirements and Roles

When designing databases for MemberJunction:

Naming Conventions:
- Use PascalCase for tables and views
- Use camelCase for columns
- Use plurals for table names (e.g., Customers, not Customer)
- Prefix lookup tables with "Lookup" (e.g., LookupCountries)
Standard Fields:
- id: Primary key (GUID or auto-increment integer)
- createdAt: Timestamp of record creation
- createdBy: User who created the record
- updatedAt: Timestamp of last update
- updatedBy: User who last updated the record
Foreign Keys:
- Name as {relatedTable}Id (e.g., customerId)
- Create indexes on foreign key columns
- Set appropriate cascade behavior

Database Functionality -- CodeGen

The CodeGen system generates database assets:

Stored procedures for CRUD operations
Views for filtered or joined data
Functions for calculated values
Indexes for performance optimization

Base Views and Full Text Indexing

MemberJunction creates base views for each entity:

Combines related data for easier querying
Includes display and computed fields
Supports full-text indexing for search
Provides a consistent API for data access

Full-text indexing configuration:

Specify which fields should be indexed
Configure language and search options
Set up catalog and index maintenance

Datasets

Datasets in MemberJunction provide:

Pre-defined queries for common data needs
Parameterized data access
Re-usable data components
Performance optimized data retrieval

Business Logic and MemberJunction Object Model

Base Entity Object Model

The base entity object model provides:

Standard Methods:
- load(): Load a record by ID
- save(): Create or update a record
- delete(): Delete a record
- validate(): Validate field values
- calculateFields(): Update calculated fields
Properties:
- Data properties matching database fields
- Metadata about the entity
- Change tracking information
- Validation state

Example of using the base entity model:

// Load an existing organization
const org = await OrganizationEntity.load(123);

// Update properties
org.name = "New Organization Name";
org.website = "https://example.com";

// Save changes
await org.save();

Subclass Registration

Extend entity classes with custom business logic:

@RegisterClass(OrganizationEntity)
export class CustomOrganizationEntity extends OrganizationEntity {
  // Override base methods
  async validate(): Promise<ValidationResult> {
    const result = await super.validate();
    
    // Add custom validation
    if (this.name && this.name.length < 3) {
      result.addError('name', 'Organization name must be at least 3 characters');
    }
    
    return result;
  }
  
  // Add custom methods
  async getRevenueAnalysis(): Promise<RevenueAnalysis> {
    // Custom business logic here
    return analysis;
  }
}

Loose Coupling

MemberJunction's architecture supports loose coupling:

Components interact through well-defined interfaces
Dependencies are injected rather than hard-coded
Events enable communication without direct dependencies
Services provide centralized functionality

Two-way Data Binding

UI components use two-way data binding:

Changes in the UI update the model
Changes in the model update the UI
Validation errors propagate to the UI
Changed fields are tracked for partial updates

Custom Business Logic

Implement custom business logic through:

Entity Method Overrides:
- Override validate(), save(), delete(), etc.
- Add pre/post processing logic
- Implement custom validation rules
Business Rules:
- Define declarative rules in metadata
- Create rule handlers for complex logic
- Set up validation and calculation rules
Event Handlers:
- Subscribe to entity events (onCreate, onUpdate, etc.)
- Implement cross-entity logic
- Trigger notifications or workflows
Custom Services:
- Create specialized services for complex operations
- Implement business processes spanning multiple entities
- Build integration with external systems

Business Logic Across Tiers

Business logic is implemented across different tiers:

Database Tier:
- Constraints and triggers
- Stored procedures
- Computed columns
Server Tier:
- Entity validation and processing
- Business rules and workflows
- Authorization and security
Client Tier:
- UI validation
- User experience logic
- Client-side calculations

AI Actions

MemberJunction supports AI-powered actions:

Define actions that use AI models
Connect actions to entity events or user triggers
Process data using Large Language Models
Enhance user experience with AI-driven suggestions

Examples of AI actions:

Summarize customer interactions
Generate content based on data
Classify and categorize records
Predict outcomes and make recommendations

Vectors and Entity Embeddings

MemberJunction supports vector embeddings for advanced AI capabilities:

Generate embeddings from entity data
Store vectors for semantic search
Find similar records using vector similarity
Enhance search with semantic understanding

Implementation steps:

Configure entities for embedding generation
Select fields to include in the embedding
Choose the embedding model and parameters
Generate and store embeddings
Use embeddings for search and recommendations

UI and Front-End Development

MemberJunction's front-end is built with Angular:

Component-based architecture
Reactive programming with RxJS
Material Design components
Responsive layouts
Theme customization

Custom Component Development

To create custom components:

Generate a new component:

ng generate component my-custom-component

Implement the component logic:

@Component({
  selector: 'app-my-custom-component',
  templateUrl: './my-custom-component.component.html',
  styleUrls: ['./my-custom-component.component.scss']
})
export class MyCustomComponent implements OnInit {
  @Input() entity: BaseEntity;
  @Output() entityChanged = new EventEmitter<BaseEntity>();
  
  // Component logic here
}

Create the component template:

<div class="custom-component">
  <h2>{{entity.name}}</h2>
  <div class="custom-content">
    <!-- Custom UI here -->
  </div>
  <button (click)="saveChanges()">Save</button>
</div>

GitHub Repo

MemberJunction is an open-source project hosted on GitHub:

Repository: https://github.com/MemberJunction/MJ
Issues: https://github.com/MemberJunction/MJ/issues
Pull Requests: https://github.com/MemberJunction/MJ/pulls

Libraries

MemberJunction is organized into several key libraries:

@memberjunction/core: Core entity and business logic
@memberjunction/graphql: GraphQL API implementation
@memberjunction/ui: Common UI components
@memberjunction/codegen: Code generation tools

Sample Application

The repository includes a sample application demonstrating MemberJunction features.

Overview

The sample application includes:

Customer management
Organization tracking
Activity logging
Reporting and analytics
AI-powered features

Building and Running the Sample Application

Clone the repository:

git clone https://github.com/MemberJunction/MJ.git
cd MJ

Install dependencies:
```
npm install
```
Configure the database connection in config.ts
Run the setup script:
```
npm run setup
```
Start the application:
```
npm start
```
Open your browser to http://localhost:4200