Merge branch 'main' into docs/custom-prisma-attributes

docs/community/handling-a-new-issue.md

@@ -1,11 +1,11 @@
 ---
 id: handling-a-new-issue
-title: Handling a New Issue
-sidebar_label: Handling a New Issue
+title: Handling Issues
+sidebar_label: Handling Issues
 slug: /community/handling-a-new-issue
 ---
 
-# Handling a New Issue
+# Handling Issues
 
 **This article describes how the Amplication team responds to a new issue in GitHub.**
 

docs/contributing.md

@@ -1,10 +1,10 @@
 ---
 id: contributing
-sidebar_label: Contributing
+sidebar_label: Introduction
 slug: /contributing
 ---
 
-# Contributing
+# Contribute To Amplication
 
 We would ❤️ it if you contributed to the project and helped make Amplication even better. We will make sure that contributing to Amplication is easy, enjoyable, and educational for anyone and everyone. All contributions are welcome, including features, issues, documentation, guides, and more.
 

docs/dictionary/en-custom.txt

@@ -82,4 +82,5 @@ drawio
 heirarchy
 autoplay
 youtube
+datasource
 autoincrement

docs/faqs/faqs.mdx

@@ -230,7 +230,23 @@ The monorepo model provides you with several advantages:
 
 ## Will all my services be stored in the same or different repositories?
 
-It depends on your requirements. If you want to store all your projects( or services) on the same repo then amplication provides you the monorepo model to do so. Alternatively, you can create different repositories to store the service as Amplication as supports the polyrepo approach.
+The choice is yours.
+You can decide where you want to sync your code for each service.
+
+You can store each service in its own separate repo.
+You can also group services together in the same repository.
+
+Amplication provides two options for organizing your generated code in a git repository:
+
+- **Monorepo** - Stores your service code in a dedicated folder you select. Great if combining multiple services in one repo.
+- **Polyrepo** - Puts your service code at the root of the repo. Better if you want a single service per repository.
+
+:::note
+Check out our docs for more on syncing to a git repository and how Amplication handles pull requests:
+
+- [Sync with GitHub](/sync-with-github)
+- [Sync with Bitbucket](/sync-with-bitbucket)
+:::
 
 ---
 

docs/getting-started/first-service.md

@@ -5,9 +5,15 @@ sidebar_label: Create Your First Service
 slug: /first-service
 ---
 
