@adobe/spacecat-shared-data-access 1.59.2 → 1.60.0

package/src/v2/models/suggestion/index.d.ts

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import type { BaseCollection, BaseModel, Opportunity } from '../index';
+
+export interface Suggestion extends BaseModel {
+  getData(): object;
+  getKpiDeltas(): object;
+  getOpportunity(): Promise<Opportunity>;
+  getOpportunityId(): string;
+  getRank(): number;
+  getStatus(): string;
+  getType(): string;
+  setData(data: object): Suggestion;
+  setKpiDeltas(kpiDeltas: object): Suggestion;
+  setOpportunityId(opportunityId: string): Suggestion;
+  setRank(rank: number): Suggestion;
+  setStatus(status: string): Suggestion;
+}
+
+export interface SuggestionCollection extends BaseCollection<Suggestion> {
+  allByOpportunityId(opportunityId: string): Promise<Suggestion[]>;
+  allByOpportunityIdAndStatus(opportunityId: string, status: string): Promise<Suggestion[]>;
+  bulkUpdateStatus(suggestions: Suggestion[], status: string): Promise<Suggestion[]>;
+}

package/src/v2/models/suggestion/index.js

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import Suggestion from './suggestion.model.js';
+import SuggestionCollection from './suggestion.collection.js';
+
+export {
+  Suggestion,
+  SuggestionCollection,
+};

package/src/v2/models/suggestion/suggestion.collection.js

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import BaseCollection from '../base/base.collection.js';
+import { STATUSES } from './suggestion.model.js';
+
+/**
+ * SuggestionCollection - A collection class responsible for managing Suggestion entities.
+ * Extends the BaseCollection to provide specific methods for interacting with Suggestion records.
+ *
+ * @class SuggestionCollection
+ * @extends BaseCollection
+ */
+class SuggestionCollection extends BaseCollection {
+  /**
+   * Updates the status of multiple given suggestions. The given status must conform
+   * to the status enum defined in the Suggestion schema.
+   * Saves the updated suggestions to the database automatically.
+   * You don't need to call save() on the suggestions after calling this method.
+   * @async
+   * @param {Suggestion[]} suggestions - An array of Suggestion instances to update.
+   * @param {string} status - The new status to set for the suggestions.
+   * @return {Promise<*>} - A promise that resolves to the updated suggestions.
+   * @throws {Error} - Throws an error if the suggestions are not provided
+   * or if the status is invalid.
+   */
+  async bulkUpdateStatus(suggestions, status) {
+    if (!Array.isArray(suggestions)) {
+      throw new Error('Suggestions must be an array');
+    }
+
+    if (!Object.values(STATUSES).includes(status)) {
+      throw new Error(`Invalid status: ${status}. Must be one of: ${Object.values(STATUSES).join(', ')}`);
+    }
+
+    suggestions.forEach((suggestion) => {
+      suggestion.setStatus(status);
+    });
+
+    await this._saveMany(suggestions);
+
+    return suggestions;
+  }
+}
+
+export default SuggestionCollection;

package/src/v2/models/{suggestion.model.js → suggestion/suggestion.model.js}

@@ -10,7 +10,22 @@
  * governing permissions and limitations under the License.
  */
 
