Chore/#1739 - Create mkdocs.yml for all the services which have docum…

…entation (#1741)

catalog/systems/OnePlatform.yml

@@ -6,6 +6,9 @@ metadata:
   title: One Platform
   namespace: devex
   description: One Platform provides a single place for all internal applications and services, supports consistent User experience by providing standard platform for service hosting and data integration, efficient resource management, real time metrics availability, cross-team collaboration and unified documentation.
+  annotations:
+    github.com/project-slug: '1-Platform/one-platform'
+    backstage.io/techdocs-ref: dir:.
   tags:
     - digital-experience
     - javascript

catalog/systems/docs/code-of-conduct.md

@@ -0,0 +1,80 @@
+---
+id: code-of-conduct
+title: Code of Conduct
+sidebar_label: Code of Conduct
+---
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at [email protected]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+<https://www.contributor-covenant.org/faq>

catalog/systems/docs/how-to-contribute.md

@@ -0,0 +1,35 @@
+---
+id: how-to-contribute
+title: How to Contribute
+sidebar_label: How to Contribute
+---
+
+First of all, thank you for your effort to improve OP Platform. This guide will help you regarding various aspects like putting issues, contributing a feature, etc.
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by the [Code of Conduct](./code-of-conduct.md). By participating, you are expected to uphold this code. Please read the [full text](./code-of-conduct.md) so that you can read which actions may or may not be tolerated.
+
+---
+
+## Before Submitting a Pull Request
+
+**Before submitting your pull request** make sure the following requirements are fulfilled:
+
+- Fork the repository
+- Run `npm install` in the repository root
+- Create a branch from `master`
+- Add the required envs
+- Change necessary code for bug fix, a new feature
+- Check linting and format it
+- Make sure all are test passing
+
+```bash
+npm run test
+```
+
+## Reporting an issue
+
+Before submitting an issue, you need to make sure:
+
+- Kindly provide an adequate description and a clear title

catalog/systems/docs/index.md

@@ -0,0 +1,42 @@
+---
+id: overview
+title: What's One Platform
+sidebar_label: Overview
+slug: /
+---
+
+One Platform provides a single place for all internal applications and services, supports consistent User experience by providing standard platform for service hosting and data integration, efficient resource management, real time metrics availability, cross-team collaboration and unified documentation.
+
+## Why One Platform?
+
+If we observe a few key challenges of any organization with regards to application platforms for developers, it is to provide consistent app development, deployment & delivery experience, and a single place to access information. This could be due to a lack of a shared services platform for developers and unawareness of similar app's availability (search) that invites major duplication of code and efforts.
+
+The One Platform team was developing a solution to this problem since the start of this year. The goal was to build a shared services platform that helps developers to increase the development speed using easy to integrate microservices, in-built SPAs, and simplest components library and provide seamless app delivery. The intent is to provide a platform that connects users, developers, and stakeholders across the organization and allows them to exchange value by sharing apps.
+
+Developers have good reasons to select many feasible platforms that provide good development and deploying experience and One Platform works with these platforms and respective tools to ease a developer's job even further. While One Platform provides integrations and microservices that save developers time and effort, developers can use saved time to strengthen the core functionality of their individual apps.
+
+## One Platform Benefits?
+
+One Platform has been built on one key Principle/Mantra i.e. Develop fast, Deliver faster
+
+One Platform does not interfere in the Developer's business and provides flexibility to develop an app using their favorite framework, language, and tools. It provides on-demand integrations with internal tools and applications to easily access/share content(s). The following diagram shows where One Platform really comes into the picture.
+
+![OP Overview](/img/getting-started/op-overview.jpeg)
+
+The applications deployed in One Platform are,
+
+1. Open to all, by choice
+2. Hosted apps under single domain i.e one.redhat.com/yourapp
+3. Easy to search (including app contents) using common search service
+4. Have access to Core microservices (we will discuss them in detail in the next part)
+   - Authentication - Red Hat Single Sign-On enabled. (Subject to IT regulations)
+   - Authorization - Rover integration to view & grant users access
+   - Feedback - Collect feedback in 3 clicks, Generate ticket (Jira, GitLab) for improvements
+   - Notifications - Inter SPA communication, Toasters, Banners, Subscriptions etc
+   - Search - App & Content search utilizing inbuilt integration with Apache Solr
+5. Deployable within minutes using SPAship.
+6. Patternfly compliant and can easily utilize One Platform Component library
+
+In the end, One Platform would like to change the developer's mindset through its services from **"I work on a product/process"** to
+
+<center><b>"I connect users to an experience"</b></center>

catalog/systems/docs/op-architecture.md

@@ -0,0 +1,75 @@
+---
+id: op-architecture
+title: One Platform Architecture
+sidebar_label: One Platform Architecture
+slug: /architecture
+---
+
+One Platform entirely focuses on,
+
+- Core interaction of native & non-native apps/microservices.
+- Generate maximum value to both developers and users.
+- Enhancing and provide consistent developer experience.
+
+![OP Arch](/img/getting-started/op-arch.png)
+
+OP Architecture majorly consist of two components
+
+1. The SPA deployment base provided by SPASHIP
+
+2. The Unified Core API Service provided by a Federated GraphQL
+
+## Core Services
+
+Core services provides the basic interactive for any application like Authentication, Feedback, Notification etc
+
+Some of the core services provided by One Platform are:
+
+### Authentication
+
+One platform has different strategies for authentication. At the Client-side, internal auth is supported (auth.redhat.com) and at the API gateway, JWT token from Internal auth. The API key is supported. SPAs are authenticated default through SSI authentication support.
+
+### SSI Components
+
+One Platform provides global components, including a Navigation bar, Feedback action button, etc. These are provided as pluggable web components, published under `one-platform` namespace in npm. They provide flexibility and extensibility to the SSI.
+
+### User Group
+
+The simplest microservice is a wrapper over Rover that uses LDAP to authorize users. The plan is to give away complete ownership control to developers so the platform can stay out of the authorization business. User-group microservice plays the role of the middleware which talks to the organization's user data store. This is primarily integrated with LDAP and Rover. Also, it manages a minimal data store for faster data processing. This data store is updated daily with sync scripts. Native/Non-native microservices/SPAs can benefit from this for managing the user information.
+
+### Feedback
+
+The goal of feedback microservice is to let users submit feedback in 3 easy steps i.e. Select App, select Experience, and Describe a problem to help developers and the Platform team (in case of core services) build context for better decisions. The feedback services integrated with the ticketing system (Jira & GitLab) so developers can follow up with end-users and record satisfaction. This provides complete transparency as data is visible to all visitors and helps to increase the value of the applications.
+
+### Notification
+
+It is the core communication microservice of the platform for native(inbuilt) and non-native apps. It enables developers to select & configure the mode of communication for individual apps. The need for microservices to communicate with each other, many of which does not necessitate real-time communication, demanded the need of an engine that can help to notify the users of the event without bothering about the health and response of users. We kept it lightweight to ensure a quick response.
+
+### Search
+
+One Platform goal is to consolidate applications and make them searchable in real-time. It should be a single point of contact for end-users when they are looking for an app. The Search microservices would not only resolve app search problems however it would extend the search to app contents. This helps to design & develop an native app search.
+
+### Developer Console
+
+The developer's dashboard or the rather the control plane of One Platform. A single point to manage all your SPA's and there corresponding OP service utilization.
+
+### API Gateway
+
+The responsibility of the API gateway is to record “which service is communicating, with whom, and is it allowed to do so”. Access Control is implemented on top of the API Gateway which enables the authorization and permission model in the data flow. Also, it is a single source of truth for the entire one platform backend. Websocket support is also provided in the gateway.
+
+The supported authorization models are:
+
+- JWT Tokens from auth.redhat.com
+- API Key
+
+## Hosted Services
+
+There exist hosted services maintained by One Platform Team to enhance developer experience even furthur. Some of these are
+
+### Lighthouse
+
+Lighthouse is a Google Open Source Webpage Audit tool the measure's various parameters like SEO, PWA, Accessibility etc. One Platform has hosted the Lighthouse CI server for CI Testing and also an interactive, yet simple UI to get your SPA's Lighthouse progress.
+
+### API Catalog
+
+API Catalog is One Platform's effort to resolve API discoverability in an organization. In simple terms, it's a catalog to discover various API's provided by various team. It helps developers to manage, promote and share APIs with their users. Users can get various information regarding API like the owners or maintainers of it, various pre-prod and prod instances available, etc. API Catalog also provides toolsets to play around with the APIs.

catalog/systems/docs/service-deployment-guideline.md

@@ -0,0 +1,50 @@
+---
+id: service-deployment-guideline
+title: OP Service Deployment Guideline
+slug: /deployments/service
+sidebar_label: Service Guideline
+---
+
+This document shares the steps on how we can deploy the microservice on the kubernetes cluster in the openshift environment.
+
+## Workflow
+
+1. Once the PR/ MR is merged, run the github actions configured with the repository with proper tags.
+2. Github actions containerizes the code and pushes images to the Github Container Registry(GHCR).
+3. Once Image is published in GHCR, update the imagestreams of the respective microservice in OpenShift.
+4. Roll out the microservice deployment and restart the One Platform API Gateway if required.
+5. Now your changes are live now
+
+## Building an Image
+
+1. For building the image after PR navigate to GIthub Actions and select the action you want to perform. Trigger the run workflow button for the action which you have selected.
+2. Once the GitHub action is completed you will be able to see the new/updated image on the packages section of the One Platform repository.
+
+![GH Workflow Trigger](/img/service-deploymeny-guide/step1.png)
+
+3. Details of the new/updated image is available over the package page over the GitHub repository with the history of the update.
+
+![GH Workflow Progress](/img/service-deploymeny-guide/step2.png)
+
+4. Login to the Openshift Console and copy the login command with oc CLI.
+
+```sh
+oc login --token=token-test --server=https://test.openshiftapps.com:6442
+```
+
+![GH Workflow History](/img/service-deploymeny-guide/step3.png)
+
+5. Switch to the project in openshift to update the imagestream.
+
+```sh
+oc project <project-name>
+```
+
+6. Update the imagestream with a new image.
+
+```sh
+oc import-image <image-name>:<tagname>
+```
+
+7. Under the imagestreams section of the openshift web ui you can see that the new image has rolled out.
+8. Navigate to respective Deployment config and redeploy the microservice to update what changes through web UI

catalog/systems/docs/spa-deployment-guidelines.md

@@ -0,0 +1,10 @@
+---
+id: spa-deployment-guidelines
+title: SPA Deployment Guidelines
+slug: /deployments/spa
+sidebar_label: SPA Guidelines
+---
+
+## Guide
+
+#### Please head over to [SPAship quickstart deployment guide](https://spaship.io/docs/guide/user-guide/Quickstart/)

catalog/systems/mkdocs.yml

@@ -0,0 +1,13 @@
+site_name: 'One Platform'
+
+nav:
+  - What's One Platform: index.md
+  - One Platform Architecture: op-architecture.md
+  - OP Service Deployment Guideline: service-deployment-guideline.md
+  - SPA Deployment Guideline: spa-deployment-guidelines.md
+  - How to Contribute: how-to-contribute.md
+  - Code Of Conduct: code-of-conduct.md
+
+
+plugins:
+  - techdocs-core

packages/analytics-service/catalog-info.yml

@@ -8,6 +8,7 @@ metadata:
   description: Analytics microservice is used for providing analytics api information for SPAs deployed in One Platform by connecting with Sentry and Pendo.
   annotations:
     github.com/project-slug: '1-Platform/one-platform'
+    backstage.io/techdocs-ref: dir:.
     servicenow.com/appcode: ONEP-006
   tags:
     - microservice

packages/analytics-service/docs/index.md

@@ -0,0 +1,55 @@
+# Analytics Microservice
+
+Analytics microservice is used for providing analytics api information for SPAs deployed in One Platform by connecting with Sentry and Pendo
+
+## Features
+
+1. Total rate timeline
+2. Unique error rate timeline
+3. Total count of errors on an interval
+4. Total unique errors on an interval
+5. Error outcome based timeline - (Accepted errors, invalid errors etc)
+6. Api to connect analytics service with an existing project and an app or create a new one in one-platform set
+
+## Local Development
+
+### 1. Switch to the working directory
+
+1. Switch to the working directory `cd analytics-service`
+2. Copy the `.env.example` to the `.env`
+3. Change the values as needed, keeping the unneeded values as undefined
+
+### 2. Start Microservice
+
+Install required modules by using `npm install`
+
+Run `npm start` to run your microservice for dev env
+
+To build the microservice, use `npm run build`.
+
+## Using docker-compose (Recommended)
+
+1. Follow the first 2 steps from above
+2. Then execute the following command to start a standalone instance of `analytics-service`
+
+   ```bash
+   docker-compose up -d analytics-service
+   ```
+
+   **Note:** Some features of the App Service might not work without the API Gateway.
+
+3. To start the entire cluster of microservices, use the following command
+
+   ```bash
+   docker-compose up -d api-gateway
+   ```
+
+## Runnninng Tests
+
+```bash
+npm test
+```
+
+## Contributors:
+
+👤 **Akhil Mohan** [@akhilmhdh](https://github.com/akhilmhdh)

packages/analytics-service/mkdocs.yml

@@ -0,0 +1,7 @@
+site_name: 'Analytics Service'
+
+nav:
+  - Getting Started: index.md
+
+plugins:
+  - techdocs-core