Docs: Add Custom Code Guide

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

@@ -0,0 +1,112 @@
+---
+id: add-custom-code
+title: Adding Custom Code to Your Amplication Service
+sidebar_label: Add Custom Code To Your Service
+slug: /add-custom-code-to-your-service
+---
+
+# Add Custom Code To Your Service
+
+Amplication generates a robust, production-ready backend for your app, but you'll often need to add your own custom business logic with custom code.
+In this guide you'll learn how to add custom code to your Amplication service with a simple example.
+
+## Prerequisites
+
+Before you begin, make sure you know to:
+
+1. [Create your first service](/first-service/)
+2. [Set up entities](/set-up-entities/) for your service
+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/)
+
+:::note
+For more a more in-depth explanation of how custom code works, read [Understanding Custom Code in Amplication](/custom-code-overview/).
+:::
+
+## Adding Custom Code: Retrieve The User's Full Name
+
+Let's walk through a simple example of adding custom code to your service.
+In this example, we'll add a method with custom code to get the user's full name.
+
+### Step 1: Create A New Feature Branch
+
+Ensure that your local repository is up-to-date with the latest Amplication-generated code:
+
+```bash
+git checkout main && git merge amplication && git push
+```
+
+Next, create a new branch from the main branch to make your custom code changes:
+
+```bash
+git checkout -b feature/user-full-name
+```
+
+### Step 2: Locate the Correct File
+
+Navigate to the code of your generated service's `src` folder and find the `user` folder:
+
+```
+src
+└── user
+    ├── base
+    │   ├── user.controller.base.ts
+    │   ├── user.service.base.ts
+    │   └── ...
+    ├── user.controller.ts
+    ├── user.module.ts
+    ├── user.resolver.ts
+    └── user.service.ts
+```
+
+We'll modify the `user.service.ts` to add our custom functionality.
+
+:::tip
+Notice that we're adding our changes to `user.service.ts` instead of `base/user.service.base.ts` file.
+To learn more why we recommend doing this, read [Understanding Custom Code in Amplication](/custom-code-overview/).
+:::
+
+### Step 3: Add Custom Logic to the Service
+
+Open `src/user/user.service.ts`. This file extends the base service and is where we'll add our custom method that retrieves the user's full name.
+
+```typescript
+import { Injectable } from "@nestjs/common";
+import { UserServiceBase } from "./base/user.service.base";
+
+@Injectable()
+export class UserService extends UserServiceBase {
+  async getUserFullName(userId: string): Promise<string> {
+    const user = await this.findOne({ where: { id: userId } });
+    return `${user.firstName} ${user.lastName}`;
+  }
+}
+```
+
+Note how it uses the `findOne` method from the base service.
+
+### Step 4: Push Your Changes
+
+After adding your custom code, commit the changes to the git feature branch you created in Step 1:
+
+```bash
+git add .
+git commit -m "Added full name functionality"
+git push origin feature/user-full-name
+```
+
+After going through any review process, merge the feature branch into your working branch:
+
+```bash
+git checkout main && git merge feature/user-full-name && git push
+```
+
+## Next Steps
+
+Now that you know how to add custom code to your Amplication service, you can:
+
+- Implement complex business logic specific to your application
+- Create custom utilities and helpers
+- Integrate with external services or APIs
+- Implement advanced validation and data processing

docs/getting-started/generated-app.md

@@ -95,4 +95,5 @@ For Node.js services, the Admin project provides a React application with ready-
 
 ## Learn more
 
-- [How to add custom code to your application](/how-to/custom-code)
+- [Understanding Custom Code in Amplication](/custom-code-overview/)
+- [Add Custom Code To Your Service](/add-custom-code-to-your-service)

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,95 @@
 ---
-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.
+Amplication allows seamless integration of your custom code with generated code through our [Smart Git Sync](/smart-git-sync) feature.
+This lets you add custom business logic while continuing to use Amplication to update your data models, permissions, roles, plugins, and more.
 
-## The Vision
+This guide is an in-depth explanation on how custom code works in your Amplication project.
 