-Welcome to Amplication, a platform that helps you build critical apps faster by auto-generating fully-functional apps. These automatically-generated apps are known as **services**.
+Welcome to Amplication, a platform that helps you build critical apps faster by auto-generating fully-functional apps. These automatically-generated apps are known as [**services**](/projects-resources-services/#service).
 
-[Services](/getting-started/) include components like NestJS, Prisma, a REST API, and an Admin UI. It's a full solution complete with authentication, authorization, logging, and other essential features for back-end management. [Learn more](/getting-started/) about the details, structure, and technologies of a service.
+[Services](/getting-started/) include components like NestJS, Prisma, a REST API, and an Admin UI. It's a full solution complete with authentication, authorization, logging, and other essential features for back-end management.
+
+:::info
+Amplication also pushes the generated code of your service to [a git repository of your choosing](/sync-with-github/). Easily keep track of the code and any changes generated by Amplication.
+:::
+
+[Learn more](/getting-started/) about the details, structure, and technologies of a service.
 
 Let's get you started on creating your first service using our service creation onboarding wizard.
 

docs/getting-started/generated-app.md

@@ -1,7 +1,7 @@
 ---
 id: generated-app
 title: The Generated Service
-sidebar_label: The Generated Service
+sidebar_label: Introduction
 slug: /getting-started
 ---
 

docs/getting-started/how-prisma-schemas-are-converted-into-entities.md

@@ -0,0 +1,251 @@
+---
+id: how-prisma-schema-is-converted-into-entities
+title: How Prisma Schema Is Converted Into Amplication Entities
+sidebar_label: How Prisma Schema Is Converted Into Amplication Entities
+slug: /getting-started/how-prisma-schema-is-converted-into-entities
+pagination_prev: how-to/import-prisma-schema
+---
+
+# How Prisma Schema Is Converted Into Amplication Entities
+
+After you [import your prisma schema](/how-to/import-prisma-schema), it'll go through a series of conversions so that it matches Amplication's internal structure.
+
+These conversions are what you see in the log while your `schema.prisma` file is processing.
+
+:::note
+See the [Log Warnings](#log-warnings) section on possible warnings you might encounter while your `schema.prisma` is processing.
+:::
+
+Amplication will process your schema by running it through 3 different phases:
+
+1. Validate
+2. Prepare
+3. Convert
+
+In this article, you'll learn more about those 3 conversion steps that your schema goes through so that it matches Amplication's internal structure.
+
+### Step 1: Validate   
+
+The first validation step is performed immediately after you upload your `schema.prisma` file.
+
+The purpose of this step is to validate the structure and syntax of the `schema.prisma` file.
+This validation process is grounded in the [Prisma conventions](https://www.prisma.io/docs/reference/api-reference/prisma-schema-reference#naming-conventions) and other restrictions.
+
+Besides checking structure and syntax, the validate step also checks if the schema contains any models to process. If no models are present, you will see an error, and the conversion process will stop.
+
+### Step 2: Prepare   
+
+During the prepare phase, Amplication runs the schema through 5 different conversion operations:
+
+1. Model Names
+2. Field Names
+3. Field Types
+4. Model IDs
+5. Model ID Field
+
+Each operation represents a transformation to be made on the schema, and their collective execution ensures the schema is in the correct format before being used for Amplication’s entities and fields creation.
+
+#### Model Names
+
+This part renames models in the Prisma schema to follow Amplication's best practices and conventions.
+
+Amplication's format is model names in **PascalCase**, **no underscores**, and **singular**.
+
+All original model names are preserved in the database with the `@@map` custom attribute where necessary.
+
+:::note
+If the model already has the **`@@map`** attribute, it won’t be added, even if the model name was formatted. 
+:::
+
+Here's an example of a transformation that would happen on one model:
+
+```diff title="schema.prisma"
+-model course_rating  
++model CourseRating {
+  id        String    @id @default(cuid())
+  createdAt DateTime  @default(now())
+  updatedAt DateTime  @updatedAt
+  rating    Int      
+
++@@map("course_rating")
+}
+```
+
+#### Field Names
+
+Field names will also go through a similar conversion.
+
+Amplication's format for field names is **camelCase** and **no underscores**.
+
+It also ensures that original field names are preserved in the database by adding `@map` custom attributes where needed.
+
+:::note
+If the field already has the **`@map`** attribute, it won’t be added, even if the field name was formatted.
+:::
+
+Here's a quick example of a simple field name transformation:
+
+```diff title="schema.prisma"
+model Product {
+  id          String   @id @default(cuid())
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+  name        String?
+-item_price  Float?
++itemPrice   Float?    @map("item_price")
+  description String?
+  orders      Order[]
+}
+```
+
+#### Field Types
+
+Now that Amplication has updated both the model names and field names, it has to update the types of the fields.
+
+For example, here's how two models could see transformations:
+
+```diff name="schema.prisma"  
+-model products
++model Product {
+  id          String   @id @default(cuid())
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+  name        String?
+  itemPrice   Float?
+  description String? 
+- orders      orders[]
++ orders      Order[]
+}
+
+-model orders
++model Order {
+  id         String    @id @default(cuid())
+  createdAt  DateTime  @default(now())
+  updatedAt  DateTime  @updatedAt
+  totalPrice Int?
+- product    products?  @relation(fields: [productId], references: [id])  
++ product    Product?  @relation(fields: [productId], references: [id])
+  productId  String?
+}
+```
+
+#### Model IDs
+
+This phase converts `@@id` attributes in your models to `@@unique` attributes.
+
+It also introduces an `id` field of type `String` to every model that uses a composite ID.
+
+Here's an example of this transformation:
+
+```diff title="schema.prisma"
+model DomainUnit {
++ id       String @id @default(cuid())
+  domainId String
+  unitId   String
+
+- @@id([domainId, unitId])
++ @@unique([domainId, unitId])
+}
+```
+
+#### Model ID field  
+
+Finally, there's a conversion of all ID fields.
+
+This part ensures that your schema aligns with Amplication's conventions of having an **`id`** field for each model.
+
+non-ID fields named **`id`** are renamed to **`${modelName}Id`** to prevent any collisions with the actual ID field.
+
+If an ID field (a field with an `@id` attribute) has a different name, it's renamed to **`id`**.
+
+In both cases, a `@map` custom attribute is added to the field with the original field name to preserve the actual field name in the database.
+
+Here's an example:
+
+```diff title="schema.prisma"
+model RandomName {
+- randomId.         Int     @id  
++ id                Int     @id @map("randomId")
+- id.               Int?
++ randomNameId      Int?    @map("id")
+  fullName          String
+} 
+```
+
+### Step 3: Convert
+
+In this final step, Prisma data types get converted into Amplication data types.
+
+Here is a table summarizing the Prisma to Amplication data type conversions:
+
+| Prisma | Amplication | Description |
+|-|-|-|  
+| String (ID) | Id | Converts ID field with String type to Amplication Id type, defaults to cuid |
+| Int (ID) | Id (autoincrement) | Converts ID field with Int type to autoincrement Amplication Id |   
+| Boolean | Boolean | Same Boolean type |
+| DateTime (@default(now())) | CreatedAt | DateTime with now() default converts to CreatedAt |
+| DateTime (@updatedAt) | UpdatedAt | DateTime with updatedAt attribute converts to UpdatedAt |
+| DateTime | DateTime | Plain DateTime remains DateTime |
+| Float, Decimal | Decimal | Float and Decimal convert to Decimal |
+| Int, BigInt | WholeNumber | Int and BigInt convert to WholeNumber |
+| String | SingleLineText | String converts to SingleLineText |    
+| Json | Json | Json types are equivalent |  
+| Enum | OptionSet | Enum converts to OptionSet |
+| Enum[] | MultiSelectOptionSet | Enum array converts to MultiSelectOptionSet |
+| Model relation | Lookup | Relation to another model becomes Lookup |
+
+## Log Warnings
+
+While your `schema.prisma` file is processing you'll see various types of logs like `(Info)` and `(Warning)` giving you information on what's happening in real-time.
+
+The schema will still process with warnings, but it's possible you might want to make some changes to your schema file and re-upload after correcting the warnings.
+
+![Import Prisma Schema Upload Log](./assets/import-prisma-schema-log.png)
+
+### 1. Custom Attributes on enum keys
+
+Amplication currently does not support adding custom attributes to enum and enum keys.
+Instead, Amplication allows you to define options as an `optionSet` or `multiSelectOptionSet`.
+
+So if your Prisma schema includes `@map` or `@@map` custom attributes on an enum or enum keys, these attributes will not be accurately represented after processing.
+The final schema file will not contain these mapping attributes.  
+
+If your app logic relies on `@map` and `@@map` custom attributes, you'll need to manually adjust the generated `schema.prisma` file or your app code to ensure everything works correctly.
+
+### 2. Composite IDs on models   
+
+A model in Prisma can use the `@@id` custom attribute and combine fields to create a unique identifier for each record.
+According to Amplication's best practices, each model should have a single, distinct `id` field.
+
+During schema processing. Amplication modifies IDs created with the `@@id` custom attribute to be `@@unique` custom attributes.
+It also introduces a new `id` field of type `String` to each model.   
+
+For example, if your generated `schema.prisma` file looks like the following:
+
+```tsx title="schema.prisma"
+model Employee {
+  firstName String
+  lastName  String
+  birthdate DateTime
+
+  @@id([firstName, lastName, birthdate])
+}
+```
+
+Amplication will transform it to look like the following:  
+
+```diff title="schema.prisma"
+model Employee {
++ id String @id @default(cuid())
+  firstName String
+  lastName  String
+  birthdate DateTime
+
+- @@id([firstName, lastName, birthdate])  
++ @@unique([firstName, lastName, birthdate])
+}
+```
+
+As the schema is processed, we log warning entries if we encounter a model without an `id` field and an existing `@@id` attribute.
+
+This approach maintains uniqueness and integrity for each record in the database, but it may impact how relationships and queries are designed, given the shift from a composite id with `@@id` to a singular one.

docs/getting-started/plugins.md

@@ -1,7 +1,7 @@
 ---
 id: plugins
-title: Using Plugins
-sidebar_label: Using Plugins
+title: How To Use Plugins
+sidebar_label: Use Plugins
 slug: /getting-started/plugins
 ---
 

docs/getting-started/service-entities-roles-permissions.md

@@ -122,7 +122,7 @@ Click on `Create` and proceed to Step 3.
 1. On the _Overview_ page, click **Go to roles**, or from the main menu (left sidebar) click the **Roles** icon.
 
 :::tip
-Currently, there's only a default **User** role that was auto-generated when you created the new app.
+Currently, there's only a default **User** role that was auto-generated when you created the new service.
 :::
 
 In this example, we add another two roles: _Admin_ and _Manager_.
@@ -190,6 +190,18 @@ We will now set permissions at the field level.
 
 ![](./assets/first-app/granular-fields-2.png)
 
+### Visualize Your Entities with ERD View
+
+After you've set up your new entities, fields, and permissions, you can visualize their relationships with [Amplication's ERD view](/erd-view-for-entities).
+
+To activate the ERD view:
+
+1. Navigate back to the Entities page of your service.
+2. In the center, to the right of the search bar, you'll find a toggle switch.
+3. Activate the toggle to enable the ERD view. 
+
+![Amplication's Entity ERD View](./../how-to/assets/amplication-erd-view.png)
+
 ## Step 5 - Commit Your Changes
 
 While working in Amplication your changes are saved automatically, but are not committed. Only committed changes will be included in the next version of your generated application.
@@ -219,8 +231,16 @@ Congratulations! You've successfully set up your service, added new entities, ro
 
 ![](./assets/service-entities-roles-permissions/github-pull-request.png)
 
+:::important
+Amplication doesn't just push your service's generated code to a git repository once. It continuously keeps track of your changes and helps you manage your service through pull requests on a git provider that you choose.
+
+[Learn more](/sync-with-github/) about syncing with a git provider.
+:::
+
 ## Next Steps
 
 Now that you know how to create entities, commit changes, and build new versions, let's take it a bit further by adding another entity and learning how to compare changes before committing.
 
+You'll also learn more about how Amplication automatically tracks your code and changes in a git repository.
+
 [Building New Versions of Your Service](/building-new-versions/)