@memberjunction/server 4.0.0 → 4.1.0

package/README.md

@@ -1,84 +1,180 @@
 # @memberjunction/server
 
-The `@memberjunction/server` library provides a comprehensive API server for MemberJunction, featuring both GraphQL and REST APIs. It includes all the functions required to start up the server, manage authentication, handle database connections, and provide a robust interface for accessing and managing metadata within MemberJunction.
-
-## Key Features
-
-- **Dual API Support**: Both GraphQL and REST APIs with consistent authentication
-- **Multi-Database Support**: Read-write and optional read-only database connections
-- **Advanced Authentication**: Support for MSAL (Azure AD) and Auth0 authentication providers
-- **Transaction Management**: Automatic transaction wrapper for GraphQL mutations
-- **Type-Safe Resolvers**: Full TypeScript support with type-graphql integration
-- **Entity Management**: Comprehensive CRUD operations with change tracking
-- **Real-time Support**: WebSocket subscriptions for GraphQL
-- **Compression**: Built-in response compression for better performance
-- **Extensible Architecture**: Support for custom resolvers and entity subclasses
-- **AI Integration**: Built-in support for AI operations, prompts, agents, and embeddings
-- **Security Features**: Entity-level and schema-level access control for REST API
-- **SQL Logging**: Runtime SQL logging configuration and session management for debugging
+The MemberJunction server package provides the complete API server infrastructure for MemberJunction applications. It delivers both GraphQL and REST APIs with a unified authentication layer, per-request transaction isolation, pluggable authentication providers, scope-based API key authorization, scheduled job orchestration, SQL logging, and built-in AI operation endpoints. This package is the primary integration point between client applications and the MemberJunction data layer.
 
 ## Installation
 
-```shell
+```bash
 npm install @memberjunction/server
 ```
 
-## Dependencies
+## Overview
+
+MJServer acts as the central API gateway for MemberJunction, sitting between client applications (MJExplorer, external integrations, AI agents) and the SQL Server database via the `@memberjunction/sqlserver-dataprovider`. It initializes database connections, loads entity metadata, builds a GraphQL schema from dynamically discovered resolver modules, optionally exposes a REST API, and manages the full request lifecycle including authentication, per-request provider isolation, and transaction management.
+
+```mermaid
+flowchart TD
+    subgraph Clients["Client Applications"]
+        EX[MJ Explorer]
+        EXT[External Apps]
+        AI[AI Agents / MCP]
+    end
+
+    subgraph MJServer["@memberjunction/server"]
+        direction TB
+        AUTH[Authentication Layer]
+        GQL[GraphQL API - Apollo Server]
+        REST[REST API - Express Routes]
+        CTX[Request Context & Provider Factory]
+        RES[Resolver Layer]
+        SCHED[Scheduled Jobs Service]
+        SQLLOG[SQL Logging Manager]
+    end
+
+    subgraph Data["Data Layer"]
+        SQLP[SQL Server Data Provider]
+        DB[(SQL Server Database)]
+    end
+
+    Clients --> AUTH
+    AUTH --> GQL
+    AUTH --> REST
+    GQL --> CTX
+    REST --> CTX
+    CTX --> RES
+    RES --> SQLP
+    SQLP --> DB
+    SCHED --> SQLP
+
+    style Clients fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style MJServer fill:#7c5295,stroke:#563a6b,color:#fff
+    style Data fill:#2d8659,stroke:#1a5c3a,color:#fff
+```
 
-This package depends on several core MemberJunction packages:
-- `@memberjunction/core`: Core functionality and metadata management
-- `@memberjunction/sqlserver-dataprovider`: SQL Server data provider
-- `@memberjunction/graphql-dataprovider`: GraphQL data provider
-- `@memberjunction/ai`: AI engine integration
-- Various other MJ packages for specific functionality
+### Key Features
+
+- **Dual API Support**: GraphQL (Apollo Server) and REST APIs with consistent authentication and authorization
+- **Pluggable Authentication**: Support for Azure AD/Entra ID (MSAL), Auth0, Okta, AWS Cognito, and Google via the `IAuthProvider` interface
+- **API Key Authorization**: User-level (`X-API-Key`) and system-level (`x-mj-api-key`) API keys with scope-based access control
+- **Per-Request Provider Isolation**: Each GraphQL request receives its own `SQLServerDataProvider` instance for transaction safety
+- **Multi-Database Support**: Separate read-write and read-only database connection pools
+- **Transaction Management**: Automatic transaction wrapping for GraphQL mutations with savepoint support
+- **Scheduled Jobs**: Built-in job scheduler with configurable polling, concurrency limits, and lock management
+- **SQL Logging**: Real-time SQL statement capture with session management, user filtering, and migration-format output
+- **AI Integration**: Resolvers for AI prompt execution, agent orchestration, text embeddings, and Skip AI
+- **Real-time Support**: WebSocket subscriptions via `graphql-ws`
+- **Response Compression**: Built-in gzip compression with configurable thresholds
+- **Encryption Handling**: Transparent field-level encryption/decryption with configurable API exposure policies
+- **CloudEvents**: Optional CloudEvent emission for entity lifecycle events
+- **Telemetry**: Configurable server-side telemetry with multiple verbosity levels
+- **Extensible Architecture**: Custom resolvers, entity subclasses, and new user handling via `@RegisterClass`
 
 ## Configuration
 
-The server uses configuration from its environment
-
-| Env variable             | Description                                                  |
-| ------------------------ | ------------------------------------------------------------ |
-| DB_HOST                  | The hostname for the common data store database              |
-| DB_PORT                  | The port for the common data store database (default 1433)   |
-| DB_USERNAME              | The username used to authenticate with the common data store |
-| DB_PASSWORD              | The password used to authenticate with the common data store |
-| DB_DATABASE              | The common data store database name                          |
-| PORT                     | The port used by the server (default 4000)                   |
-| ROOT_PATH                | The GraphQL root path (default /)                            |
-| WEB_CLIENT_ID            | The client ID used for MSAL authentication                   |
-| TENANT_ID                | The tenant ID used for MSAL authentication                   |
-| ENABLE_INTROSPECTION     | A flag to allow GraphQL introspection (default false)        |
-| WEBSITE_RUN_FROM_PACKAGE | An Azure flag to indicate a read-only file system            |
-| AUTH0_DOMAIN             | The Auth0 domain                                             |
-| AUTH0_CLIENT_ID          | The Auth0 Client ID                                          |
-| AUTH0_CLIENT_SECRET      | The Auth0 Client secret                                      |
-| MJ_CORE_SCHEMA           | The core schema to use for the data provider                 |
-| CONFIG_FILE              | An absolute path to the config file json                     |
-| DB_READ_ONLY_USERNAME    | Username for read-only database connection (optional)        |
-| DB_READ_ONLY_PASSWORD    | Password for read-only database connection (optional)        |
-
-### REST API
-
-In addition to the GraphQL API, MemberJunction provides a REST API for applications that prefer RESTful architecture. By default, the REST API is enabled but can be disabled.
-
-For comprehensive documentation on the REST API, including configuration options, security controls, and available endpoints, see [REST_API.md](./REST_API.md).
-
-The REST API supports:
-- Standard CRUD operations for entities
-- View operations for data retrieval
-- Metadata exploration
-- Wildcard pattern matching for entity filtering
-- Schema-level access control
-- Comprehensive security configuration
+MJServer uses a layered configuration system with the following priority (highest to lowest):
+
+1. Environment variables
+2. `mj.config.cjs` file (discovered via [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig))
+3. `DEFAULT_SERVER_CONFIG` hardcoded defaults
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DB_HOST` | Database server hostname | `localhost` |
+| `DB_PORT` | Database server port | `1433` |
+| `DB_DATABASE` | Database name | (required) |
+| `DB_USERNAME` | Database username | (required) |
+| `DB_PASSWORD` | Database password | (required) |
+| `DB_READ_ONLY_USERNAME` | Read-only connection username | (optional) |
+| `DB_READ_ONLY_PASSWORD` | Read-only connection password | (optional) |
+| `DB_TRUST_SERVER_CERTIFICATE` | Trust self-signed certs | `false` |
+| `DB_INSTANCE_NAME` | Named SQL Server instance | (optional) |
+| `MJ_CORE_SCHEMA` | MJ metadata schema name | `__mj` |
+| `GRAPHQL_PORT` | Server listen port | `4000` |
+| `GRAPHQL_ROOT_PATH` | GraphQL endpoint path | `/` |
+| `GRAPHQL_BASE_URL` | Server base URL | `http://localhost` |
+| `MJAPI_PUBLIC_URL` | Public callback URL (e.g. ngrok) | (optional) |
+| `ENABLE_INTROSPECTION` | Allow GraphQL introspection | `false` |
+| `MJ_API_KEY` | System-level API key | (optional) |
+| `TENANT_ID` | Azure AD tenant ID | (optional) |
+| `WEB_CLIENT_ID` | Azure AD client ID | (optional) |
+| `AUTH0_DOMAIN` | Auth0 domain | (optional) |
+| `AUTH0_CLIENT_ID` | Auth0 client ID | (optional) |
+| `AUTH0_CLIENT_SECRET` | Auth0 client secret | (optional) |
+| `WEBSITE_RUN_FROM_PACKAGE` | Azure read-only filesystem flag | (optional) |
+| `MJ_REST_API_ENABLED` | Enable/disable REST API | (from config) |
+| `MJ_REST_API_INCLUDE_ENTITIES` | Comma-separated entity include list | (optional) |
+| `MJ_REST_API_EXCLUDE_ENTITIES` | Comma-separated entity exclude list | (optional) |
+| `MJ_TELEMETRY_ENABLED` | Enable server telemetry | `true` |
+| `METADATA_CACHE_REFRESH_INTERVAL` | Metadata refresh interval (ms) | `180000` |
+
+### Configuration File (`mj.config.cjs`)
+
+```javascript
+module.exports = {
+  dbHost: 'myserver.database.windows.net',
+  dbDatabase: 'MemberJunction',
+  dbUsername: 'mj_user',
+  dbPassword: 'secret',
+  mjCoreSchema: '__mj',
+  graphqlPort: 4000,
+
+  userHandling: {
+    autoCreateNewUsers: true,
+    newUserLimitedToAuthorizedDomains: false,
+    newUserRoles: ['UI', 'Developer'],
+    contextUserForNewUserCreation: 'admin@example.com',
+    CreateUserApplicationRecords: true,
+  },
+
+  databaseSettings: {
+    connectionTimeout: 45000,
+    requestTimeout: 30000,
+    metadataCacheRefreshInterval: 180000,
+    connectionPool: {
+      max: 50,
+      min: 5,
+      idleTimeoutMillis: 30000,
+      acquireTimeoutMillis: 30000,
+    },
+  },
+
+  restApiOptions: {
+    enabled: true,
+    includeEntities: ['User*', 'Entity*'],
+    excludeEntities: ['Password', 'APIKey*'],
+    includeSchemas: ['public'],
+    excludeSchemas: ['internal'],
+  },
+
+  scheduledJobs: {
+    enabled: true,
+    systemUserEmail: 'system@example.com',
+    maxConcurrentJobs: 5,
+  },
+
+  sqlLogging: {
+    enabled: true,
+    allowedLogDirectory: './logs/sql',
+    maxActiveSessions: 5,
+    sessionTimeout: 3600000,
+  },
 
+  telemetry: {
+    enabled: true,
+    level: 'standard',  // 'minimal' | 'standard' | 'verbose' | 'debug'
+  },
+};
+```
 
 ## Usage
 
 ### Basic Server Setup
 