-import BaseModel from './base.model.js';
+import BaseModel from '../base/base.model.js';
+
+export const STATUSES = {
+  NEW: 'NEW',
+  APPROVED: 'APPROVED',
+  SKIPPED: 'SKIPPED',
+  FIXED: 'FIXED',
+  ERROR: 'ERROR',
+};
+
+export const TYPES = {
+  CODE_CHANGE: 'CODE_CHANGE',
+  CONTENT_UPDATE: 'CONTENT_UPDATE',
+  REDIRECT_UPDATE: 'REDIRECT_UPDATE',
+  METADATA_UPDATE: 'METADATA_UPDATE',
+};
 
 /**
  * Suggestion - A class representing a Suggestion entity.

package/src/v2/models/suggestion/suggestion.schema.js

@@ -0,0 +1,53 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/* c8 ignore start */
+
+import { isNonEmptyObject } from '@adobe/spacecat-shared-utils';
+
+import SchemaBuilder from '../base/schema.builder.js';
+import Suggestion, { STATUSES, TYPES } from './suggestion.model.js';
+import SuggestionCollection from './suggestion.collection.js';
+
+/*
+Schema Doc: https://electrodb.dev/en/modeling/schema/
+Attribute Doc: https://electrodb.dev/en/modeling/attributes/
+Indexes Doc: https://electrodb.dev/en/modeling/indexes/
+ */
+
+const schema = new SchemaBuilder(Suggestion, SuggestionCollection)
+  .addReference('belongs_to', 'Opportunity', ['status', 'rank'])
+  .addAttribute('type', {
+    type: Object.values(TYPES),
+    required: true,
+    readOnly: true,
+  })
+  .addAttribute('rank', {
+    type: 'number',
+    required: true,
+  })
+  .addAttribute('data', {
+    type: 'any',
+    required: true,
+    validate: (value) => isNonEmptyObject(value),
+  })
+  .addAttribute('kpiDeltas', {
+    type: 'any',
+    validate: (value) => !value || isNonEmptyObject(value),
+  })
+  .addAttribute('status', {
+    type: Object.values(STATUSES),
+    required: true,
+    default: STATUSES.NEW,
+  });
+
+export default schema.build();

package/src/v2/readme.md

