LATAM Angular Frontend Template

Purpose and Scope

This project is a base template for frontend applications developed with Angular at LATAM. Its purpose is to provide a robust, preconfigured project structure that accelerates the start of new development and ensures consistency and adherence to LATAM standards.

Primary Objectives:

• Provide a foundation with Angular (currently focused on Angular 17+).
• Preconfigured integration with Microsoft Azure Active Directory (Azure AD) and Azure B2C for authentication and authorization via MSAL (Microsoft Authentication Library).
• Support for internationalization (i18n) with @ngx-translate.
• Inclusion of Angular Material for UI components.
• Configuration for Progressive Web Apps (PWA).
• Structure for unit tests (Karma/Jasmine) and E2E/automated tests (WebDriverIO).
• Guides and configurations for deployment on GKE (Google Kubernetes Engine) via Jenkins.

Scope:

• Generation of the base Angular project structure.
• Configuration of development, build, and testing tools.
• Authentication mechanisms and session management.
• Examples of common components and services (navigation, layout, HTTP error handling).
• CI/CD pipeline for deployment on GKE.

Out of Scope (to be implemented by the development team):

• Application-specific business logic.
• Detailed UI/UX design beyond base Material components.
• Connections to specific backend APIs (although an HTTP interceptor is provided).

Architecture

The template follows the standard architecture of an Angular application, based on components, modules, and services.

• Presentation: Angular components and Angular Material.
• Application Logic/Services: Angular services for UI logic, simple state management, and communication with the backend.
• Authentication: Integration with Azure AD/B2C using MSAL Angular (MsalGuard, MsalInterceptor).
• Internationalization: ngx-translate for multiple languages.
• Web Server (in deployment): Nginx serves the built static application.

Development teams are encouraged to maintain application-specific architecture diagrams derived from this template.

• General Architecture Diagram: [Link to diagram if available, or placeholder]
• Authentication Flow Diagram: [Link to diagram if available, or placeholder]

Technologies and Dependencies

Frontend:

• Language: TypeScript (~5.7.3)
• Main Framework: Angular (~17.x / ~19.x per package.json, with Angular 17 support confirmed in CHANGELOG.md)
• UI Components: Angular Material (~19.x)
• State Management/Reactivity: RxJS (~7.8.0)
• Internationalization (i18n): @ngx-translate/core (~14.0.0), @ngx-translate/http-loader (~7.0.0)
• Authentication: @azure/msal-angular (~3.0.20), @azure/msal-browser (~3.17.0)
• PWA: @angular/service-worker

Development and Tools:

• CLI: Angular CLI (@angular/cli ~19.x)
• Package Manager: npm
• Development Server: ng serve (webpack dev server)
• Unit Tests: Karma, Jasmine
• E2E/Automated Tests: WebdriverIO (@wdio/cli, @wdio/cucumber-framework)
• Code Quality: SonarQube (implicit via sonar-scanner and sonar script)

Deployment and Operations:

• Containerization: Docker
• Web Server (Production): Nginx (base image redhat_ubi_8_nginx_1)
• Orchestration: Google Kubernetes Engine (GKE)
• CI/CD: Jenkins (pipelineLatam("gke-krane-angular"))
• Artifacts: JFrog Artifactory (for corporate npm dependencies)

Local Setup

Prerequisites

• Node.js (LTS version recommended, compatible with the Angular version)
• npm (usually bundled with Node.js)
• Angular CLI: npm install -g @angular/cli
• Git
• Access to LATAM JFrog Artifactory.

Setup Steps

1. Clone the repository: Follow these steps

2. Configure Artifactory NPM registry:

   npm config set registry https://artifactoryrepo1.appslatam.com/artifactory/api/npm/corp-libs-npm-release/

   You may need to run npm login if this is your first time, entering your Artifactory credentials.

3. Install dependencies:

   npm install

4. Configure MSAL for local development (Azure AD or B2C):

   • For Azure AD: Copy src/assets/configuration-localhost.json to src/assets/config/configuration.json.
   • For Azure B2C: Copy src/assets/configuration-b2c-localhost.json to src/assets/config/configuration.json.
   • Modify src/assets/config/configuration.json with the correct values for your application (clientId, authority, redirectUri, etc.). This file (src/assets/config/configuration.json) is in .gitignore and must not be committed to the repository with real credentials/configurations.

   Example of src/assets/config/configuration.json (for Azure AD):

   {
     "storage": {
       "azure_use_redirect": 0, // 0 for popup, 1 for redirect
       "server_url": "https://tu-api-backend.com" // URL of your backend if applicable
     },
     "msal": {
       "auth": {
         "clientId": "TU_CLIENT_ID_AZURE_AD",
         "authority": "https://login.microsoftonline.com/TU_TENANT_ID",
         "redirectUri": "http://localhost:4200/"
       },
       "cache": {
         "cacheLocation": "localStorage", // or "sessionStorage"
         "storeAuthStateInCookie": false
       }
     },
     "guard": {
       "interactionType": "redirect", // or "popup"
       "authRequest": {
         "scopes": ["user.read", "directory.read.all"], // Required scopes
         "prompt": "select_account"
       }
     },
     "interceptor": {
       "interactionType": "redirect", // or "popup"
       "protectedResourceMap": [
         ["https://graph.microsoft.com/v1.0/me", ["user.read"]],
         ["URL_DE_TU_API_PROTEGIDA", ["SCOPE_DE_TU_API"]]
       ]
     }
   }

