(docs): Re-writing the original understanding custom code page. Fixin…

…g the link on the new guide.

docs/getting-started/add-custom-code.md

@@ -18,7 +18,6 @@ Before you begin, make sure you know to:
 3. [Configure roles and permissions](/configure-roles-and-permissions/)
 4. [Add plugins to your service](/add-plugins-service/)
 5. [Commit changes and build a new version](/commit-and-build-new-versions/)
-6. Read the [Understanding Custom Code in Amplication](/how-to/custom-code/) document
 
 ## Understanding Custom Code in Amplication
 
@@ -30,6 +29,10 @@ Amplication is designed to allow seamless integration of custom code with genera
 4. Files outside the `base` folder are intended for your custom code and are preserved across builds.
 5. Amplication uses [smart merging](/smart-git-sync) to update your project while preserving your custom code.
 
+:::note
+For more a more in-depth explanation, read [Understanding Custom Code in Amplication](/custom-code-overview/)
+:::
+
 ## How Amplication Handles Custom Code
 
 Amplication preserves your custom code during updates:

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

@@ -8,19 +8,19 @@ pagination_next: getting-started/add-custom-code
 
 # Understanding Custom Code in Amplication
 
-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 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.
+Amplication allows seamless integration of custom code with generated code, empowering you to add custom business logic while continuing to use Amplication for updating your data model, permissions, roles, and more.
 
 ## How It Works
 
-Your Amplication-generated application is structured to allow easy and maintainable customization, with a clear separation between customizable and non-customizable code.
+Amplication uses a specific folder structure and smart merging using [Smart Git Sync](/smart-git-sync) to manage custom and generated code:
+
+1. All code in your Amplication project can be customized.
+2. Amplication generates a folder structure that separates base files from non-base files intended for custom code.
+3. Updates to your Amplication configuration regenerate base files while preserving your custom code.
 
 ### Folder Structure
 
-Each entity has a dedicated folder under the 'src' folder, containing all necessary modules and files:
+Each entity has a dedicated folder under the `src` folder:
 
 ```
 └── src
@@ -32,9 +32,9 @@ Each entity has a dedicated folder under the 'src' folder, containing all necess
 
 Within each entity folder, 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 with each new build**.
+1. **Base files**: Located in the 'base' folder, these are automatically generated by Amplication with every build. While these can be modified, changes to these files may be lost in subsequent builds.
 
-2. **Non-base Customizable files**: These inherit from the base files and can be safely customized with your custom code. They reside directly in the entity folder.
+2. **Non-base files**: These inherit from the base files and are intended for your custom code. They reside directly in the entity folder and your custom code is preserved across builds.
 
 ```
 src
@@ -48,31 +48,39 @@ src
  └── ...
 ```
 
-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.
+## Smart Git Sync
 
-## Amplication's Approach to Custom Code
+Amplication uses [Smart Git Sync](/smart-git-sync/) to merge changes, preserving your custom code while updating generated parts. This feature:
 
-Amplication is designed to preserve your custom code while allowing for continuous updates to the generated code. Here's how it works:
+1. Regenerates base files with each build.
+2. Preserves non-base files containing your custom code.
+3. Makes necessary updates to non-base files (e.g., removing references to deleted plugins) while maintaining your custom code.
 
-1. **Initial Generation**: Amplication generates both base and customizable files for each module.
+## Best Practices for Custom Code
 
-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.
+1. Add custom code to non-base files (e.g., `user.service.ts` instead of `user.service.base.ts`).
+2. Use types and interfaces generated by Amplication to ensure type safety.
+3. Leverage existing services and utilities provided by Amplication.
+4. Document your custom code thoroughly.
+5. Create a new branch for significant custom code changes.
+6. Regularly pull and merge the latest Amplication-generated code into your working branch.
 
-3. **Smart Merging**: Amplication uses [Smart Git Sync](/smart-git-sync/) to merge changes, preserving your custom code while updating the generated parts.
+## Handling Conflicts
 
-4. **Conflict Resolution**: If conflicts arise, Amplication provides clear indications and allows you to resolve them manually.
+While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:
 
-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.
+1. Amplication will provide clear indications of the conflicting areas.
+2. You may need to manually resolve these conflicts, merging your custom code with the updated generated code.
+3. After resolving conflicts, thoroughly test your application to ensure everything works as expected.
 
 ## Considerations
 
-- 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.
+- While all code can be customized, we recommend focusing custom code in the non-base files for easier maintenance.
+- Major changes to your data model or entity structure may require manual updates to your custom code.
+- Client-side customization (Admin UI) is supported, but changes may not be automatically merged in future builds. Consider maintaining a separate repository for extensive client-side customizations.
 
 ## Next Steps
 
-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](/add-custom-code-to-your-service) guide.
+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, check out our [How To Add Custom Code To Your Service](/add-custom-code-to-your-service) guide.
 
-Happy coding!
+Happy coding!