# KernDX - Developer Documentation

This page is the map to everything you can read about KernDX. It is for anyone building on the framework, whether you are a brand-new Salesforce developer looking for a quick task guide or an architect comparing design choices. Skim the [Learning Paths](#learning-paths) if you are starting out, jump to a [Fast Start](#fast-starts) when you have a specific task, or open a full [Guide](#guides) when you want the complete picture.

> **Namespaces in code samples:** `kern.` on a class and `kern__` on an object, field, or metadata type mark the managed package's namespace.
> On the managed package, framework references need those prefixes even where a sample omits them; repackaged under your own namespace, replace `kern`/`kern__`
> with your prefix; on an unmanaged deploy, drop them. See [How to read the code samples](/installation#how-to-read-the-code-samples).

> **Using an AI coding assistant?** Load [`docs/AI Agent Instructions.md`](/ai-agent-instructions)
> into it before generating KernDX code. That one file is the assistant's complete context for writing
> selectors, triggers, callouts, LWC, and tests the KernDX way. It's already in this repo and release; see
> its header for exactly how to wire it into your tool.

## Table of Contents

<details>
<summary>Expand</summary>

1. [Before You Begin](#before-you-begin)
2. [Learning Paths](#learning-paths)
3. [Fast Starts](#fast-starts)
    - [Data Access](#data-access)
    - [Triggers & Validation](#triggers-validation)
    - [Web Services](#web-services)
    - [Operations](#operations)
    - [Security](#security)
    - [User Interface](#user-interface)
    - [Code Quality](#code-quality)
    - [Testing](#testing)
4. [Guides](#guides)
    - [Core Frameworks](#core-frameworks)
    - [Data & Security](#data-security)
    - [UI](#ui)
    - [Utilities](#utilities)
    - [Code Quality](#code-quality-1)
    - [Testing](#testing-1)
5. [API Reference](#api-reference)
6. [Special Documents](#special-documents)
    - [Strategic Guide (9 documents)](#strategic-guide-9-documents)
7. [Choosing the Right Document](#choosing-the-right-document)

</details>

---

## Before You Begin

Verify these prerequisites before starting any Fast Start guide:

- [ ] **Salesforce org access**: a developer or sandbox org with admin permissions
- [ ] **Salesforce DX**: the `sf` CLI installed and authenticated to your org
- [ ] **KernDX deployed**: the KernDX managed package installed
- [ ] **API version 68.0**: org and project metadata aligned to API 68.0
- [ ] **Custom Metadata access**: permission to create and edit Custom Metadata Type records

---

## Learning Paths

Choose the path that matches your project needs:

**Data Layer Path**
> [Selectors](/fast-start-selectors) → [DML](/fast-start-dml) → [Security](/fast-start-security) → [Data Masking](/fast-start-data-masking) → [Test Data](/fast-start-test-data)

**Automation Path**
> [Trigger Actions](/fast-start-trigger-actions) → [Custom Validations](/fast-start-custom-validations) → [Async Processing](/fast-start-async-processing) → [Logging](/fast-start-logging)

**Integration Path**
> [Outbound APIs](/fast-start-outbound-apis) → [Resilience](/fast-start-resilience) → [Inbound APIs](/fast-start-inbound-apis) → [Async Chains](/fast-start-async-processing) → [Feature Flags](/fast-start-feature-flags) → [Logging](/fast-start-logging)

**Testing Path**
> [Test Data](/fast-start-test-data) → [E2E Testing](/fast-start-e2e-testing)

**Quality Path**
> [Code Scanning](/fast-start-code-scanning) → [Logging](/fast-start-logging) → [E2E Testing](/fast-start-e2e-testing)

**UI Path**
> [LWC](/fast-start-lwc) → [E2E Testing](/fast-start-e2e-testing)

---

## Fast Starts

Have a specific task in mind? These short, focused guides walk you through one job at a time so you can build it quickly.

### Data Access

| Name                                           | Description                                  | Key Reference                                                                                |
|------------------------------------------------|----------------------------------------------|--------------------------------------------------------------------------------------------|
| [Selectors](/fast-start-selectors)   | Build object selectors and fluent queries    | [SEL_Base](/reference/apex/sel-base), [QRY_Builder](/reference/apex/qry-builder)       |
| [DML](/fast-start-dml)               | Insert, update, delete with Unit of Work     | [DML_Builder](/reference/apex/dml-builder)                                               |
| [Test Data](/fast-start-test-data) | Create test data with builders and factories | [TST_Builder](/reference/apex/tst-builder), [TST_Factory](/reference/apex/tst-factory) |

### Triggers & Validation

| Name                                                             | Description                           | Key Reference                                                                                                                                |
|------------------------------------------------------------------|---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
| [Trigger Actions](/fast-start-trigger-actions)       | Build metadata-driven trigger actions | [TRG_Dispatcher](/reference/apex/trg-dispatcher), [TRG_Base](/reference/apex/trg-base), [IF_Trigger](/reference/apex/if-trigger)     |
| [Custom Validations](/fast-start-custom-validations) | Build formula-driven validation rules | [UTIL_ValidationRule](/reference/apex/util-validationrule), [FLOW_ExecuteValidationRules](/reference/apex/flow-executevalidationrules) |

### Web Services

| Name                                                   | Description                                | Key Reference                                                                                                                                          |
|--------------------------------------------------------|--------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Outbound APIs](/fast-start-outbound-apis) | Call external REST APIs                    | [API_Outbound](/reference/apex/api-outbound), [DTO_JsonBase](/reference/apex/dto-jsonbase), [UTIL_HttpClient](/reference/apex/util-httpclient) |
| [Inbound APIs](/fast-start-inbound-apis)   | Expose REST endpoints for external callers | [API_Inbound](/reference/apex/api-inbound), [API_Dispatcher](/reference/apex/api-dispatcher)                                                     |
| [Resilience](/fast-start-resilience)         | Retry, backoff, and circuit breaker for flaky callouts | [UTIL_HttpClient](/reference/apex/util-httpclient), [UTIL_Retry](/reference/apex/util-retry), [UTIL_CircuitBreaker](/reference/apex/util-circuitbreaker) |

### Operations

| Name                                                         | Description                                                              | Key Reference                                                                                                                                      |
|--------------------------------------------------------------|--------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| [Async Processing](/fast-start-async-processing) | Adaptive async jobs and chain orchestration with shared context          | [IF_Async](/reference/apex/if-async), [UTIL_AsyncChain](/reference/apex/util-asyncchain)                                                     |
| [Scheduled Jobs](/fast-start-scheduled-jobs)     | Schedule a class with a record, and run many jobs on the job runner      | [SCHED_Base](/reference/apex/sched-base), [IF_Schedulable](/reference/apex/if-schedulable)                                                   |
| [Logging](/fast-start-logging)                     | Application logging and monitoring                                       | [LOG_Builder](/reference/apex/log-builder)                                                                                                     |
| [Feature Flags](/fast-start-feature-flags)       | Metadata-driven feature toggles                                          | [UTIL_FeatureFlag](/reference/apex/util-featureflag)                                                                                           |

### Security

| Name                                         | Description                                  | Key Reference                                                                          |
|----------------------------------------------|----------------------------------------------|--------------------------------------------------------------------------------------|
| [Security](/fast-start-security)   | Queries and DML that run with the user's own permissions and sharing by default (USER_MODE) | [QRY_Builder](/reference/apex/qry-builder), [DML_Builder](/reference/apex/dml-builder) |
| [Data Masking](/fast-start-data-masking) | Redact cards, secrets, and PII on records before they save | [MaskingTarget__mdt](/reference/metadata/maskingtarget-mdt), [UTIL_FeatureFlag](/reference/apex/util-featureflag) |

### User Interface

| Name                                | Description                                                         | Key Reference                       |
|-------------------------------------|---------------------------------------------------------------------|-----------------------------------|
| [LWC](/fast-start-lwc)    | Build Lightning Web Components on the ComponentBuilder base class    | [LWC - Guide](/lwc-guide) |

### Code Quality

| Name                                                   | Description                                                          | Key Reference |
|--------------------------------------------------------|----------------------------------------------------------------------|-------------|
| [Code Scanning](/fast-start-code-scanning) | PMD and ESLint enforcement of framework conventions in IDE and CI/CD | [Code Scanning - Guide](/code-scanning-guide)           |

### Testing

| Name                                               | Description                                             | Key Reference |
|----------------------------------------------------|---------------------------------------------------------|-------------|
| [E2E Testing](/fast-start-e2e-testing) | Browser-based Playwright tests for Salesforce Lightning | [E2E Testing - Guide](/e2e-testing-guide)           |

---

## Guides

In-depth reference guides. Open one of these when you want the complete picture of a framework area: what it can do, the patterns behind it, and the recommended way to use it.

### Core Frameworks

| Name                                                          | Description                                                                                                                  |
|---------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
| [Selectors - Guide](/selectors-guide)                 | Layered query architecture, QRY_Builder, sharing enforcement, caching, pagination                                            |
| [Triggers - Guide](/triggers-guide)                   | Metadata-driven trigger actions, bypass mechanisms, entry criteria, recursion prevention                                     |
| [Validation - Guide](/validation-guide)               | Formula-driven validation, bypass hierarchy, shadow mode, Flow integration                                                   |
| [DML - Guide](/dml-guide)                             | Unit of Work, bulk DML, sharing enforcement, CRUD/FLS, data purge                                                            |
| [Async Processing - Guide](/async-processing-guide) | Adaptive async processing, chain orchestration with shared context, ApiStep web service bridge, Chain Monitor UI, scheduling |
| [Web Services - Guide](/web-services-guide)         | Outbound/inbound REST, named credentials, retry logic, Flow integration                                                      |
| [Resilience - Guide](/resilience-guide)               | Retry strategies, exponential/linear backoff, jitter, circuit breaker states, declarative resilience on registered handlers  |
| [Logging - Guide](/logging-guide)                     | Application logging, async log publishing, log filtering, and the Log Console for browsing and diagnosing what was logged                                                         |
| [Feature Flags - Guide](/feature-flags-guide)       | Metadata-driven flags, targeting strategies, custom strategy handlers, Apex/Flow/LWC checks                                  |

### Data & Security

| Name                                                                  | Description                                                                        |
|-----------------------------------------------------------------------|------------------------------------------------------------------------------------|
| [Data Masking - Guide](/data-masking-guide)                 | Write-time field redaction, masking rules and targets, the Data Masking Advisor    |
| [DTOs - Guide](/dtos-guide)                                   | JSON serialisation, SObject transformation, populate/transform patterns, JsonPath  |
| [Security - Guide](/security-guide)                           | CRUD/FLS enforcement, sharing control, encryption                                  |
| [Objects & Metadata - Guide](/objects-metadata-guide) | Custom objects, platform events, and custom metadata types included in the package |

### UI

| Name                                                                    | Description                                                                                                              |
|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| [LWC - Guide](/lwc-guide)                                       | ComponentBuilder pattern, utility modules, pre-built components, Jest testing                                             |
| [Administration Tools - Guide](/administration-tools-guide)   | Kern Home and the built-in tools: API Test Harness, Streaming Event Monitor, Chain Monitor, Data Masking Advisor, Log Console |

### Utilities

| Name                                          | Description                                                                                       |
|-----------------------------------------------|---------------------------------------------------------------------------------------------------|
| [Utilities - Guide](/utilities-guide) | String, date, number, collection utilities, type resolution, random data, feature flags, indexing |

### Code Quality

| Name                                                    | Description                                                                        |
|---------------------------------------------------------|------------------------------------------------------------------------------------|
| [Code Scanning - Guide](/code-scanning-guide) | PMD rulesets, ESLint plugin, naming validators, CI/CD integration, phased adoption |

### Testing

| Name                                                | Description                                                                          |
|-----------------------------------------------------|--------------------------------------------------------------------------------------|
| [Test Data - Guide](/test-data-guide)     | TST_Builder, TST_Mock, TST_Factory: auto-population, bulk creation, relationships, DML-free query mocking |
| [E2E Testing - Guide](/e2e-testing-guide) | Playwright E2E testing for Salesforce: authentication, helpers, page objects, CI/CD |

---

## API Reference

Auto-generated API reference documentation for all Apex classes, custom objects, platform events, and custom metadata types.

**[API Reference Index](/reference/)**

| Category              | Link                                  |
|-----------------------|---------------------------------------|
| Apex Classes          | [Browse](/reference/apex/)     |
| Custom Objects        | [Browse](/reference/objects/)  |
| Platform Events       | [Browse](/reference/events/)   |
| Custom Metadata Types | [Browse](/reference/metadata/) |

---

## Special Documents

| Document                                                      | Description                                                                                     |
|---------------------------------------------------------------|-------------------------------------------------------------------------------------------------|
| [AI Agent Instructions](/ai-agent-instructions)         | Complete framework reference for AI agents, repackaging with custom namespace, org setup |
| [Code Conventions - Guide](/code-conventions-guide) | Canonical Apex/LWC/JS coding conventions: naming, formatting, ApexDoc, anti-patterns           |
| [Installation](/installation)                               | Your org configuration, post-install steps, health check verification                     |

### Strategic Guide (9 documents)

| Document                                                                                | Description                                                                                                                       |
|-----------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| [Overview](/strategic-guide-overview)                                         | One-page summary, key findings, recommendations, navigation hub                                                               |
| [Architecture & Philosophy](/strategic-guide-architecture-philosophy) | Design principles, capabilities, Well-Architected + Security Benchmark for Salesforce alignment                                   |
| [Adoption](/strategic-guide-adoption)                                         | Enterprise delivery, total cost of ownership (TCO) model, decision matrices, build-vs-buy economics                                                         |
| [Choosing a Framework](/strategic-guide-choosing-a-framework)             | Capability-by-capability comparison against the established Apex frameworks, pick-by-capability guidance, head-to-head trade-offs |
| [Operations](/strategic-guide-operations)                                     | Running it after go-live, packaging, exit strategy, seeing what your code did in production                                                                          |
| [Risks](/strategic-guide-risks)                                               | Risk register and mitigations for adoption decisions                                                                              |
| [Personas](/strategic-guide-personas)                                         | Stakeholder-specific decision views (chief technology officer, architect, developer, product manager, package developer at an independent software vendor (ISV))                                                          |
| [Glossary](/strategic-guide-glossary)                                         | Term definitions with links to relevant sections                                                                                  |
| [Metrics](/strategic-guide-metrics)                                           | Canonical framework metrics: class counts, test coverage, metadata totals                                                        |

---

## Choosing the Right Document

| I want to...                                           | Start with                                                                                  |
|--------------------------------------------------------|---------------------------------------------------------------------------------------------|
| Learn KernDX for the first time                        | [Learning Paths](#learning-paths)                                                           |
| Build a selector or query data                         | [Fast Start - Selectors](/fast-start-selectors)                                   |
| Build a trigger action                                 | [Fast Start - Trigger Actions](/fast-start-trigger-actions)                     |
| Build a validation rule                                | [Fast Start - Custom Validations](/fast-start-custom-validations)               |
| Insert, update, or delete records                      | [Fast Start - DML](/fast-start-dml)                                               |
| Call an external API                                   | [Fast Start - Outbound APIs](/fast-start-outbound-apis)                         |
| Make a simple ad-hoc HTTP call                         | [UTIL_HttpClient](/reference/apex/util-httpclient)                                        |
| Expose a REST endpoint                                 | [Fast Start - Inbound APIs](/fast-start-inbound-apis)                           |
| Create test data                                       | [Fast Start - Test Data](/fast-start-test-data)                                 |
| Process large data sets asynchronously                 | [Fast Start - Async Processing](/fast-start-async-processing)                   |
| Run a class on a schedule, or many jobs on the job runner | [Fast Start - Scheduled Jobs](/fast-start-scheduled-jobs)                       |
| Orchestrate multi-step async workflows                 | [Async Processing - Guide](/async-processing-guide) (Chain Orchestration section) |
| Chain outbound API calls in sequence                   | [Async Processing - Guide](/async-processing-guide) (ApiStep section)             |
| Add logging to my code                                 | [Fast Start - Logging](/fast-start-logging)                                       |
| Browse and diagnose production logs                    | [Logging - Guide](/logging-guide#the-log-console) (The Log Console section)         |
| Monitor integrations, jobs, and logs from one place    | [Administration Tools - Guide](/administration-tools-guide)                       |
| Toggle features on and off                             | [Fast Start - Feature Flags](/fast-start-feature-flags)                         |
| Make a flaky callout resilient (retry, circuit breaker) | [Fast Start - Resilience](/fast-start-resilience)                                |
| Enforce CRUD/FLS on every read and write (USER_MODE)   | [Fast Start - Security](/fast-start-security)                                     |
| Build my first Lightning Web Component                 | [Fast Start - LWC](/fast-start-lwc)                                               |
| Understand full query architecture                     | [Selectors - Guide](/selectors-guide)                                               |
| Understand full trigger framework                      | [Triggers - Guide](/triggers-guide)                                                 |
| Transform data between formats (DTOs)                  | [DTOs - Guide](/dtos-guide)                                                         |
| Enforce CRUD/FLS or encrypt data                       | [Security - Guide](/security-guide)                                                 |
| Control record-level sharing at runtime                | [Security - Guide](/security-guide)                                                 |
| Redact sensitive data before it is stored              | [Fast Start - Data Masking](/fast-start-data-masking)                           |
| Configure the data masking framework and Advisor       | [Data Masking - Guide](/data-masking-guide)                                       |
| Build Lightning Web Components                         | [LWC - Guide](/lwc-guide)                                                           |
| Use string, date, number, or collection utilities      | [Utilities - Guide](/utilities-guide)                                               |
| Evaluate KernDX vs fflib trade-offs                    | [Choosing a Framework](/strategic-guide-choosing-a-framework)                 |
| Set up KernDX in your org                              | [Installation](/installation)                                                             |
| Configure AI-assisted KernDX development               | [AI Agent Instructions](/ai-agent-instructions)                                       |
| Write browser-based E2E tests                          | [Fast Start - E2E Testing](/fast-start-e2e-testing)                             |
| Enforce framework conventions in CI/CD                 | [Fast Start - Code Scanning](/fast-start-code-scanning)                         |
| Build custom PMD rules or adopt scanning incrementally | [Code Scanning - Guide](/code-scanning-guide)                                     |
| Design an E2E test strategy               | [E2E Testing - Guide](/e2e-testing-guide)                                         |
| Look up a specific class API                           | [API Reference](/reference/apex/)                                                    |
