(docs): Updating the previous Custom Code page into a newer and more …

…clear Understanding Code Code page that explains the philosophy and goes into the modifications that might happen to non-base files.

docs/getting-started/view-generated-code.md

@@ -1,11 +1,11 @@
 ---
 id: view-generated-code
 title: Viewing the generated code
-sidebar_label: View the generated code
+sidebar_label: Code View Explained
 slug: /getting-started/view-generated-code
 ---
 
-# Viewing the Generated Code
+# Code View Explained
 
 Use **Code View** to view and explore the generated code. You can see the updated code before it is synced with GitHub or downloaded.
 

docs/how-to/add-custom-code.md

@@ -1,95 +1,78 @@
 ---
-id: add-custom-code
-title: How to add custom code to your services
-sidebar_label: Add custom code to your services
-slug: /how-to/custom-code
+id: custom-code-overview
+title: Understanding Custom Code in Amplication
+sidebar_label: Understanding Custom Code
+slug: /custom-code-overview
+pagination_next: getting-started/add-custom-code
 ---
 
-# Add custom code to your services
+# Understanding Custom Code in Amplication
 
-Although your application built with Amplication is fully functional and you can start using it as it was shipped, you probably want to add your core business logic and other functionality to your server.
+This page provides an overview of how custom code works in Amplication and our vision for seamless integration between generated and custom code.
 
 ## The Vision
 
-Our vision is that you will be able to add custom code to the server while keeping the ability to work on Amplication to update your data model, change permissions, add roles, and more.
+Our vision is to empower you to add custom code to your server while maintaining the ability to use Amplication for updating your data model, changing permissions, adding roles, and more. Amplication achieves this by merging changes via our [Smart Git Sync](/smart-git-sync/) feature, based on pre-defined policies that allow you to add and update services, controllers, resolvers, and more without losing the link to Amplication. This approach gives you the freedom and power of custom code while saving time on repetitive tasks.
 
-To do so, Amplication will merge changes via Git, based on pre-defined policies that will allow you to add and update services, controllers, resolvers, and more without losing the link to Amplication. You will have the freedom and power of code while saving time on repetitive tasks with Amplication.
+## How It Works
 
-:::info
-This document describes the method to customize the server code only.
+Your Amplication-generated application is structured to allow easy and maintainable customization, with a clear separation between customizable and non-customizable code.
 
-Customizing the client application (Admin UI) code is not supported. You can use the generated client application as a boilerplate and keep developing it, but Amplication will not be able to merge your code changes with the newly generated code.
+### Folder Structure
 
-In case you decide to customize the client application, it is recommended to first clone the entire **Admin** folder to a separate folder or a separate repository and work on the cloned code instead of the original folder.
-:::
-
-## How it works
-
-Your server application is created with a folder structure that allows easy and maintainable customization and development, with a clear separation between customizable code and non-customizable code.
-
-### The 'entity' folder
-
-Each entity has a dedicated folder under the 'src' folder.
-For example:
+Each entity has a dedicated folder under the 'src' folder, containing all necessary modules and files:
 
 ```
 └── src
-	├── customer
-	├── user
-	├── project
-	└── task
+    ├── customer
+    ├── user
+    ├── project
+    └── task
 ```
 
-The entity folder contains all the modules and files required to work with a specific entity, i.e. GraphQL resolver, REST API controller, service, and DTOs.
+Within each entity folder, files are split into two groups:
 
-The files are split into two groups:
+1. **Base files**: Located in the 'base' folder, these are automatically generated by Amplication with every change. They should not be altered as they will be overwritten.
 