5. Run the application in development mode:

   ng serve

   The application will be available at http://localhost:4200/.

Deployment

Deployment is managed through Jenkins pipelines and Krane for GKE.

General Deployment Process (Manual/Initial Setup)

1. Collocated Design (JIRA): Create a JIRA issue to request resources (repositories, pipelines, Azure AD/B2C configuration).
2. Prepare Code: Use this template as the base for the new project.
3. Push to Repository: Upload the code to the provided repository.
4. Configure Ingress (GKE): Edit the deployment.yaml.erb file in the gke-resources repository (the specific path will be provided) to add the service route. Example:

   - path: /mi-aplicacion # Adjust the path
     pathType: Prefix
     backend:
       service:
         name: <%= owner_name %>-{nombre_repo}-service
         port:
           number: 80

5. Customize Environment Values (Optional): Modify deploy/env/<entorno>.yaml (e.g. dev.yaml) to add specific variables that will be injected into configuration.json during deployment.

   steps_test: false
   steps_automated_test: false
   dns_record: "mi-app.dev.appslatam.com"
   # Custom variables
   mi_variable_custom: "valor_custom"
   azure_client_id: "client_id_para_este_entorno" # Override if necessary

6. Customize deployment.yaml.erb (Optional): If more configuration parameters are needed in assets/config/configuration.json or assets/config/configuration_b2c.json that are injected from deploy/env/<entorno>.yaml files, modify the ConfigMap section in deploy/gke/deployment.yaml.erb. Example of the ConfigMap section in deployment.yaml.erb for configuration.json:

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: "<%= owner_name %>-<%= repository_name %>-settings"
   data:
     configuration.json: |-
       {
         "storage": {
           "azure_use_redirect": <%= azure_use_redirect_storage_value %>, // Uses environment.yaml variables
           "server_url": "https://<%= dns_record %>",
           "key1": "<%= key1_value %>" // Example custom value
         },
         "msal": {
           "auth": {
             "clientId": "<%= azure_client_id %>",
             "authority": "<%= azure_authority %>",
             "redirectUri": "https://<%= dns_record %>"
           },
           // ... more msal configuration
         },
         // ... more guard/interceptor configuration
       }

Jenkins Pipeline

• The Jenkinsfile at the project root defines the pipeline:

  pipelineLatam("gke-krane-angular")

• When pushing to the configured branch (e.g. dev, main), Jenkins is triggered automatically, builds the Docker image, and deploys it to GKE.

API Endpoints

This is a frontend application and does not expose API endpoints. It consumes backend APIs. Configuration for interacting with protected APIs is managed through the MsalInterceptor and the protectedResourceMap in assets/config/configuration.json.

Specific Components

Authentication (MSAL - Azure AD / B2C)

• Key Modules: @azure/msal-angular, @azure/msal-browser.
• Dynamic Configuration: MsalConfigDynamicModule (src/app/msal-config-dynamic.module.ts) loads the MSAL configuration from assets/config/configuration.json (or configuration_b2c.json) at application startup. This allows different MSAL configurations per environment without recompiling.
• Configuration Files:
  • src/assets/config/configuration.json: For Azure AD.
  • src/assets/config/configuration_b2c.json: For Azure B2C.
  • src/assets/configuration-localhost.json: Template for local config with Azure AD.
  • src/assets/configuration-b2c-localhost.json: Template for local config with Azure B2C.