-Import the `serve` function from the package and run it as part of the server's main function. The function accepts an array of absolute paths to the resolver code.
+Import the `serve` function and provide paths to your custom resolver modules. The server automatically includes its own built-in resolvers.
 
-```ts
+```typescript
 import { serve } from '@memberjunction/server';
 import { resolve } from 'node:path';
 
@@ -88,357 +184,338 @@ const resolverPaths = [
   'resolvers/**/*Resolver.{js,ts}',
   'generic/*Resolver.{js,ts}',
   'generated/generated.ts',
-]
+];
 
 serve(resolverPaths.map(localPath));
 ```
 
 ### Advanced Server Options
 
-The `serve` function accepts an optional `MJServerOptions` object:
+The `serve` function accepts an optional `MJServerOptions` object for lifecycle hooks and REST API overrides.
 
 ```typescript
-import { serve, MJServerOptions } from '@memberjunction/server';
+import { serve, createApp, MJServerOptions } from '@memberjunction/server';
 
 const options: MJServerOptions = {
   onBeforeServe: async () => {
-    // Custom initialization logic
+    // Custom initialization after schema is built, before HTTP listen
     console.log('Server is about to start...');
   },
   restApiOptions: {
     enabled: true,
     includeEntities: ['User*', 'Entity*'],
     excludeEntities: ['Password', 'APIKey*'],
-    includeSchemas: ['public'],
-    excludeSchemas: ['internal']
-  }
+  },
 };
 
 serve(resolverPaths.map(localPath), createApp(), options);
 ```
 
-### Transaction Management
+### Custom New User Handling
 
-MJServer provides automatic transaction management for all GraphQL mutations with full support for multi-user environments through per-request provider instances.
-
-#### Per-Request Provider Architecture
-
-Each GraphQL request receives its own SQLServerDataProvider instance, ensuring complete isolation between concurrent requests:
+Override the default new user creation behavior by subclassing `NewUserBase` and registering it with a higher priority.
 
 ```typescript
