---
title: Architecture Overview
aliases: [layer stack, 6-layer architecture, metadata architecture]
sources: [sources/sessions/2026-02-18-integration-summary.md, sources/sessions/2026-02-18-datasource-analysis.md]
last_updated: 2026-04-19
status: seed
---

# Architecture Overview

The CG Mobile App uses a **6-layer declarative metadata architecture**. Each layer is expressed as XML contracts (and JavaScript business logic) that the Modeler plugin compiles into runtime artifacts. No manual code generation is required — the Modeler builds everything from these contracts.

## The Layer Stack

```
┌─────────────────────────────────────────────────────────────┐
│                      Salesforce Cloud                        │
│  Account, Visit__c, Task, etc. (Source of Truth)            │
└──────────────────────────┬──────────────────────────────────┘
                           │ Sync (Salesforce Mobile SDK)
                           ▼
┌─────────────────────────────────────────────────────────────┐
│               Local SQLite Database                          │
│  appl/data/app.db3 — synced copy of Salesforce data         │
│  ONLY columns configured for sync are available locally     │
└──────────────────────────┬──────────────────────────────────┘
                           │ Query
                           ▼
┌─────────────────────────────────────────────────────────────┐
│               Layer 1 — DataSource (DS)                     │
│  Maps Salesforce fields → DS attributes                     │
│  Files: *.datasource.xml                                    │
└──────────────────────────┬──────────────────────────────────┘
                           │ Load
                           ▼
┌─────────────────────────────────────────────────────────────┐
│          Layer 2/3 — Business Object / ListObject           │
│  DS attributes → typed properties + business logic          │
│  Files: *.businessobject.xml, *.listobject.xml,             │
│         *.listitem.xml, *.bl.js                             │
└──────────────────────────┬──────────────────────────────────┘
                           │ Orchestrate
                           ▼
┌─────────────────────────────────────────────────────────────┐
│               Layer 4 — Process (PR)                        │
│  Coordinates load, save, logic, decisions, navigation       │
│  Files: *.processflow.xml                                   │
└──────────────────────────┬──────────────────────────────────┘
                           │ Bind
                           ▼
┌─────────────────────────────────────────────────────────────┐
│               Layer 5 — User Interface (UI)                 │
│  Binds ProcessContext → UI controls, responsive layouts     │
│  Files: *.userinterface.xml                                 │
└──────────────────────────┬──────────────────────────────────┘
                           │ Display
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                           User                              │
│  Views and interacts with mobile app                        │
└─────────────────────────────────────────────────────────────┘
```

## Key Principles

| Principle                  | Description                                                                                                                                                                      |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Offline-First**          | All queries run against local SQLite (`appl/data/app.db3`). Only sync-configured columns are available. Always verify DS columns against the DB schema before writing contracts. |
| **Declarative Contracts**  | XML metadata defines data mapping, structure, orchestration, and presentation.                                                                                                   |
| **Business Logic in JS**   | Custom rules live in `.bl.js` files, not in XML.                                                                                                                                 |
| **Process Is the Hub**     | The Process layer connects the business layer (BO/LO) to the presentation layer (UI) via `ProcessContext`.                                                                       |
| **Responsive by Default**  | UI layouts define Phone, Tablet, and Default variants.                                                                                                                           |
| **Separation of Concerns** | DS = data mapping, BO = business rules, LO = collections, PR = orchestration, UI = presentation.                                                                                 |

## Directory Structure

```
src/
├── {Module}/                       # e.g., Visit, Call, Order, Application
│   ├── DS/                         # DataSource XML files
│   │   ├── DsBo*_sf.datasource.xml
│   │   └── DsLo*_sf.datasource.xml
│   ├── BO/                         # Business Objects, ListObjects, ListItems
│   │   ├── Bo{Name}/
│   │   │   ├── Bo{Name}.businessobject.xml
│   │   │   └── Mv2/               # Business logic files
│   │   │       ├── LoadAsync/
│   │   │       ├── SaveAsync/
│   │   │       ├── CreateAsync/
│   │   │       ├── Initialize/
│   │   │       ├── DoValidateAsync/
│   │   │       └── Bo{Name}.{CustomMethod}.bl.js
│   │   └── Lo{Name}/
│   │       ├── Lo{Name}.listobject.xml
│   │       ├── Li{Name}.listitem.xml
│   │       └── Mv2/
│   └── PR/                         # Processes and their UIs
│       └── {Module}_{Feature}/
│           ├── {Module}_{Feature}Process.processflow.xml
│           └── {Module}_{Feature}UI.userinterface.xml
├── Utilities/
│   └── BO/
│       └── BoSalesCockpitHelper/   # Card controller for Application Cockpit
└── Application/
    └── PR/
        └── Application_Cockpit/    # Main dashboard process & UI
```

## End-to-End Data Flows

### Read Flow: Display a List

```
Salesforce (records) → Sync → SQLite (local copy)
    → DS query (WHERE clause with parameters)
    → LO Load (LI instances populated)
    → afterLoadAsync (computed properties set)
    → Process EntryActions (LOAD/CREATE + LOGIC)
    → ProcessContext variable
    → UI binds (dataSource="ProcessContext::ListVar")
    → Format and display
```

### Write Flow: Edit and Save

```
User opens edit screen → Process LOAD action → BO loaded
    → TWO_WAY bindings (UI displays editable values)
    → User modifies fields (bindings write back to BO)
    → User clicks Done (ButtonPressedEvent)
    → Process event handler → LOGIC action (validate/transform)
    → VALIDATION action (beforeDoValidateAsync → afterDoValidateAsync)
    → DECISION (valid?) → SAVE action → DS write → SQLite → Background sync → Salesforce
```

### Complete Mapping Chain

```
Salesforce Field → DS Attribute → BO/LI Property → Computed → UI Binding → Display
```

## Cross-References

-   [[datasource]] — Layer 1 details
-   [[business-objects]] — Layer 2 details
-   [[list-objects]] — Layer 3 details
-   [[processes]] — Layer 4 details
-   [[user-interface]] — Layer 5 details
-   [[business-logic]] — Layer 6 details
-   [[cockpit-cards]] — Application Cockpit card pattern