-- Base files - the base files are the ones that are automatically generated by Amplication with every change. These files should not be altered or customized as they will be overwritten and the changes will not be preserved. All the base files exist in a separate folder named "base".
-
-- Customizable files - the customizable files inherit from the base files and they can be customized and will never be overwritten by Amplication. All the customizable files reside directly in the entity folder and can be freely customized and altered.
+2. **Non-base Customizable files**: These inherit from the base files and can be safely customized. They reside directly in the entity folder.
 
 ```
 src
 └── Customer
     ├── Base
-    │    ├── CreateCustomerArgs.ts
-    │    ├── CustomerFindManyArgs.ts
-    │    ├── CustomerFindUniqueArgs.ts
-    │    ├── customer.controller.base.spec.ts
     │    ├── customer.controller.base.ts
-    │    ├── customer.resolver.base.ts
     │    ├── customer.service.base.ts
-    │    ├── customer.ts
-    │    ├── CustomerCreateInput.ts
-    │    ├── CustomerUpdateInput.ts
-    │    ├── CustomerWhereInput.ts
-    │    ├── CustomerWhereUniqueInput.ts
-    │    ├── DeleteCustomerArgs.ts
-    │    └── updateCustomerArgs.ts
-    ├── customer.controller.spec.ts
+    │    └── ...
     ├── customer.controller.ts
-    ├── customer.module.ts
-    ├── customer.resolver.ts
-    └── customer.service.ts
-
+    ├── customer.service.ts
+    └── ...
 ```
 
-### The 'base' folder
+Amplication may still update the non-base files that include your custom code in certain circumstances. These updates are limited to changes necessary for preventing errors and ensuring the project can build correctly. For example, if you remove a plugin that was previously used in your service, Amplication might update the non-base files to remove references to the removed plugin, thus preventing build errors.
+
+This approach allows Amplication to maintain the integrity of your project structure while still preserving your custom code to the greatest extent possible.
+
+## Amplication's Approach to Custom Code
+
+Amplication is designed to preserve your custom code while allowing for continuous updates to the generated code. Here's how it works:
+
+1. **Initial Generation**: Amplication generates both base and customizable files for each module.
+
+2. **Subsequent Updates**: When you make changes in Amplication (e.g., updating the data model), it regenerates the base files and updates the customizable files as needed.
+
+3. **Smart Merging**: Amplication uses [Smart Git Sync](/smart-git-sync/) to merge changes, preserving your custom code while updating the generated parts.
+
+4. **Conflict Resolution**: If conflicts arise, Amplication provides clear indications and allows you to resolve them manually.
 
-The base folder contains all the base files that are automatically generated by Amplication with every change. These files should not be altered or customized as they will be overwritten and the changes will not be preserved.
+This approach allows you to freely add custom business logic, new endpoints, or any other customizations while still benefiting from Amplication's code generation and updates.
 
-- _entity_.ts - the entity model class with all the model's properties
-- _entity_.service.base.ts - the base service that wraps the Prisma client with all the CRUD operations on the entity.
-- _entity_.controller.base.ts - the base REST API controller that provides all the CRUD operations on the entity.
-- _entity_.resolver.base.ts - the base GraphQL resolver that provides all the queries and mutations on the entity.
-- DTOs - Args and Input classes that are used for transferring data to and from the controller and resolver.
+## Considerations
 
-## Examples
+- Customizing the client application (Admin UI) code is not currently supported within Amplication's regeneration process. If you need to customize the client, it's recommended to clone the entire **Admin** folder to a separate repository.
+- While Amplication strives to maintain compatibility, major changes to your data model or entity structure may require manual updates to your custom code.
 
-Following are some examples of how to add custom code in different layers of the application.
+## Next Steps
 
-The purpose of these examples is to get familiar with the layers' structure and the responsibility of each of the components in the server.
+Now that you understand how custom code works in Amplication, you're ready to start adding your own business logic and customizations. For a step-by-step guide on how to add custom code to your service, check out our [How To Add Custom Code To Your Service](/getting-started/add-custom-code) guide.
 
-- [Example: How to add business logic to a service](/custom-code/business-logic)
-- [Example: How to add an action to a REST API controller](/custom-code/controller-action)
-- [Example: How to add a query to a GraphQL resolver](/custom-code/graphql-query)
+Happy coding!

sidebars.js

@@ -27,6 +27,7 @@ const sidebars = {
       items: [
         "getting-started/generated-app",
         // "getting-started/service-building-new-versions",
+        "how-to/custom-code-overview",
         "getting-started/view-generated-code",
         // "how-to/add-custom-code",
         "getting-started/authentication",