-// Each request automatically:
-// 1. Creates a new SQLServerDataProvider instance
-// 2. Reuses cached metadata for fast initialization
-// 3. Has isolated transaction state within the provider
-// 4. Gets garbage collected after request completion
-
-mutation {
-  CreateUser(input: { FirstName: "John", LastName: "Doe" }) {
-    ID
-  }
-  CreateUserRole(input: { UserID: "...", RoleID: "..." }) {
-    ID
+import { RegisterClass } from '@memberjunction/global';
+import { NewUserBase } from '@memberjunction/server';
+
+@RegisterClass(NewUserBase, undefined, 1)
+export class CustomNewUserHandler extends NewUserBase {
+  public override async createNewUser(
+    firstName: string,
+    lastName: string,
+    email: string
+  ) {
+    // Custom logic: create linked records, assign roles, etc.
+    return super.createNewUser(firstName, lastName, email, 'Other');
   }
 }
-// Both operations execute within the same provider's transaction
-// Success: Both committed together
-// Error: Both rolled back together
 ```
 
-#### Key Transaction Features
+Import the file before calling `serve` to ensure registration:
 
-- **Provider Isolation**: Each request has its own data provider instance
-- **Automatic Management**: Transactions are automatically started, committed, or rolled back
-- **Multi-User Safety**: Concurrent requests have completely isolated provider instances
-- **Zero Configuration**: No transaction IDs or scope management needed
-- **Efficient**: Metadata caching makes provider creation lightweight
-- **Nested Support**: Providers use SQL Server savepoints for nested transaction logic
+```typescript
+import './auth/customNewUserHandler';
+import { serve } from '@memberjunction/server';
+// ...
+serve(resolverPaths);
+```
 
-### Provider Configuration
+## Architecture
+
+### Request Lifecycle
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant A as Auth Layer
+    participant CF as Context Factory
+    participant R as Resolver
+    participant P as SQLServerDataProvider
+    participant DB as SQL Server
+
+    C->>A: Request (Bearer token / API key)
+    A->>A: Validate JWT or API key
+    A->>A: Resolve UserInfo from UserCache
+    A->>CF: Create request context
+    CF->>P: New per-request provider instance
+    P->>P: Reuse cached metadata
+    CF->>R: Pass AppContext with providers
+    R->>P: Execute operations
+    P->>DB: SQL queries within transaction
+    DB-->>P: Results
+    P-->>R: Entity objects / data
+    R-->>C: GraphQL / REST response
+    Note over P,DB: Transaction auto-committed on success, rolled back on error
+```
 
-MJServer automatically creates per-request SQLServerDataProvider instances for optimal isolation and performance:
+### Per-Request Provider Isolation
+
+Each GraphQL request receives its own `SQLServerDataProvider` instance, ensuring complete transaction isolation between concurrent requests. Metadata is cached and reused across providers for efficiency.
 
 ```typescript
-// In each GraphQL request context:
+// Automatically created per request in context.ts:
 const provider = new SQLServerDataProvider();
 await provider.Config({
   connectionPool: pool,
   MJCoreSchemaName: '__mj',
-  ignoreExistingMetadata: false  // Reuse cached metadata
+  ignoreExistingMetadata: false,  // Reuse cached metadata
 });
 
-// Provider is included in AppContext
-context.providers = [{
-  provider: provider,
-  type: 'Read-Write'
-}];
+// Included in AppContext for resolvers:
+context.providers = [
+  { provider: readWriteProvider, type: 'Read-Write' },
+  { provider: readOnlyProvider, type: 'Read-Only' },  // if configured
+];
 ```
 
-#### Provider Types
-
-The AppContext supports multiple providers with different access levels:
-
-```typescript
-export type AppContext = {
-  dataSource: sql.ConnectionPool;  // Legacy, for backward compatibility
-  userPayload: UserPayload;
-  dataSources: DataSourceInfo[];
-  providers: Array<ProviderInfo>;  // Per-request provider instances
-};
-
-export class ProviderInfo {
-  provider: DatabaseProviderBase;
-  type: 'Admin' | 'Read-Write' | 'Read-Only' | 'Other';
-}
+### Authentication Architecture
+
+MJServer uses a pluggable authentication provider system built on the `IAuthProvider` interface and `AuthProviderFactory`.
+
+```mermaid
+flowchart LR
+    subgraph Providers["Auth Providers"]
+        MSAL[MSAL / Azure AD]
+        A0[Auth0]
+        OK[Okta]
+        COG[AWS Cognito]
+        GOOG[Google]
+    end
+
+    subgraph Factory["AuthProviderFactory"]
+        REG[Provider Registry]
+        CACHE[Issuer Cache]
+    end
+
+    subgraph Auth["Authentication Flow"]
+        JWT[JWT Token]
+        APIKEY[API Key]
+        SYS[System API Key]
+    end
+
+    JWT --> REG
+    REG --> Providers
+    APIKEY --> VAL[API Key Engine]
+    SYS --> SYSUSER[System User Lookup]
+
+    style Providers fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style Factory fill:#7c5295,stroke:#563a6b,color:#fff
+    style Auth fill:#b8762f,stroke:#8a5722,color:#fff
 ```
 
-### Custom New User Behavior
+Providers are registered via `@RegisterClass(BaseAuthProvider, 'type-key')` and automatically discovered at startup. Each provider implements:
 
-The behavior to handle new users can be customized by subclassing the `NewUserBase` class. The subclass can pre-process, post-process or entirely override the base class behavior as needed. Import the class before calling `serve` to ensure the class is registered.
+- `validateConfig()` -- Validates required configuration
+- `getSigningKey()` -- Retrieves JWKS signing keys with retry logic
+- `extractUserInfo()` -- Extracts email, name from provider-specific JWT claims
+- `matchesIssuer()` -- Matches JWT `iss` claim to the provider
 
-`index.ts`
+Configure providers in `mj.config.cjs` under `authProviders` or via environment variables (see Configuration section).
 
-```ts
-import { serve } from '@memberjunction/server';
-import { resolve } from 'node:path';
-
-import './auth/exampleNewUserSubClass'; // make sure this new class gets registered
-
-// ...
-```
-
-
-`auth/exampleNewUserSubClass.ts`
-
-```ts
-import { LogError, Metadata, RunView } from "@memberjunction/core";
-import { RegisterClass } from "@memberjunction/global";
-import { NewUserBase, configInfo } from '@memberjunction/server';
-import { UserCache } from "@memberjunction/sqlserver-dataprovider";
-
-/**
- * This example class subclasses the @NewUserBase class and overrides the createNewUser method to create a new person record and then call the base class to create the user record. In this example there is an entity
- * called "Persons" that is mapped to the User table in the core MemberJunction schema. You can sub-class the NewUserBase to do whatever behavior you want and pre-process, post-process or entirely override the base
- * class behavior.
- */
-@RegisterClass(NewUserBase, undefined, 1) /*by putting 1 into the priority setting, MJGlobal ClassFactory will use this instead of the base class as that registration had no priority*/
-export class ExampleNewUserSubClass extends NewUserBase {
-    public override async createNewUser(firstName: string, lastName: string, email: string) {
-        try {
-            const md = new Metadata();
-            const contextUser = UserCache.Instance.Users.find(u => u.Email.trim().toLowerCase() === configInfo?.userHandling?.contextUserForNewUserCreation?.trim().toLowerCase())
-            if(!contextUser) {
-                LogError(`Failed to load context user ${configInfo?.userHandling?.contextUserForNewUserCreation}, if you've not specified this on your config.json you must do so. This is the user that is contextually used for creating a new user record dynamically.`);
-                return undefined;
-            }
-
-            const pEntity = md.Entities.find(e => e.Name === 'Persons'); // look up the entity info for the Persons entity
-            if (!pEntity) {
-                LogError('Failed to find Persons entity');
-                return undefined;
-            }
-
-            let personId;
-            // this block of code only executes if we have an entity called Persons
-            const rv = new RunView();
-            const viewResults = await rv.RunView({
-                EntityName: 'Persons',
-                ExtraFilter: `Email = '${email}'`
-            }, contextUser)
-    
-            if (viewResults && viewResults.Success && Array.isArray(viewResults.Results) && viewResults.Results.length > 0) {
-                // we have a match so use it
-                const row = (viewResults.Results as { ID: number }[])[0]; // we know the rows will have an ID number
-                personId = row['ID'];
-            }
-    
-            if (!personId) {
-                // we don't have a match so create a new person record
-                const p = await md.GetEntityObject('Persons', contextUser);
-                p.NewRecord(); // assumes we have an entity called Persons that has FirstName/LastName/Email fields
-                p.FirstName = firstName;
-                p.LastName = lastName;
-                p.Email = email;
-                p.Status = 'active';
-                if (await p.Save()) {
-                    personId = p.ID;
-                }   
-                else {
-                    LogError(`Failed to create new person ${firstName} ${lastName} ${email}`)
-                }
-            }
-    
-            // now call the base class to create the user, and pass in our LinkedRecordType and ID
-            return super.createNewUser(firstName, lastName, email, 'Other', pEntity?.ID, personId);        
-        }
-        catch (e) {
-            LogError(`Error creating new user ${email} ${e}`);
-            return undefined;
-        }
-    }
-}
-```
-
-## API Documentation
-
-### Core Exports
-
-The package exports numerous utilities and types:
-
-#### Server Functions
-- `serve(resolverPaths: string[], app?: Express, options?: MJServerOptions)`: Main server initialization
-- `createApp()`: Creates an Express application instance
-
-#### Authentication
-- `NewUserBase`: Base class for custom new user handling
-- `TokenExpiredError`: Token expiration error class
-- `getSystemUser(dataSource?: DataSource)`: Get system user for operations
-
-#### Resolvers and Base Classes
-- `ResolverBase`: Base class for custom resolvers
-- `RunViewResolver`: Base resolver for view operations
-- `PushStatusResolver`: Status update resolver base
-
-#### Type Definitions
-- `AppContext`: GraphQL context type
-- `DataSourceInfo`: Database connection information
-- `KeyValuePairInput`: Generic key-value input type
-- `DeleteOptionsInput`: Delete operation options
+### API Key Authentication
 
-#### Utility Functions
-- `GetReadOnlyDataSource(dataSources: DataSourceInfo[])`: Get read-only data source
-- `GetReadWriteDataSource(dataSources: DataSourceInfo[])`: Get read-write data source
+The server supports two types of API key authentication:
 
-### Entity Subclasses
+**User API Keys** (`X-API-Key` header, `mj_sk_*` format):
+- Authenticate as a specific user
+- Support expiration dates and individual revocation
+- Subject to scope-based authorization
+- Usage is logged for audit
 
-The server includes specialized entity subclasses:
-- `UserViewEntityServer`: Server-side user view handling
-- `EntityPermissionsEntityServer`: Entity permission management
-- `DuplicateRunEntityServer`: Duplicate detection operations
-- `ReportEntityServer`: Report generation and management
+**System API Key** (`x-mj-api-key` header):
+- Single shared key set via `MJ_API_KEY` environment variable
+- Authenticates as the system user with elevated privileges
+- Used for server-to-server communication
 
-## AI Integration
+### Scope-Based Authorization
 
-The server includes built-in AI capabilities:
+API keys are subject to a two-level scope evaluation: the application ceiling (maximum allowed scopes for MJAPI, MCP Server, etc.) and the individual key's assigned scopes.
 
-### Learning Cycle Scheduler
+| Scope | Description |
+|-------|-------------|
+| `full_access` | Bypass all scope checks |
+| `entity:read` | Read entity records |
+| `entity:create` | Create records |
+| `entity:update` | Update records |
+| `entity:delete` | Delete records |
+| `view:run` | Execute RunView queries |
+| `agent:execute` | Execute AI agents |
+| `agent:monitor` | Check agent run status |
+| `action:execute` | Execute MJ Actions |
+| `prompt:execute` | Execute AI prompts |
+| `query:run` | Execute queries |
+| `metadata:entities:read` | Read entity metadata |
+| `metadata:agents:read` | Read agent metadata |
+| `communication:send` | Send emails/messages |
 
-The server can automatically run AI learning cycles:
+Add scope checks to custom resolvers:
 
 ```typescript
-import { LearningCycleScheduler } from '@memberjunction/server/scheduler';
+import { ResolverBase } from '@memberjunction/server';
 
-// In your server initialization
-const scheduler = LearningCycleScheduler.Instance;
-scheduler.setDataSources(dataSources);
-scheduler.start(60); // Run every 60 minutes
+@Resolver()
+export class MyResolver extends ResolverBase {
+  @Mutation(() => MyResult)
+  async myOperation(@Ctx() ctx: AppContext): Promise<MyResult> {
+    // Checks scope for API key auth; no-op for JWT auth
+    await this.CheckAPIKeyScopeAuthorization('my:scope', 'resource-name', ctx.userPayload);
+    // Proceed with operation...
+  }
+}
 ```
 
-### AI Resolvers
-
-The server includes comprehensive AI resolvers for various AI operations:
-
-#### RunAIPromptResolver
-Handles AI prompt execution with multiple methods:
+Alternatively, use the standalone utility functions:
 
-- `RunAIPrompt`: Execute stored AI prompts with full parameter support
-  - Supports temperature, topP, topK, and other model parameters
-  - Handles conversation messages and system prompt overrides
-  - Returns parsed results, token usage, and execution metadata
-
-- `ExecuteSimplePrompt`: Execute ad-hoc prompts without stored configuration
-  - Direct system prompt and message execution
-  - Smart model selection based on preferences or power level
-  - Automatic JSON extraction from responses
-  - Available for both regular users and system users
-
-- `EmbedText`: Generate text embeddings using local models
-  - Batch processing support for multiple texts
-  - Model size selection (small/medium)
-  - Returns vector dimensions and model information
-  - Available for both regular users and system users
-
-#### RunAIAgentResolver
-- `RunAIAgent`: Execute AI agents for conversational interactions
-  - Session management for conversation context
-  - Streaming support for real-time responses
-  - Progress tracking and partial results
-  - Available for both regular users and system users
-
-#### System User Variants
-All AI operations have system user variants (queries) that use the `@RequireSystemUser` decorator:
-- `RunAIPromptSystemUser`
-- `ExecuteSimplePromptSystemUser`
-- `EmbedTextSystemUser`
-- `RunAIAgentSystemUser`
-
-These allow server-to-server operations with elevated privileges.
-
-#### AskSkipResolver
-- `AskSkipResolver`: Handle Skip AI queries
-
-### SQL Logging Resolver
+```typescript
+import { CheckAPIKeyScope, RequireScope } from '@memberjunction/server';
 
-- `SqlLoggingConfigResolver`: Manage SQL logging configuration and sessions
+// Standalone function
+await CheckAPIKeyScope(ctx.userPayload.apiKeyId, 'view:run', ctx.userPayload.userRecord, {
+  resource: 'Users',
+});
 
-## SQL Logging Management
+// Pre-built scope checker
+const requireViewRun = RequireScope('view:run');
+await requireViewRun(ctx);
+```
 
-The server includes a comprehensive SQL logging management system that allows Owner-level users to control SQL statement capture in real-time.
+## GraphQL API
 
-### Key Features
+### Custom Directives
 
-- **Owner-only Access**: SQL logging requires `Type = 'Owner'` privileges
-- **Session Management**: Create, monitor, and stop multiple concurrent logging sessions
-- **User Filtering**: Capture SQL statements from specific users only
-- **Multiple Formats**: Standard SQL logs or migration-ready files
-- **Real-time Control**: Start/stop sessions via GraphQL API
-- **Automatic Cleanup**: Sessions auto-expire and clean up empty files
+- **`@RequireSystemUser`**: Restricts a field or mutation to system-user-only access. Applied at the schema level; non-system users receive an `AuthorizationError`.
+- **`@Public`**: Marks a field as publicly accessible without authentication. All other fields require an active, authenticated user by default.
+
+### Built-in Resolvers
+
+The server includes resolvers for the following domains:
+
+| Resolver | Operations |
+|----------|------------|
+| `EntityResolver` | CRUD operations for all entities |
+| `RunViewResolver` | RunView by ID, name, or dynamic entity |
+| `RunAIPromptResolver` | Execute AI prompts, simple prompts, text embeddings |
+| `RunAIAgentResolver` | Execute AI agents with session and streaming support |
+| `ActionResolver` | Execute MJ Actions |
+| `QueryResolver` | Execute and create queries |
+| `ReportResolver` | Run and manage reports |
+| `DatasetResolver` | Dataset operations |
+| `UserViewResolver` | User view management |
+| `UserResolver` | User profile operations |
+| `UserFavoriteResolver` | Favorite record management |
+| `MergeRecordsResolver` | Record merge operations |
+| `SyncDataResolver` / `SyncRolesUsersResolver` | Data synchronization |
+| `FileResolver` / `FileCategoryResolver` | File and category management |
+| `EntityCommunicationsResolver` | Entity-level communications |
+| `EntityRecordNameResolver` | Record name resolution |
+| `TransactionGroupResolver` | Transaction group management |
+| `ComponentRegistryResolver` | Component registry queries |
+| `MCPResolver` | MCP server operations |
+| `APIKeyResolver` | API key management |
+| `SqlLoggingConfigResolver` | SQL logging session management |
+| `TelemetryResolver` | Server telemetry queries |
+| `ColorResolver` | Color palette operations |
+| `InfoResolver` | Server info queries |
+| `PotentialDuplicateRecordResolver` | Duplicate detection |
+| `RunTestResolver` | Test execution |
+| `RunTemplateResolver` | Template execution |
+| `TaskResolver` | Task orchestration |
 
-### GraphQL Operations
+### Transaction Management
 
-#### Query Configuration
+GraphQL mutations are automatically wrapped in transactions through the per-request provider:
 
 ```graphql
-query {
-  sqlLoggingConfig {
-    enabled
-    activeSessionCount
-    maxActiveSessions
-    allowedLogDirectory
-    sessionTimeout
-    defaultOptions {
-      prettyPrint
-      statementTypes
-      formatAsMigration
-      logRecordChangeMetadata
-    }
-  }
+mutation {
+  CreateUser(input: { FirstName: "John", LastName: "Doe" }) { ID }
+  CreateUserRole(input: { UserID: "...", RoleID: "..." }) { ID }
 }
+# Both operations execute within the same provider's transaction scope.
+# Success: both committed together. Error: both rolled back.
 ```
 
-#### List Active Sessions
+### WebSocket Subscriptions
 
-```graphql
-query {
-  activeSqlLoggingSessions {
-    id
-    sessionName
-    filePath
-    startTime
-    statementCount
-    filterByUserId
-    options {
-      prettyPrint
-      statementTypes
-      formatAsMigration
-    }
-  }
-}
+Real-time updates are supported via WebSocket at the same path as the GraphQL endpoint:
+
+```typescript
+// Server-side: already configured
+const webSocketServer = new WebSocketServer({
+  server: httpServer,
+  path: graphqlRootPath,
+});
 ```
 
-#### Start a New Session
+### ResolverBase
+
+All built-in resolvers extend `ResolverBase`, which provides:
+
+| Method | Description |
+|--------|-------------|
+| `CreateRecord()` | Create entity with before/after hooks |
+| `UpdateRecord()` | Update with optimistic concurrency detection |
+| `DeleteRecord()` | Delete with before/after hooks |
+| `RunViewByIDGeneric()` | Execute a saved view by ID |
+| `RunViewByNameGeneric()` | Execute a saved view by name |
+| `RunDynamicViewGeneric()` | Execute an ad-hoc view on an entity |
+| `RunViewsGeneric()` | Batch-execute multiple views |
+| `CheckUserReadPermissions()` | Validate entity-level read access |
+| `CheckAPIKeyScopeAuthorization()` | Validate API key scope |
+| `MapFieldNamesToCodeNames()` | Map field names for GraphQL transport |
+| `FilterEncryptedFieldsForAPI()` | Handle encryption policy for API responses |
+| `EmitCloudEvent()` | Emit CloudEvents for entity lifecycle |
+| `ListenForEntityMessages()` | Subscribe to entity event messages |
+| `BeforeCreate()` / `AfterCreate()` | Lifecycle hooks for create |
+| `BeforeUpdate()` / `AfterUpdate()` | Lifecycle hooks for update |
+| `BeforeDelete()` / `AfterDelete()` | Lifecycle hooks for delete |
+
+## REST API
+
+In addition to GraphQL, MJServer provides a REST API at `/api/v1/`. By default it is disabled and can be enabled via configuration.
+
+For comprehensive REST API documentation including endpoints, security configuration, wildcard filtering, and examples, see [REST_API.md](./REST_API.md).
+
+Key endpoints:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/v1/entities/:entityName` | GET | List entity records |
+| `/api/v1/entities/:entityName` | POST | Create a record |
+| `/api/v1/entities/:entityName/:id` | GET | Get a record by ID |
+| `/api/v1/entities/:entityName/:id` | PUT | Update a record |
+| `/api/v1/entities/:entityName/:id` | DELETE | Delete a record |
+| `/api/v1/views/:entityName` | POST | Run a view |
+| `/api/v1/views/batch` | POST | Batch view execution |
+| `/api/v1/metadata/entities` | GET | List entity metadata |
+| `/api/v1/users/current` | GET | Get current user |
+
+## SQL Logging
+
+The server includes a runtime SQL logging system for debugging and migration generation. Requires `Owner`-level user privileges.
 
 ```graphql
+# Start a logging session
 mutation {
   startSqlLogging(input: {
     fileName: "debug-session.sql"
@@ -453,264 +530,363 @@ mutation {
     id
     filePath
     sessionName
-    startTime
   }
 }
-```
 
-#### Stop Sessions
-
-```graphql
-# Stop specific session
-mutation {
-  stopSqlLogging(sessionId: "session-id-here")
+# Query active sessions
+query {
+  activeSqlLoggingSessions {
+    id
+    sessionName
+    statementCount
+  }
 }
 
-# Stop all sessions
+# Stop a session
 mutation {
-  stopAllSqlLogging
+  stopSqlLogging(sessionId: "session-id")
 }
 ```
 
-### Security Requirements
-
-All SQL logging operations require:
-1. **Authentication**: Valid user session or API key
-2. **Authorization**: User must have `Type = 'Owner'` in the Users table
-3. **Configuration**: SQL logging must be enabled in server config
-
-### Configuration
-
-SQL logging is configured in `mj.config.cjs`:
+Configuration in `mj.config.cjs`:
 
 ```javascript
 sqlLogging: {
-  enabled: true,  // Master switch
+  enabled: true,
   allowedLogDirectory: './logs/sql',
   maxActiveSessions: 5,
-  sessionTimeout: 3600000, // 1 hour
+  sessionTimeout: 3600000,
   autoCleanupEmptyFiles: true,
   defaultOptions: {
     formatAsMigration: false,
-    statementTypes: 'both',
+    statementTypes: 'both',  // 'queries' | 'mutations' | 'both'
     prettyPrint: true,
     logRecordChangeMetadata: false,
-    retainEmptyLogFiles: false
-  }
+  },
 }
 ```
 
-## Security Configuration
-
-### Authentication Providers
-
-The server supports multiple authentication providers:
-
-1. **Azure AD (MSAL)**:
-   - Set `TENANT_ID` and `WEB_CLIENT_ID` environment variables
-   - Supports Microsoft identity platform
+## Scheduled Jobs
+
+MJServer integrates with the `@memberjunction/scheduling-engine` to execute scheduled jobs defined in MemberJunction metadata.
+
+```mermaid
+flowchart LR
+    subgraph Config["Configuration"]
+        CFG[mj.config.cjs]
+    end
+
+    subgraph Service["ScheduledJobsService"]
+        INIT[Initialize]
+        POLL[Start Polling]
+        STOP[Stop Polling]
+    end
+
+    subgraph Engine["SchedulingEngine"]
+        JOBS[Active Jobs]
+        EXEC[Job Execution]
+        LOCK[Lock Management]
+    end
+
+    CFG --> INIT
+    INIT --> POLL
+    POLL --> JOBS
+    JOBS --> EXEC
+    EXEC --> LOCK
+
+    style Config fill:#b8762f,stroke:#8a5722,color:#fff
+    style Service fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style Engine fill:#2d8659,stroke:#1a5c3a,color:#fff
+```
 
-2. **Auth0**:
-   - Set `AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, and `AUTH0_CLIENT_SECRET`
-   - Supports Auth0 authentication
+Configuration:
 
-### API Key Authentication
+```javascript
+scheduledJobs: {
+  enabled: true,
+  systemUserEmail: 'system@example.com',
+  maxConcurrentJobs: 5,
+  defaultLockTimeout: 600000,    // 10 minutes
+  staleLockCleanupInterval: 300000, // 5 minutes
+}
+```
 
-The server supports two types of API key authentication:
+The service starts automatically during server initialization and shuts down gracefully on SIGTERM/SIGINT.
 
-#### User API Keys (`X-API-Key` header)
+## AI Integration
 
-Per-user API keys that authenticate as a specific user. These follow the `mj_sk_*` format and are created via the EncryptionEngine:
+### AI Prompt Execution
 
-```typescript
-import { EncryptionEngine } from '@memberjunction/encryption';
-
-// Create a new API key for a user
-const result = await EncryptionEngine.Instance.CreateAPIKey({
-    userId: 'user-guid-here',
-    label: 'My Integration',
-    description: 'API key for external integration',
-    expiresAt: new Date('2025-12-31') // Optional
-}, contextUser);
-
-if (result.success) {
-    console.log('API Key:', result.rawKey); // Save this - cannot be recovered!
+```graphql
+mutation {
+  RunAIPrompt(input: {
+    PromptName: "Summarize Content"
+    ModelID: "model-guid"
+    Temperature: 0.7
+    Messages: [{ role: "user", content: "Summarize this article..." }]
+  }) {
+    Success
+    Result
+    TokenUsage { InputTokens OutputTokens }
+  }
 }
 ```
 
-Usage:
-```bash
-curl -H "X-API-Key: mj_sk_abc123..." https://api.example.com/graphql
+### Simple Prompt Execution
+
+```graphql
+mutation {
+  ExecuteSimplePrompt(input: {
+    SystemPrompt: "You are a helpful assistant."
+    UserMessage: "What is MemberJunction?"
+    ModelPowerLevel: "Standard"
+  }) {
+    Success
+    Result
+  }
+}
 ```
 
-Features:
-- Authenticates as the specific user who owns the key
-- Supports expiration dates
-- Can be revoked individually
-- Usage is logged for audit purposes
-- `apiKeyId` is included in the request context
+### Text Embeddings
 
-#### System API Key (`x-mj-api-key` header)
+```graphql
+mutation {
+  EmbedText(input: {
+    Texts: ["Hello world", "MemberJunction framework"]
+    ModelSize: "small"
+  }) {
+    Success
+    Embeddings
+    Dimensions
+    Model
+  }
+}
+```
 
-A single shared API key for system-level operations, configured via the `MJ_API_KEY` environment variable:
+### AI Agent Execution
 
-```bash
-curl -H "x-mj-api-key: your-system-key" https://api.example.com/graphql
+```graphql
+mutation {
+  RunAIAgent(input: {
+    AgentID: "agent-guid"
+    SessionID: "session-guid"
+    UserMessage: "Find all active users"
+  }) {
+    Success
+    Result
+    SessionID
+  }
+}
 ```
 
-Features:
-- Authenticates as the system user
-- Used for server-to-server communication
-- Has elevated privileges for system operations
-- `isSystemUser: true` is set in the request context
-
-### Scope-Based Authorization
+All AI operations have system-user variants (e.g., `RunAIPromptSystemUser`) that use the `@RequireSystemUser` directive for server-to-server operations.
 
-API keys are subject to scope-based authorization, which controls what operations each key can perform. This is implemented in `ResolverBase.CheckAPIKeyScopeAuthorization()`.
+## API Reference
 
-#### How It Works
+### Core Exports
 
-1. **Application Ceiling**: Each API application (GraphQL API, MCP Server, A2A Server) defines maximum allowed scopes
-2. **API Key Scopes**: Each API key has assigned scopes from the `MJ: API Scopes` entity
-3. **Two-Level Evaluation**: Authorization succeeds only if both application ceiling AND API key scopes permit the operation
+#### Server Functions
 
-#### Available Scopes
+| Export | Description |
+|--------|-------------|
+| `serve(resolverPaths, app?, options?)` | Main server initialization function |
+| `createApp()` | Creates a new Express application instance |
 
-| Scope | Description |
-|-------|-------------|
-| `full_access` | Bypass all scope checks ("god mode") |
-| `entity:read` | Read entity records |
-| `entity:create` | Create new records |
-| `entity:update` | Update existing records |
-| `entity:delete` | Delete records |
-| `view:run` | Execute RunView queries |
-| `agent:execute` | Execute AI agents |
-| `agent:monitor` | Check agent run status |
-| `action:execute` | Execute MJ Actions |
-| `prompt:execute` | Execute AI prompts |
-| `query:run` | Execute queries |
-| `metadata:entities:read` | Read entity metadata |
-| `metadata:agents:read` | Read agent metadata |
-| `communication:send` | Send emails/messages |
+#### Types
 
-#### Default Behavior
+| Export | Description |
+|--------|-------------|
+| `AppContext` | GraphQL resolver context type |
+| `UserPayload` | Authenticated user payload |
+| `DataSourceInfo` | Database connection descriptor |
+| `ProviderInfo` | Per-request provider descriptor |
+| `MJServerOptions` | Options for `serve()` |
+| `ConfigInfo` | Full server configuration type |
+| `MJServerEvent` | Server lifecycle event type |
 
-**Important**: API keys with **no scopes assigned** will have **no permissions** and all requests will be denied (except for OAuth/JWT authenticated users which bypass scope checks).
+#### Authentication
 
-#### Adding Scope Checks to Custom Resolvers
+| Export | Description |
+|--------|-------------|
+| `IAuthProvider` | Authentication provider interface |
+| `AuthProviderFactory` | Provider registry and factory |
+| `NewUserBase` | Base class for custom new user handling |
+| `TokenExpiredError` | Token expiration error class |
+| `getSystemUser(dataSource?)` | Retrieve the system user |
+| `getSigningKeys(issuer)` | Get JWT signing keys for an issuer |
+| `extractUserInfoFromPayload(payload)` | Extract user info from JWT claims |
+| `verifyUserRecord(email, ...)` | Verify and optionally create a user record |
+
+#### Scope Authorization
+
+| Export | Description |
+|--------|-------------|
+| `CheckAPIKeyScope(apiKeyId, scopePath, contextUser, options?)` | Check API key scope |
+| `CheckAPIKeyScopeAndLog(apiKeyId, scopePath, contextUser, usageDetails, options?)` | Check scope with usage logging |
+| `RequireScope(scopePath, options?)` | Create a reusable scope checker |
+| `RequireViewRun` | Pre-built scope checker for `view:run` |
+| `RequireQueryRun` | Pre-built scope checker for `query:run` |
+| `RequireAgentExecute` | Pre-built scope checker for `agent:execute` |
+
+#### Resolver Base Classes
+
+| Export | Description |
+|--------|-------------|
+| `ResolverBase` | Base class for all resolvers |
+| `RunViewResolver` | Base resolver for view operations |
+| `PushStatusResolver` | Status update resolver with pub/sub |
 
-Custom resolvers should extend `ResolverBase` and call `CheckAPIKeyScopeAuthorization()`:
+#### Utility Functions
 
-```typescript
-import { ResolverBase } from '@memberjunction/server';
+| Export | Description |
+|--------|-------------|
+| `GetReadOnlyDataSource(dataSources, options?)` | Get read-only connection pool |
+| `GetReadWriteDataSource(dataSources)` | Get read-write connection pool |
+| `GetReadOnlyProvider(providers, options?)` | Get read-only provider instance |
+| `GetReadWriteProvider(providers, options?)` | Get read-write provider instance |
 
-@Resolver()
-export class MyResolver extends ResolverBase {
-    @Mutation(() => MyResult)
-    async myOperation(
-        @Ctx() ctx: AppContext
-    ): Promise<MyResult> {
-        // Check scope authorization for API keys
-        await this.CheckAPIKeyScopeAuthorization('my:scope', 'resource-name', ctx.userPayload);
-
-        // Proceed with operation...
-    }
-}
-```
+#### GraphQL Inputs
 
-The method:
-- Returns immediately for OAuth/JWT users (no scope restrictions)
-- Validates API key scopes against application ceiling and key scopes
-- Throws `AuthorizationError` with detailed message on failure
+| Export | Description |
+|--------|-------------|
+| `KeyValuePairInput` | Generic key-value input type |
+| `DeleteOptionsInput` | Delete operation options |
 
-### Access Control
+#### Directives
 
-For REST API access control, see the comprehensive documentation in [REST_API.md](./REST_API.md).
+| Export | Description |
+|--------|-------------|
+| `RequireSystemUser` | Decorator restricting access to system users |
+| `Public` | Decorator marking endpoints as publicly accessible |
+| `configInfo` | Parsed server configuration singleton |
+| `DEFAULT_SERVER_CONFIG` | Default configuration values |
 
-## Performance Optimization
+## Performance
 
-### Compression
+### Response Compression
 
-The server includes built-in compression middleware:
-- Responses larger than 1KB are compressed
-- Binary files are excluded from compression
-- Uses compression level 6 for optimal balance
+Responses larger than 1KB are automatically compressed using gzip at compression level 6. Binary content types (images, video, audio) are excluded.
 
 ### Connection Pooling
 
-Database connections are managed with TypeORM's connection pooling. Configure pool size in your TypeORM configuration.
+Database connections are managed via `mssql` connection pools. Configure pool size in `databaseSettings.connectionPool`:
 
-### Caching
+```javascript
+connectionPool: {
+  max: 50,      // Maximum connections
+  min: 5,       // Minimum connections
+  idleTimeoutMillis: 30000,
+  acquireTimeoutMillis: 30000,
+}
+```
 
-The server uses LRU caching for frequently accessed data. Configure cache settings in your `mj.config.cjs`:
+**Recommended settings:**
+- Development: `max: 10, min: 2`
+- Production: `max: 50, min: 5`
+- High load: `max: 100, min: 10`
+
+### Metadata Caching
+
+Entity metadata is loaded once at startup and shared across all per-request provider instances. The cache refresh interval is configurable:
 
 ```javascript
 databaseSettings: {
-  metadataCacheRefreshInterval: 300000 // 5 minutes
+  metadataCacheRefreshInterval: 180000,  // 3 minutes
 }
 ```
 
-## Advanced Configuration
+### Authentication Token Caching
 
-### Custom Directives
+Validated JWT tokens are cached using an LRU cache, avoiding repeated cryptographic verification for the same token within its lifetime.
 
-The server includes custom GraphQL directives:
-- `@RequireSystemUser`: Requires system user permissions
-- `@Public`: Makes endpoints publicly accessible
+## Graceful Shutdown
 
-### SQL Logging Integration
+The server registers handlers for `SIGTERM` and `SIGINT` to:
 
-The server integrates with the SQLServerDataProvider's logging capabilities:
-- Session management through GraphQL resolvers
-- Owner-level access control validation
-- Real-time session monitoring and control
-- Integration with MemberJunction Explorer UI
+1. Stop the scheduled jobs service
+2. Close the HTTP server
+3. Force-exit after a 10-second timeout if graceful shutdown stalls
 
-### WebSocket Configuration
+Unhandled promise rejections are caught and logged without crashing the server.
 
-For real-time subscriptions:
+## Dependencies
 
-```typescript
-const webSocketServer = new WebSocketServer({ 
-  server: httpServer, 
-  path: graphqlRootPath 
-});
-```
+### Core MemberJunction Packages
+
+| Package | Purpose |
+|---------|---------|
+| [@memberjunction/core](../MJCore/README.md) | Core metadata, entities, RunView |
+| [@memberjunction/core-entities](../MJCoreEntities/README.md) | Generated entity classes |
+| [@memberjunction/global](../MJGlobal/README.md) | ClassFactory, event system |
+| [@memberjunction/sqlserver-dataprovider](../SQLServerDataProvider/README.md) | SQL Server data provider |
+| [@memberjunction/graphql-dataprovider](../GraphQLDataProvider/README.md) | GraphQL field mapping |
+| [@memberjunction/config](../Config/README.md) | Configuration utilities |
+| [@memberjunction/api-keys](../APIKeys/README.md) | API key engine and scope evaluation |
+| [@memberjunction/encryption](../Encryption/README.md) | Field-level encryption engine |
+
+### AI Packages
+
+| Package | Purpose |
+|---------|---------|
+| [@memberjunction/ai](../AI/README.md) | AI engine abstraction |
+| [@memberjunction/ai-prompts](../AI/Prompts/README.md) | AI prompt execution |
+| [@memberjunction/ai-agents](../AI/Agents/README.md) | AI agent framework |
+| [@memberjunction/ai-core-plus](../AI/CorePlus/README.md) | AI prompt parameters |
+| [@memberjunction/aiengine](../AIEngine/README.md) | AI engine orchestration |
+| [@memberjunction/ai-provider-bundle](../AI/ProviderBundle/README.md) | Bundled AI providers |
+
+### Infrastructure Packages
+
+| Package | Purpose |
+|---------|---------|
+| [@memberjunction/scheduling-engine](../SchedulingEngine/README.md) | Scheduled job execution |
+| [@memberjunction/actions](../Actions/README.md) | Action framework |
+| [@memberjunction/templates](../Templates/README.md) | Template engine |
+| [@memberjunction/notifications](../Notifications/README.md) | Notification system |
+| [@memberjunction/storage](../Storage/README.md) | File storage |
+| [@memberjunction/communication-ms-graph](../Communication/providers/MSGraphProvider/README.md) | MS Graph communications |
+| [@memberjunction/communication-sendgrid](../Communication/providers/SendGridProvider/README.md) | SendGrid communications |
+
+### Third-Party Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `@apollo/server` | GraphQL server |
+| `express` | HTTP framework |
+| `type-graphql` | TypeScript GraphQL decorators |
+| `mssql` | SQL Server client |
+| `jsonwebtoken` / `jwks-rsa` | JWT verification |
+| `graphql-ws` / `ws` | WebSocket subscriptions |
+| `compression` | Response compression |
+| `cosmiconfig` | Configuration file discovery |
+| `cloudevents` | CloudEvent emission |
+| `zod` | Configuration schema validation |
+
+## Related Packages
+
+- [@memberjunction/server-bootstrap](../ServerBootstrap/README.md) -- Pre-built class registration manifest for tree-shaking prevention
+- [MJAPI](../../MJAPI/README.md) -- Reference server application that consumes this package
+- [@memberjunction/core](../MJCore/README.md) -- Core framework that MJServer exposes via API
 
 ## Troubleshooting
 
-### Common Issues
+| Issue | Solution |
+|-------|----------|
+| Authentication errors | Verify environment variables for your auth provider are set |
+| Database connection failures | Check `DB_HOST`, `DB_PORT`, `DB_USERNAME`, `DB_PASSWORD` |
+| No resolvers found | Verify resolver paths passed to `serve()` are absolute and use correct glob patterns |
+| Transaction errors | Review mutation logic; check that entity operations are within the per-request provider |
+| SQL logging access denied | Ensure user has `Type = 'Owner'` in the Users table |
+| Metadata not loading | Check `MJ_CORE_SCHEMA` matches your database schema name |
+| Token expired errors | Expected behavior for long-lived sessions; client should refresh tokens |
 
-1. **Authentication Errors**: Ensure all required environment variables are set
-2. **Database Connection**: Verify connection string and credentials
-3. **Module Loading**: Check resolver paths are correct and accessible
-4. **Transaction Errors**: Review mutation logic for proper error handling
-5. **SQL Logging Access**: Ensure user has Owner privileges and logging is enabled in config
+Enable verbose logging:
 
-### Debug Mode
-
-Enable detailed logging by setting environment variables:
-```shell
+```bash
 DEBUG=mj:*
 NODE_ENV=development
 ```
 
-## Best Practices
-
-1. **Use Read-Only Connections**: Configure read-only database connections for query operations
-2. **Implement Custom User Handling**: Extend `NewUserBase` for organization-specific user creation
-3. **Monitor Performance**: Use the built-in timing logs for transaction monitoring
-4. **Secure Your REST API**: Always configure entity and schema filters for production
-5. **Handle Errors Gracefully**: Implement proper error handling in custom resolvers
-
 ## Contributing
 
-When contributing to this package:
-1. Follow the existing code style and patterns
-2. Add appropriate TypeScript types
-3. Include tests for new functionality
-4. Update documentation as needed
-
-## License
-
-ISC
+See the [MemberJunction Contributing Guide](../../CONTRIBUTING.md) for development setup and guidelines.