• Important Configuration Variables (in configuration.json / configuration_b2c.json):
  • msal.auth.clientId: Client ID of the application registered in Azure.
  • msal.auth.authority: URL of the token-issuing authority (e.g. https://login.microsoftonline.com/TENANT_ID for AD, or https://{b2cDomain}.b2clogin.com/{b2cDomain}.onmicrosoft.com/{policyName} for B2C).
  • msal.auth.redirectUri: URI to which Azure redirects after authentication.
  • msal.auth.knownAuthorities (for B2C): Array with B2C authority domains. E.g. ["latamb2c.b2clogin.com"].
  • storage.B2C: "1" if Azure B2C is used, "0" or absent for Azure AD. Determines which configuration is used.
  • storage.azure_use_redirect: "1" for redirect login, "0" for popup login.
  • interceptor.protectedResourceMap: Mapping of API URLs to scopes required to attach tokens.
• Services and Guards:
  • AdService / B2cService: Helper services to initiate the login flow.
  • SessionService: Handles session information and the token.
  • MsalGuard: Protects routes that require authentication.
  • MsalInterceptor: Automatically attaches tokens to outgoing HTTP requests to protected resources.
• Implementation: See LoginComponent for sign-in. Protected routes use AuthGuardService (which in turn may invoke MsalGuard).

Internationalization (i18n) with @ngx-translate

• Key Modules: @ngx-translate/core, @ngx-translate/http-loader.
• Configuration: In AppModule, TranslateModule is configured to use HttpLoaderFactory, which loads JSON files from src/assets/i18n/{{lang}}.json (e.g. es.json, en.json, pt.json).
• Usage:
  • Inject TranslateService in components/services for programmatic translations.
  • Use the | translate pipe in HTML templates: {{ 'MI_CLAVE_DE_TRADUCCION' | translate }}.
• Language Management: HeaderComponent allows changing the language and saves it in localStorage. AppComponent initializes the default language and loads the saved one.

UI Components (Angular Material)

• Module: MaterialModule (src/app/common/modules/material.module.ts) imports and exports the required Angular Material modules.
• Theming: The prebuilt indigo-pink.css theme is used. Global styles in src/styles.scss.
• Usage: Import MaterialModule in Angular modules where Material components are needed.

Progressive Web App (PWA)

• Module: @angular/service-worker.
• Configuration:
  • src/manifest.webmanifest: Defines application metadata (name, icons, colors).
  • src/ngsw-config.json: Configures Service Worker behavior (asset caching, etc.).
  • Registered in AppModule.

Testing

Unit Tests

• Tools: Karma (test runner) and Jasmine (testing framework).
• Execution:

  ng test

• Files: Test files (.spec.ts) are located alongside the source files they test (e.g. app.component.spec.ts).
• Configuration: karma.conf.js at the project root. tsconfig.spec.json for TypeScript configuration for tests.

Automated Tests (E2E with WebdriverIO)

The template includes a configuration for E2E tests with WebdriverIO.

• Location: src/tests/wdio-web/

• Prerequisites (before running):

  1. Modify package.json (the main Angular project file, not the one in wdio-web) and add "type": "module" under the name definition:

     {
       "name": "latam-angular-template", // or your project name
       "type": "module",
       "version": "0.0.0"
       // ...
     }

2. Create and configure the .env file in src/tests/wdio-web/ with the required credentials (e.g. for application login, BrowserStack, Jira if using the integration). Example of src/tests/wdio-web/.env:

   WEB_URL=http://localhost:4200/  # or the test environment URL
   LOGIN_USERNAME=tu_usuario_azure
   LOGIN_PASSWORD=tu_contraseña_azure
   # For BrowserStack (if used)
   BROWSERSTACK_USERNAME=tu_usuario_bs
   BROWSERSTACK_ACCESS_KEY=tu_access_key_bs
   # For Jira Zephyr (if used)
   JIRA_USERNAME=tu_usuario_jira
   JIRA_TOKEN=tu_api_token_jira
   GOOGLE_CHAT_KEY=tu_google_chat_key #optional
   GOOGLE_CHAT_TOKEN=tu_google_chat_token #optional

• Local Execution: From the Angular project root:

  npm run local

  This will run the tests defined in src/tests/wdio-web/tests/features/ using the configuration in src/tests/wdio-web/wdio.conf.js.

• BrowserStack Execution: From the Angular project root:

  npm run browserstack

  This will run the tests using the configuration in src/tests/wdio-web/browserstack.conf.js.

• View Reports: Cucumber HTML reports are generated in:

  • Local: src/tests/wdio-web/reports/local/cucumber-html/
  • BrowserStack: src/tests/wdio-web/reports/browserstack/cucumber-html/ Allure can be used for more detailed reports (after execution):

  cd src/tests/wdio-web
  npm run report # (runs: allure generate allure-results --clean && allure open)
  cd ../../..

• WebdriverIO Test Structure:

  • features/: Gherkin files (.feature).
  • step-definitions/: Gherkin step implementations in JavaScript.
  • page-objects/: Page abstractions for interacting with the UI.
  • utils/: Helpers for reports, constants, Jira integration, etc.

Security Considerations

• Authentication and Authorization: Using MSAL for Azure AD/B2C is the primary method. Ensure that requested scopes are the minimum necessary.
• Secret Management:
  • Local: Use the .env file inside src/tests/wdio-web/ for test credentials. This file is in that folder's .gitignore. The file src/assets/config/configuration.json (generated from templates) contains MSAL configuration and must not be committed with sensitive values to the main repository; it is managed per environment during deployment.
  • CI/CD (Jenkins): Credentials must be managed as Jenkins "secrets" and injected into the pipeline as needed, not hardcoded in repository configuration files.
• MSAL Configuration: The protectedResourceMap in configuration.json must be configured carefully to ensure tokens are only sent to intended API domains.
• Dependencies: Keep dependencies up to date (npm audit) to mitigate known vulnerabilities.
• HTTPS: Ensure all production deployments use HTTPS.
• Content Security Policy (CSP): Consider implementing a robust CSP to mitigate XSS risks.
• PWA Security: Consider the security implications of the Service Worker and caching.