# OpenSlice TMF Web UI

This document serves as the primary reference for setting up, configuring, and running the TMF Web UI, an Angular application that consumes the TMF API.

## Requirements

To ensure a consistent development environment and avoid compatibility issues, please use the following versions for the main tools.



| Tool                           	| Version   	| Notes                                                               	|   	
|--------------------------------	|-----------	|---------------------------------------------------------------------	|
| **Node Version Manager (nvm)** 	| Latest    	| Recommended for managing Node versions. [Guide](https://www.freecodecamp.org/news/node-version-manager-nvm-install-guide/) |
| **Node.js**                    	| `18.20.8` 	| Managed via `nvm`. Use `nvm install 18.20.8` and `nvm use 18.20.8`. 	|
| **Angular CLI**                	| `14.x.x`  	| Install globally using `npm install -g @angular/cli@14`.            	|   

## Configuration

Configuration files allow customization of the application's behavior, styling, and appearance without altering the core codebase.

All primary configuration files are located in the following directory:

`./src/assets/config/`

The configuration files for the end to end testing are located in the following directory:
`./cypress/`

### Default Configuration Files (Templates)

The following files serve as templates for customizing the environment:

| Filename                           	| Purpose   	| Description                                               |  Location                	|   	
|--------------------------------	|-----------	|---------------------------------------------------------------------	| ------------- 
| `config.prod.default.json` 	| **API & Basic Info**    	| Contains core application information, environment variables, and essential API endpoint configurations for the production environment.                             	|  `./src/assets/config/`
| `theming.default.scss`                    	| **CSS Theming** 	| Defines the SCSS variables for the application's color palette |  `./src/assets/config/`
| `config.theming.default.json`       	| **HTML Configuration**	| Contains configurations for static UI elements like the application Logo URL, Favicon path, and dynamic content for the Footer.            	|   `./src/assets/config/`
|  `default.env`      |  **E2E Testing**    |  Contains default environment variables required for running Cypress End-to-End tests.  |  `./cypress/`






### Configuration Setup (Mandatory Renaming)

Before running or building the project, you **must** create copies of the template files, removing the `.default` suffix, as these are mandatory for the application to properly load its settings.

The resulting files required for initial setup are:

| Filename                           	| Status | Purpose                                                               	|  Location    	
|--------------------------------	|-----------	|---------------------------------------------------------------------	| --------- |
| `config.prod.json` 	| **Mandatory**    	| The application's main configuration. (Copy of `config.prod.default.json`)      	|  `./src/assets/config/`
| `theming.scss`                    	| **Mandatory** 	| The primary SCSS theming file. (Copy of `theming.default.scss`) |  `./src/assets/config/`
| `config.theming.json`       	| _Optional_	| HTML configuration for branding. (Copy of `config.theming.default.json`)    	|  `./src/assets/config/` 
|  `.env`  | **Mandatory (for testing)**  |  The active environment configuration for Cypress. (Copy/Rename of default.env)  | `./cypress/`



## Serving the Application

To run the application locally, ensure you have completed the **Configuration Setup**

### Initial Setup (Dependencies)

First, install the necessary project dependencies:

```
npm i
```

This command downloads all dependencies defined in `package.json` and `package-lock.json`.

### A. Production/Default Serve (AOT)

This method uses **Ahead-of-Time (AOT)** compilation, which pre-compiles Angular templates into JavaScript during the build process. This is often used for final checks and mimics the production build process.

To run:

```
ng serve --configuration production
```

Once compiled, open your browser and navigate to: [http://localhost:4200](https://www.google.com/search?q=http://localhost:4200 "null")

### B. Development Serve (JIT)

For active development, using **Just-in-Time (JIT)** compilation is strongly encouraged. JIT compiles templates in the browser at runtime, resulting in significantly faster build times and rapid live reloads after code changes.

1.  **Create Development Config:** To use this mode, you must first create a specific development configuration file:
    
    ```
    cp src/assets/config/config.prod.json src/assets/config/config.dev.json
    ```
    
2.  **Run JIT Serve:** Execute the serve command using the new development configuration:
    
    ```
    ng serve --configuration development
    ```
    

**Important Development Note:** While JIT mode is great for iteration speed, AOT compilation runs a more comprehensive check. After development and before committing, it is highly recommended to perform at least one test run using the AOT configuration (`ng serve --configuration production`) to ensure no template or dependency issues are present in the full build.

## Building the Project

To create a deployable package containing optimized JavaScript, CSS, and HTML assets, use the build command.

### Build Command (Production)

Assuming all configurations are set and dependencies are installed (`npm i`), execute:

```
ng build --configuration production
```

### Output

The compiled, production-ready assets will be generated in the `/dist` directory within the project root. This directory contains the static files ready for deployment on any web server.

## Running Tests (Cypress)

This project uses Cypress for End-to-End (E2E) testing.

### Prerequisites
*Environment Variables*: Ensure you have created the `.env` file in the `./cypress/` directory as specified in the **Configuration Setup** table above.

### Interactive Mode (Test Runner)
Use this mode for developing tests. It opens the Cypress Test Runner UI, allowing you to select and watch tests run in a real browser

```
npm run cy:open
```
1. Select E2E Testing.
2. Choose your preferred browser (e.g. Chrome, Electron).
3. Click on a spec file (e.g. auth.cy.ts) to run it.

### Headless Mode
Use this mode to run all tests in the terminal without opening a browser window.
```
npm run cy:run
```