# CG Mobile App - AI Knowledge Base

> ⚠️ **This entire folder is auto-generated.** Running `sf modeler workspace upgrade` deletes and replaces it with the latest version from the CLI plugin. Do not edit files here — your changes will be lost. To customize AI behavior, use your tool's own config (e.g. `.claude/CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`).

This directory contains architecture documentation, development skills, and reference material for the Consumer Goods Cloud Mobile App contract system. It is designed to be consumed by AI coding assistants (Claude, Cursor, GitHub Copilot, etc.) to provide deep context about the 6-layer metadata-driven architecture.

## Contents

### architecture/

Detailed documentation of each architectural layer:

| File                      | Layer                | Description                              |
| ------------------------- | -------------------- | ---------------------------------------- |
| `datasource-layer.md`     | DataSource (DS)      | Salesforce to app attribute mapping      |
| `businessobject-layer.md` | Business Object (BO) | Entity definitions and lifecycle methods |
| `listobject-layer.md`     | ListObject (LO)      | Collection management and aggregation    |
| `process-layer.md`        | Process (PR)         | Workflow orchestration                   |
| `ui-layer.md`             | User Interface (UI)  | Responsive interface components          |
| `integration-flow.md`     | End-to-End           | Complete data flow tracing               |
| `testing-and-build.md`    | Testing & Build      | Jest framework and build process         |

### wiki/

Concept pages covering the full modeler stack:

| Page                           | Description                          |
| ------------------------------ | ------------------------------------ |
| `architecture-overview.md`     | Architecture Overview                |
| `business-logic.md`            | Business Logic (.bl.js)              |
| `business-objects.md`          | Business Object (BO)                 |
| `calendar-control.md`          | Calendar Control                     |
| `cockpit-cards.md`             | Application Cockpit Cards            |
| `customer-detail-screens.md`   | Customer Detail Screens              |
| `datasource.md`                | DataSource (DS)                      |
| `db-tables.md`                 | DBTable / TempTable Validation Rules |
| `external-files.md`            | ExternalFile Validation Rules        |
| `list-objects.md`              | ListObject (LO) & ListItem (LI)      |
| `lookup-objects.md`            | LookupObject (LU) Validation Rules   |
| `misc-contracts-validation.md` | Miscellaneous Contracts Validation   |
| `modeler-setup.md`             | Modeler Setup                        |
| `module-architecture.md`       | Module Architecture & Dependencies   |
| `offline-sync.md`              | Offline Sync Patterns                |
| `plugins.md`                   | Plugin (UserExit) Validation Rules   |
| `print-layouts.md`             | Print Layouts (PL)                   |
| `processes.md`                 | Process (PR)                         |
| `testing-and-build.md`         | Testing & Build                      |
| `ui-plugins.md`                | UIPluginV2 Validation Rules          |
| `user-interface.md`            | User Interface (UI)                  |

### skills/

AI coding skills for authoring and verifying modeler contracts. Each skill contains a SKILL.md definition, reference documentation, templates, and tests:

| Skill                    | Description                                       |
| ------------------------ | ------------------------------------------------- |
| `add-calendar-view`      | Add a calendar/planner/schedule view (full chain) |
| `add-cockpit-card`       | Add a new card to the Application Cockpit         |
| `add-detail-screen`      | Add a detail or edit screen for a single record   |
| `add-list-screen`        | Add a new list or search screen                   |
| `build-and-simulate`     | Build, simulate, and test the app                 |
| `create-business-logic`  | Create .bl.js business logic files                |
| `create-business-object` | Create or modify .businessobject.xml files        |
| `create-datasource`      | Create or modify .datasource.xml files            |
| `create-list-object`     | Create or modify .listobject.xml + .listitem.xml  |
| `create-lookup-object`   | Create or modify .lookupobject.xml files          |
| `create-print-layout`    | Create or modify .printlayoutv2.xml files         |
| `create-process`         | Create or modify .processflow.xml files           |
| `create-ui-page`         | Create or modify .userinterface.xml files         |
| `verify-sqlite-schema`   | Verify table/column exists in local SQLite DB     |

### patterns/

Implementation patterns and best practices:

| File                        | Description                                        |
| --------------------------- | -------------------------------------------------- |
| `datasource-patterns.md`    | Declarative XML vs external JS DataSource patterns |
| `cockpit-card-checklist.md` | 7-step cockpit card implementation checklist       |

### reference/

Coding standards and naming conventions:

| File                    | Description                                              |
| ----------------------- | -------------------------------------------------------- |
| `naming-conventions.md` | File naming, property naming, PascalCase/camelCase rules |

