Making A Full Stack Change To The Project

Our objective for this guide is to add a small feature to the project which will require changes to both the Frontend and Backend to successfully work. We will use a toy example of a "song"; however, feel free to try adding your own concept.

The code for this example can be found on the onboarding/song-example branch

Prerequisites

• Ensure that you are able to pull the codebase down and run it. Follow the instructions here.

Making A Backend Change

To start, we first have to perform a modification to the Backend to add the concept of a "song" to the project and have it persist in the system. This requires edits to the libs/shared folder and libs/server folders and you will need to how to use typeorm, @orcha, and nestjs.

Setup Song Data Models

1. In the libs/shared/domain/src/lib/domain directory, mkdir song && cd song to create the directory which houses our song model files

2. In the song directory create a Song interface (defines what a Song will look like)

3. In the song directory create Song DTO models. These define what the parameters are for Song Backend operations, you should have one for each of the operations you expect would be performed on the Song model.

4. In the song directory create a Song query to define what data will be fetched during Song Backend operations

5. In the song directory create a SongOrchestration interface (defines the operations that Backend/Frontend can use and their associated input & outputs)

6. In the song directory create an index.js to export created files and register the song with the parent directory libs/shared/domain/src/lib/domain

Register Song With Backend

1. In the libs/server/core/domain-services/src/lib/ directory, mkdir song && cd song to create the directory which houses our Song backend files

2. In the song directory create a SongEntity. This is used to map the Song data model to the Backend database for storing purposes.

3. In the song directory use the SongEntity to create a SongRepository. This is the database table where the Song objects will be stored.

4. In the parent directory (libs/server/core/domain-services/src/lib/) register SongEntity and Repository with "server-core-domain-services-module.ts"

Implement Server Orchestration

1. In the libs/server/core/application-services/src/lib, mkdir song && cd song to create the directory which houses the Backend Song business logic.

2. In the Song directory create a SongService to handle the logic for Song backend operations

3. In the parent directory (libs/server/core/application-services/src/lib) register the SongService with "server-core-application-services.module.ts"

4. In the libs/server/orcha/src/lib, mkdir song && cd song to create the directory which houses the Backend implementation of Song Orchestration

5. In the Song directory, implement SongOrchestration using the required Backend application services

6. In the parent directory (libs/server/orcha/src/lib) register with "server-orcha.module.ts"

Testing Changes

1. Run npx ng s api after starting PostgreSQL service

2. Validate that project registers the SongOrchestration

3. Use PGAdmin or PSQL to validate that a PostgreSQL table has been generated with appropriate fields

If the changes have been validated, then you are ready to move onto the Frontend to allow users to interact with these Backend changes.

Making A Frontend Change

Now we want to perform a modification to the Frontend to allow the Frontend to call the Backend service using the @orcha RPC mechanism. This requires edits to the libs/client/ directory and we will need to use Angular, @orcha, and nx to succeed.

Register Song with Frontend

1. In the libs/client/shared/data-access/src/lib/orchestrations directory, we need to implement the SongOrchestration interface (defined in the Backend steps) for the client

2. In the parent directory (libs/client/shared/data-access/src/lib/), we need to register the Client SongOrchestration implementation with "client-shared-data-access.module.ts"

Create Frontend Song Library

1. Create a new nx library project with nx g lib songs --directory=client in the main directory of the project

2. cd libs/client/song/src/lib and create an Angular component with ng g c create-song

3. Edit the file "create-song.component.ts" and make it look similar to "forget-password.component.ts" by having a form for song values with a submit button.

4. Edit the file "create-song.component.html" to allow the client to use the form

5. Edit the overall "client-song.module.ts" file generated by nx to add appropriate imports and routes used by the create-song component

6. Edit the "im-routes.ts" file in libs/shared/domain/src/lib/routes to add new Song library to Frontend

7. Edit the "client-shell.module.ts" file in libs/client/shell/src/lib to register Song routes to the Client Frontend

Testing

1. Run npx ng s and npx ng s api in separate terminals

2. Navigate the songs route (localhost:4202/songs) and check create-song form appears

3. Test the ability to insert songs into the form

4. Double check with PGAdmin or PSQL that updates are persisted in the PosgreSQL

Now we are done and have created a project-wide code change using the Frontend and Backend!