@@ -1,272 +1,217 @@
-# ElectroDB Model Framework
-
-This repository contains a model framework built using the ElectroDB ORM, designed to manage website improvements in a scalable manner. The system consists of several entities, including Opportunities and Suggestions, which represent potential areas of improvement and the actions to resolve them.
-
-## Table of Contents
-
-1. [Architecture Overview](#architecture-overview)
-2. [Entities and Relationships](#entities-and-relationships)
-3. [Getting Started](#getting-started)
-4. [Adding a New ElectroDB-Based Entity](#adding-a-new-electrodb-based-entity)
-   - [Step 1: Define the Entity Schema](#step-1-define-the-entity-schema)
-   - [Step 2: Add a Model Class](#step-2-add-a-model-class)
-   - [Step 3: Add a Collection Class](#step-3-add-a-collection-class)
-   - [Step 4: Integrate the Entity into Model Factory](#step-4-integrate-the-entity-into-model-factory)
-   - [Step 5: Write Unit and Integration Tests](#step-5-write-unit-and-integration-tests)
-   - [Step 6: Create JSDoc and Update Documentation](#step-6-create-jsdoc-and-update-documentation)
-   - [Step 7: Run Tests and Verify](#step-7-run-tests-and-verify)
-
-## Architecture Overview
-
-The architecture follows a collection-management pattern with ElectroDB, enabling efficient handling of DynamoDB entities. The architecture is organized into the following layers:
-
-1. **Data Layer**: Uses DynamoDB with ElectroDB to manage schema definitions and data interactions.
-2. **Model Layer**: The `BaseModel` provides methods like `save`, `remove`, and manages associations. Entity classes such as `Opportunity` and `Suggestion` extend `BaseModel` for specific features.
-3. **Collection Layer**: The `BaseCollection` handles CRUD operations for entities. Specialized collections, like `OpportunityCollection` and `SuggestionCollection`, extend `BaseCollection` with tailored methods for specific entities.
-4. **Factory Layer**: The `ModelFactory` centralizes instantiation of models and collections, providing a unified interface for different entity types.
-
-### Architectural Diagram
-
-```plaintext
-+--------------------+
-|  Data Layer        |
-|--------------------|
-|  DynamoDB + ElectroDB ORM  |
-+--------------------+
-         ↓
-+--------------------+
-|  Collection Layer  |
-|--------------------|
-|  BaseCollection,   |
-|  OpportunityCollection,    |
-|  SuggestionCollection      |
-+--------------------+
-         ↓
-+--------------------+
-|  Model Layer       |
-|--------------------|
-|  BaseModel,        |
-|  Opportunity,      |
-|  Suggestion        |
-+--------------------+
-         ↓
-+--------------------+
-|  Factory Layer     |
-|--------------------|
-|  ModelFactory      |
-+--------------------+
+# ElectroDB Entity Framework
+
+## Overview
+
+This entity framework streamlines the definition, querying, and manipulation of domain entities in a DynamoDB-based application. Built atop [ElectroDB](https://electrodb.dev/), it provides a consistent layer for schema definition, indexing, and robust CRUD operations, while adding conveniences like automatic indexing methods and reference handling.
+
+By adhering to this framework’s conventions, you can introduce and manage new entities with minimal boilerplate and complexity.
+
+## Core Concepts
+
+### Entities
+An *entity* represents a domain concept (e.g., `User`, `Organization`, `Order`) persisted in the database. Each entity is defined by a schema, specifying attributes, indexes, and references to other entities. The schema integrates with ElectroDB, ensuring a uniform approach to modeling data.
+
+### Models
+A *Model* is a class representing a single instance of an entity. It provides:
+
+- Attribute getters and setters generated based on the schema.
+- Methods for persisting changes (`save()`), and removing entities (`remove()`).
+- Methods to fetch referenced entities (via `belongs_to`, `has_one`, `has_many` references).
+
+Models extend `BaseModel`, which handles most of the common logic.
+
+### Collections
+A *Collection* operates on sets of entities. While `Model` focuses on individual records, `Collection` is for batch and query-level operations:
+
+- Query methods like `findById()`, `all()`, and index-derived methods.
+- Batch creation and update methods (`createMany`, `_saveMany`).
+- Automatic generation of `allBy...` and `findBy...` convenience methods based on defined indexes.
+
+Collections extend `BaseCollection`, which generates query methods at runtime based on your schema definitions.
+
+### Schema Builder
+The `SchemaBuilder` is a fluent API to define an entity’s schema:
+
+- **Attributes:** Configure entity fields and their validation.
+- **Indexes:** Specify primary and secondary indexes for common queries.
+- **References:** Define entity relationships (e.g., `User` belongs to `Organization`).
+
+The `SchemaBuilder` enforces naming conventions and sets defaults, reducing repetitive configuration.
+
+**Note on Indexes:** Add indexes thoughtfully. Every extra index adds cost and complexity. Only create indexes for well-understood, frequently-needed query patterns.
+
+### Entity Registry
+The `EntityRegistry` aggregates all entities, their schemas, and their collections. It ensures consistent lookup and retrieval of any registered entity’s collection. When you add a new entity, you must register it with the `EntityRegistry` so the rest of the application can discover it.
+
+## Default Attributes and Indexes
+
+When you create a schema with `SchemaBuilder`, the following attributes are automatically defined:
+
+1. **ID (Primary Key):** A UUID-based primary key (`${entityName}Id`), ensuring unique identification.
+2. **createdAt:** A timestamp (ISO string) set at entity creation.
+3. **updatedAt:** A timestamp (ISO string) updated on each modification.
+
+A primary index is also set up, keyed by the `${entityName}Id` attribute, guaranteeing a straightforward way to retrieve entities by their unique ID.
+
+## Auto-Generated Methods
+
+### `BaseCollection`
+
+`BaseCollection` automatically generates `allBy...` and `findBy...` methods derived from your defined indexes. For example, if your schema defines an index composed of `opportunityId`, `status`, and `createdAt`, `BaseCollection` will generate:
+
+- `allByOpportunityId(opportunityId, options?)`
+- `findByOpportunityId(opportunityId, options?)`
+- `allByOpportunityIdAndStatus(opportunityId, status, options?)`
+- `findByOpportunityIdAndStatus(opportunityId, status, options?)`
+- `allByOpportunityIdAndStatusAndCreatedAt(opportunityId, status, createdAt, options?)`
+- `findByOpportunityIdAndStatusAndCreatedAt(opportunityId, status, createdAt, options?)`
+
+**allBy...** methods return arrays of matching entities, while **findBy...** methods return a single (or the first matching) entity. Both can accept an optional `options` object for filtering, ordering, attribute selection, and pagination.
+
+**Example:**
+```js
+const Suggestion = dataAccess.Suggestion;
+
+// Retrieve all suggestions by `opportunityId`
+const results = await Suggestion.allByOpportunityId('op-12345');
+
+// Retrieve a single suggestion by `opportunityId` and `status`
+const single = await Suggestion.findByOpportunityIdAndStatus('op-12345', 'OPEN');
 ```
 
-## Entities and Relationships
-
-- **Opportunity**: Represents a specific issue identified on a website. It includes attributes like `title`, `description`, `siteId`, and `status`.
-- **Suggestion**: Represents a proposed fix for an Opportunity. Attributes include `opportunityId`, `type`, `status`, and `rank`.
-- **Relationships**: Opportunities have many Suggestions. This relationship is implemented through `OpportunityCollection` and `SuggestionCollection`, which interact via ElectroDB-managed DynamoDB relationships.
-
-## Getting Started
-
-1. **Install Dependencies**
-   ```bash
-   npm install
-   ```
-
-2. **Setup DynamoDB**
-   - Ensure AWS credentials are configured and a DynamoDB table is set up.
-   - Configure the DynamoDB table name and related settings in `index.js`.
-
-3. **Usage Example**
-   ```javascript
-   import { createDataAccess } from './index.js';
-
-   const config = { tableNameData: 'YOUR_TABLE_NAME' };
-   const log = console;
-   const dao = createDataAccess(config, log);
-
-   // Create a new Opportunity
-   const opportunityData = { title: 'Broken Links', siteId: 'site123', type: 'broken-backlinks' };
-   const newOpportunity = await dao.Opportunity.create(opportunityData);
-   console.log('New Opportunity Created:', newOpportunity);
-   ```
-
-4. **Extending Functionality**
-   - Add new models by extending `BaseModel` and new collections by extending `BaseCollection`.
-   - Register new models in the `ModelFactory` for unified access.
-
-## Adding a New ElectroDB-Based Entity
-
-This guide provides a step-by-step overview for adding a new ElectroDB-based entity to the application.
-
-### Step 1: Define the Entity Schema
-
-1. **Create Entity Schema File**: Define the entity schema in a new file (e.g., `myNewEntity.schema.js`) within the `/schemas/` directory.
-
-   ```javascript
-   export const MyNewEntitySchema = {
-     model: {
-       entity: 'MyNewEntity',
-       service: 'MyService',
-       version: '1',
-     },
-     attributes: {
-       myNewEntityId: {
-         type: 'string',
-         required: true,
-       },
-       name: {
-         type: 'string',
-         required: true,
-       },
-       status: {
-         type: 'string',
-         enum: ['NEW', 'IN_PROGRESS', 'COMPLETED'],
-         required: true,
-       },
-       createdAt: {
-         type: 'string',
-         required: true,
-         default: () => new Date().toISOString(),
-       },
-     },
-     indexes: {
-       myNewEntityIndex: {
-         pk: {
-           field: 'pk',
-           facets: ['myNewEntityId'],
-         },
-         sk: {
-           field: 'sk',
-           facets: ['status'],
-         },
-       },
-     },
-     references: {
-       belongs_to: [
-         { type: 'belongs_to', target: 'Opportunity' },
-       ],
-     },
-   };
-   ```
-
-2. **Declare References**: Use the `references` field to define relationships between entities. This sets up associations for easy fetching and managing of related entities, allowing for automatic generation of reference getter methods.
-
-### Step 2: Add a Model Class
-
-1. **Create the Model Class**: In the `/models/` directory, add `myNewEntity.model.js`.
-
-   ```javascript
-   import BaseModel from './base.model.js';
-   
-   class MyNewEntity extends BaseModel {
-     constructor(electroService, modelFactory, record, log) {
-       super(electroService, modelFactory, record, log);
-     }
-   }
-   
-   export default MyNewEntity;
-   ```
-
-   Note: By using `BaseModel`, entity classes can remain empty unless there is a need to:
-   - Override automatically generated getters or setters for specific attributes.
-   - Add custom methods specific to the entity.
-
-### Automatic Getter and Setter Methods
-
-The `BaseModel` automatically generates getter and setter methods for each attribute defined in the entity schema:
-
-- **Utility Methods**: `BaseModel` provides `getId()`, `getCreatedAt()`, and `getUpdatedAt()` methods out of the box for accessing common entity information like the unique identifier, creation timestamp, and last update timestamp.
-
-- **Getters**: Follow the convention `get<AttributeName>()` to access attribute values.
-- **Setters**: Follow the convention `set<AttributeName>(value)` to modify entity values, while handling patching.
-
-Example:
-
-- If an attribute is named `name`, `BaseModel` will automatically generate:
-   - `getName()`: Retrieve the value of `name`.
-   - `setName(value)`: Update the value of `name`.
-
-This reduces boilerplate and ensures consistency.
-
-### Automatic Reference Getter Methods
-
-If references are defined in the schema (e.g., `belongs_to`, `has_many`), `BaseModel` generates reference getter methods:
-
-- **References Getter Naming**:
-   - Methods are named `get<RelatedEntity>()`, where `<RelatedEntity>` corresponds to the target specified in the `references` field.
-
-  Example:
-  ```javascript
-  references: {
-     belongs_to: [
-        { type: 'belongs_to', target: 'Opportunity' },
-     ],
-  },
-  ```
-  This results in a `getOpportunity()` method for accessing the related `Opportunity` entity.
-
-### Step 3: Add a Collection Class
-
-1. **Create the Collection Class**: Add `myNewEntity.collection.js` in the `/collections/` directory.
-
-   ```javascript
-   import BaseCollection from './base.collection.js';
-   import MyNewEntity from '../models/myNewEntity.model.js';
-
-   class MyNewEntityCollection extends BaseCollection {
-     constructor(service, modelFactory, log) {
-       super(service, modelFactory, MyNewEntity, log);
-     }
-
-     async allByStatus(status) {
-       return this.findByIndexKeys({ status });
-     }
-   }
-
-   export default MyNewEntityCollection;
-   ```
+### `BaseModel`
 
-### Step 4: Integrate the Entity into Model Factory
+`BaseModel` provides methods for CRUD operations and reference handling:
 
-1. **Update the Model Factory**: Open `model.factory.js` and add the new entity and collection to the `initialize` method.
+- `save()`: Persists changes to the entity.
+- `remove()`: Deletes the entity from the database.
+- `get...()`: Getters for entity attributes.
+- `set...()`: Setters for entity attributes.
 
-   ```javascript
-   import MyNewEntityCollection from './collections/myNewEntity.collection.js';
+Additionally, `BaseModel` generates methods to fetch referenced entities. 
+For example, if `User` belongs to `Organization`, `BaseModel` will create:
 
-   class ModelFactory {
-     initialize() {
-       const myNewEntityCollection = new MyNewEntityCollection(
-         this.service,
-         this,
-         this.logger,
-       );
+- `getOrganization()`: Fetch the referenced `Organization` entity.
+- `getOrganizationId()`: Retrieve the `Organization` ID.
+- `setOrganizationId(organizationId)`: Update the `Organization` reference.
 
-       this.models.set(MyNewEntityCollection.name, myNewEntityCollection);
-     }
-   }
-   ```
+Conversely, the `Organization` entity will have:
 
-### Step 5: Write Unit and Integration Tests
+- `getUsers()`: Fetch all `User` entities referencing this `Organization`.
+- And with the `User`-Schema's `belongs_to` reciprocal reference expressing filterable sort keys, e.g. "email", "location":
+  - `getUsersByEmail(email)`: Fetch all `User` entities referencing this `Organization` with a specific email."
+  - `getUsersByEmailAndLocation(email, location)`: Fetch all `User` entities referencing this `Organization` with a specific email and location.
 
-1. **Create Unit Tests**: Add a file named `myNewEntity.model.test.js` in `/tests/unit/models/` to test all getters, setters, and interactions.
-   - Use Mocha, Chai, and Sinon for testing.
+**Example:**
+```js
+const user = await User.findById('usr-abc123');
 
-2. **Create Collection Tests**: Add `myNewEntity.collection.test.js` to `/tests/unit/collections/`.
-   - Test methods interacting with ElectroDB, like `allByStatus`.
+// Work with attributes
+console.log(user.getEmail());   // e.g. "john@example.com"
+user.setName('John Smith');
+await user.save();
 
-3. **Add Integration Tests**: Create an integration test file named `myNewEntity.integration.test.js` in `/tests/integration/` to test the full lifecycle of the entity.
+// Fetch referenced entity
+const org = await user.getOrganization();
+console.log(org.getName());
+```
 
-### Step 6: Create JSDoc and Update Documentation
+## Step-by-Step: Adding a New Entity
 
-1. **Generate JSDoc for Entity and Collection**: Add JSDoc comments for each function to describe the API.
-2. **Update Type Definitions**: Modify `index.d.ts` to include new interfaces and types for the entity.
+Follow these steps to introduce a new entity into the framework.
 
-### Step 7: Run Tests and Verify
+### 1. Define the Schema
+Create `user.schema.js`:
+
+```js
+import SchemaBuilder from '../base/schema.builder.js';
+import User from './user.model.js';
+import UserCollection from './user.collection.js';
+
+const userSchema = new SchemaBuilder(User, UserCollection)
+  .addAttribute('email', {
+    type: 'string',
+    required: true,
+    validate: (value) => value.includes('@'),
+  })
+  .addAttribute('name', { type: 'string', required: true })
+  .addAllIndexWithComposite('email')
+  .addReference('belongs_to', 'Organization') // Adds organizationId and byOrganizationId index
+  .build();
+
+export default userSchema;
+```
+
+### 2. Implement the Model
+Create `user.model.js`:
+
+```js
+import BaseModel from '../base/base.model.js';
+
+class UserModel extends BaseModel {
+  // Additional domain logic methods can be added here if needed.
+}
+
+export default UserModel;
+```
+
+### 3. Implement the Collection
+Create `user.collection.js`:
+
+```js
+import BaseCollection from '../base/base.collection.js';
+import UserModel from './user.model.js';
+import userSchema from './user.schema.js';
+
+class UserCollection extends BaseCollection {
+  // Additional domain logic collection methods can be added here if needed.
+  async findByEmail(email) {
+    return this.findByIndexKeys({ email });
+  }
+}
+
+export default UserCollection;
+```
+
+### 4. Register the Entity
+In `entity.registry.js` (or equivalent):
+
+```js
+import UserSchema from '../user/user.schema.js';
+import UserCollection from '../user/user.collection.js';
+
+EntityRegistry.registerEntity(UserSchema, UserCollection);
+```
+
+### 5. Update DynamoDB Configuration and `schema.json`
+
+After defining indexes in the schema, **manually add these indexes to your DynamoDB table configuration**. DynamoDB does not automatically create GSIs. You must:
+
+- Use the AWS Console, CLI, or CloudFormation/Terraform templates to define these GSIs.
+- Update your `schema.json` or another documentation file to reflect the newly created indexes, so the team knows which indexes exist and what query patterns they support.
+
+### 6. Use the Entity
+```js
+const { User, Organization } = dataAccess;
+
+// Create a user
+const newUser = await User.create({ email: 'john@example.com', name: 'John Doe' });
+
+// Find user by ID
+const user = await User.findById(newUser.getId());
+
+// Get the user organization
+const org = await user.getOrganization();
+
+// ...or in reverse
+const anOrg = await Organization.findById(user.getOrganizationId());
+const orgUsers = await anOrg.getUsers();
+
+// Update user and save
+user.setName('John X. Doe');
+await user.save();
+```
 
-1. **Run All Tests**:
-   ```bash
-   npm run test && npm run test:it
-   ```
+## Consideration for Indexes
 
-2. **Run Linter**: Check for coding standard violations.
-   ```bash
-   npm run lint
-   ```
+Indexes cost money and complexity. Do not add indexes lightly. Determine which query patterns you truly need and only then introduce additional indexes.