### agents/

AI agent definitions with specialized knowledge:

| File                    | Description                                                  |
| ----------------------- | ------------------------------------------------------------ |
| `cgmobile-dev-agent.md` | Spec-driven development agent with full architecture mastery |

## Quick Reference

### Architecture Stack

```
Salesforce Cloud (Source of Truth)
    |
SQLite (Offline Cache)
    |
DataSource Layer (DS) - Field mapping
    |
Business Object / ListObject Layer (BO/LO) - Business logic
    |
Process Layer (PR) - Workflow orchestration
    |
User Interface Layer (UI) - Responsive presentation
```

### Contract Types

| Type            | Extension             | Naming Pattern       | Purpose                          |
| --------------- | --------------------- | -------------------- | -------------------------------- |
| DataSource      | `.datasource.xml`     | `Ds[Bo\|Lo\|Lu]*_sf` | Maps SF fields to app attributes |
| Business Object | `.businessobject.xml` | `Bo*`                | Single entity with lifecycle     |
| ListObject      | `.listobject.xml`     | `Lo*`                | Collections with aggregation     |
| ListItem        | `.listitem.xml`       | `Li*`                | Item structure in collections    |
| LookupObject    | `.lookupobject.xml`   | `Lu*`                | Reference data lookups           |
| Process         | `.processflow.xml`    | `*Process`           | Workflow orchestration           |
| User Interface  | `.userinterface.xml`  | `*UI`                | Responsive UI layouts            |
| Business Logic  | `.bl.js`              | `Bo*.Method.bl.js`   | JavaScript logic methods         |
| Print Layout    | `.printlayoutv2.xml`  | `Pl*`                | Printed documents (PDF/thermal)  |

### Build & Test Commands

```bash
# Commands shipped by the Modeler CLI plugin (with `sf mdl` shortcuts)
sf modeler workspace build          # or `sf mdl build`     — compile the workspace
sf modeler workspace validate       # or `sf mdl validate`  — validate against XSDs
sf modeler workspace cleanup        # or `sf mdl clean`     — remove compiled artifacts
sf modeler workspace package        # or `sf mdl package`   — package for deployment
sf modeler workspace add            # or `sf mdl add`       — add a module
sf modeler workspace server start   # or `sf mdl simulate` — start the Modeler development server
```

## Using the Skills

To use the AI skills with Claude Code:

1. Copy the `skills/` directory (or the subset you need) into `.claude/skills/` in your project.
2. Ensure your workspace has `appl/data/app.db3` available (the `verify-sqlite-schema` skill reads it).
3. Start your AI assistant at the workspace root. Skills activate on the trigger phrases documented in each `SKILL.md`.

See `wiki/` and `architecture/` for conceptual background — the skills reference the same terminology.

## Usage with AI Assistants

**Important:** Do NOT load the entire `ai-wiki/` folder into context. Use `INDEX.md` for on-demand routing:

-   **Claude Code:** Add to CLAUDE.md: "For CG Mobile contract work, read `ai-wiki/INDEX.md` to find the relevant document." Copy `skills/` to `.claude/skills/` for native trigger-phrase activation.
-   **Cursor:** Add to `.cursorrules`: "For CG Mobile contracts, read `ai-wiki/INDEX.md` first." Then use `@ai-wiki/INDEX.md` to find the right file and @-mention that specific file.
-   **GitHub Copilot:** Reference `ai-wiki/INDEX.md` in `.github/copilot-instructions.md` for routing.
-   **Other tools:** Point your AI at `ai-wiki/INDEX.md` as the single entry point — not the folder.

### Why an Index?

This folder contains 100+ files (~1.3 MB). Loading all of them into context wastes tokens and pushes real work out of the AI's attention window. The `INDEX.md` file is ~3 KB and tells the AI exactly which file to read for any given task — enabling lazy, on-demand loading.

### Directory Structure

```
ai-wiki/
├── INDEX.md          <- READ THIS FIRST (routing table for AI agents)
├── README.md         <- This file (human orientation)
├── architecture/     <- Layer-by-layer docs (7 files)
├── skills/           <- Step-by-step creation guides (14 skills)
├── wiki/             <- Concept deep-dives (20+ articles)
├── patterns/         <- Implementation patterns (2 files)
├── reference/        <- Naming conventions (1 file)
└── agents/           <- AI agent definitions (1 file)
```

## Version

This documentation is distributed by the Modeler CLI plugin (`@ind-rcg/modeler-sfdx-cli-plugin`).