-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.
+## How Custom Code Integration Works
 
-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.
+1. Amplication uses a specific folder structure to manage base and non-base files.
+2. The `base` folder contains generated files that will get updates only if there are relevant changes (e.g., you add a new plugin).
+3. Non-base files are intended for custom code.
+4. Amplication will make necessary changes to both base and non-base files (e.g., updating interfaces, removing references to deleted plugins) while always preserving and respecting your custom code.
 
-:::info
-This document describes the method to customize the server code only.
-
-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.
-
-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.
+:::tip
+While you can add custom code to _all files_, we recommend primarily adding custom code to non-base files (e.g., `user.service.ts` instead of `user.service.base.ts`) for easier maintenance.
 :::
 
-## 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
+## Folder Structure
 
-Each entity has a dedicated folder under the 'src' folder.
-For example:
+Each entity has a dedicated folder under the `src` folder:
 
 ```
 └── 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:
+### Base files
 
-- 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".
+**Base files**: Located in the `base` folder, these are automatically generated by Amplication.
 
-- 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.
+### Non-base Files
+
+**Non-base files**: These inherit from the base files and are intended for your custom code. 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
+Your custom code, whether it's in base or non-file files, is always preserved and respected across builds.
+
+## Smart Git Sync
+
+Amplication uses [Smart Git Sync](/smart-git-sync/) to seamlessly integrate changes, preserving your custom code while updating the generated parts. This feature:
+
+Makes necessary updates to both base and non-base files (e.g., updating interfaces, removing references to deleted plugins) while respecting your custom code.
+
+:::note
+For a more in-depth explanation, please read the [Smart Git Sync](/smart-git-sync) page.
+:::
+
+## Best Practices for Custom Code
+
+When adding custom code to your Amplication service, keep these best practices in mind:
+
+1. Use types and interfaces generated by Amplication to ensure type safety.
+2. Leverage existing services and utilities provided by Amplication.
+3. Create a new feature branch for significant custom code changes.
+4. Regularly pull and merge the latest Amplication-generated code from the `amplication` branch into your working branch (e.g., `main`).
 
-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.
+## How To Handle Conflicts
 
-- _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.
+While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. 
 
-## Examples
+If conflicts arise during this process, you'll need to resolve them manually in the `amplication` branch before merging into your main branch.
 
-Following are some examples of how to add custom code in different layers of the application.
+1. Amplication will provide clear indications of the conflicting areas using git diffs in your chosen git provider.
+2. You'll need to manually resolve these conflicts in the `amplication` branch.
+3. After resolving conflicts, merge the updated `amplication` branch into the main branch.
 
-The purpose of these examples is to get familiar with the layers' structure and the responsibility of each of the components in the server.
+## Next Steps
 
-- [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)
+Now that you understand how custom code works in Amplication, you're ready to start adding your own business logic.
+For a step-by-step guide, check out our [How To Add Custom Code To Your Service](/add-custom-code-to-your-service) guide.

docusaurus.config.js

@@ -198,6 +198,10 @@ module.exports = {
       "@docusaurus/plugin-client-redirects",
       {
         redirects: [
+          {
+            to: "/add-custom-code-to-your-service",
+            from: ["/how-to/custom-code/"]
+          },
           {
             to: "/plugins/guides/authentication",
             from: ["/authentication-plugin-examples"]

sidebars.js

@@ -28,7 +28,7 @@ const sidebars = {
           type: "doc",
           id: "plugins/private-plugins",
           label: "Private Plugins",
-        },
+        }
       ],
     },
     {
@@ -40,9 +40,12 @@ const sidebars = {
       },
       items: [
         "getting-started/generated-app",
-        "getting-started/service-building-new-versions",
+        "getting-started/commit-changes-and-build-new-versions",
+        "getting-started/add-custom-code",
+        // "getting-started/service-building-new-versions",
+        "how-to/custom-code-overview",
         "getting-started/view-generated-code",
-        "how-to/add-custom-code",
+        // "how-to/add-custom-code",
         "getting-started/authentication",
         "concepts/event-driven-architecture",
         {