app:
  image:
    repository: "onecx-apps/onecx-document-management-bff"
    tag: 999-SNAPSHOT
  operator:
    # Permission
    permission:
      enabled: true
      spec:
        permissions:
          document:
            read: permission on all GET requests and POST search
            write: permission on PUT, POST, PATCH requests, where objects are saved or updated
            delete: permission on all DELETE requests
    keycloak:
      client:
        enabled: true
        spec:
          kcConfig:
            defaultClientScopes: [ ocx-doc:all, ocx-doc:read, ocx-doc:write, ocx-pm:read ]
  product: false

ient:
        enabled: true
        spec:
          kcConfig:
            defaultClientScopes: [ ocx-doc:all, ocx-doc:read, ocx-doc:write ]

  product: false

t Management

Document management refers to the systematic process of capturing,
organizing, storing, and retrieving documents within an organization. It
involves the efficient handling of digital documents, ensuring secure
access, version control, collaboration based on TM-Forum standard
https://github.com/tmforum-apis/TMF667_Document[TMF 667].

With OneCX-Document-Management Software, you can streamline your
document management workflows, reduce manual efforts, and enhance
productivity. Whether it’s managing contracts, invoices, legal
documents, or any other form of digital content, OneCX Document
Management provides a centralized and user-friendly solution for
effectively managing your documents.

=== Overview

OneCX-Document-Management is a comprehensive solution for managing
documents in a user-friendly and efficient manner. It is a solution that
consists of three main components which are explained in more detail in
the general documentation. Please refer to the following documentation
to learn more
https://onecx.github.io/docs/document-management/current/general/index.html[Document-Management
Documenation]. However, in this document we are only referring to one of
the three components, the OneCX-Document-Management-Backend-For-Frontend (BFF) of
OneCX-Document-Management.

=== What is a Backend For Frontend
Backend For Frontend is an architectural pattern used in modern web development. The BFF pattern involves creating a dedicated backend service for each front-end client or application. This allows the backend to provide customised APIs and functionality optimised for the specific needs of each frontend.

The code generation part of the `pom.xml` file is responsible for creating REST clients and proxies tailored to the backend services that the user interface needs to interact with. These clients and proxies act as the backend for the frontend, providing a dedicated and optimised interface for the document management frontend application. This architectural pattern provides a better separation of concerns, improves frontend performance and simplifies the frontend development process, as it only needs to deal with the APIs relevant to its functionality.

The BFF pattern is particularly useful in microservices architectures, such as the OneCX workspaces, where different front-end clients may require different data and functionality from multiple back-end services.

=== Getting Started

To start developing the OneCX Document Management BFF, you need to
set up your local development environment. It’s recommended that you use
WSL as the runtime for your application, as shown in the figure below.
If you are using a different runtime, please check that you meet the
requirements below.

==== Prerequisites

Before you begin, ensure you have the following installed:

* Java Development Kit (JDK) version 17
* Maven build tool
* Git
* Docker + Docker Compose (Windows Subsystem for Linux (WSL)
recommended)

==== Clone the Repository

Start by cloning the required repositories to your local machine using
the following command:

[source,bash]

The repository `onecx-document-management-bff` contains the source code of
the document management BFF. The repository
`document-management-dev` contains the necessary OneCX platform
dependencies and the docker-compose script required to run the OneCX
Document-Management-User-Interface on your local machine.

==== Build the Project
Navigate to the project directory and build the application using NPM:

[source,bash]

Downloading the required Maven dependencies for the first time may take
some time.

==== Update local DNS resolution
Assuming you are using WSL, updating the local host file for local
development allows you to map domain names to specific IP addresses,
making it easier to test and debug applications using custom domain names
instead of IP addresses. To enable multiple services on the same port,
we use traefik as a reverse proxy. A running traefik container is
therefore essential for your local setup to route your traffic to the
appropriate Docker containers based on hostnames.

*It is recommended that the WSL host file and the Windows host file are aligned.
Unless you have disabled this behaviour, the WSL host file will be automatically
generated from the Windows host file when WSL is restarted.*

===== Update Windows host file
Open the file `C:\Windows\System32\drivers\etc\hosts` in your favorite
editor and add the following entries:

[source,bash]

===== Update WSL host file
If needed, update the file `\etc\hosts` in `your` favorite linux editor and add the
same entries like above.

==== Starting OneCX dependencies
In a local development environment, Docker Compose is used to define and
manage multiple containers as a single application stack. It enables
developers to easily start, stop, and configure all the necessary
services and dependencies required by OneCX Document Management using a
simple configuration file.

[source,bash]

* `traefik`: Traefik is an ingress controller for Kubernetes deployments
that enables dynamic traffic routing and load balancing based on defined
rules and configurations.
* `postgresdb`: PostgreSQL is an open-source relational database
management system. It is used as persistence layer for storing and
managing data in OneCX Document Management, providing reliability and
scalability.
* `pgadmin`: pgAdmin is an open-source administration and development
platform that offers a user-friendly graphical interface for managing
and interacting with the local PostgreSQL database.
* `keycloak`: Keycloak is an open-source identity and access management
system that simplifies authentication, authorization, and single sign-on
for web and mobile applications.
* `tkit-portal-server`: This micro-service is responsible mostly for
handling the logic of portals and their meunitems and user data and
settings.
* `minio`: We use MinIO as a facade or abstraction layer to decouple our
applications from the underlying cloud storage provider, providing
greater flexibility and allowing us to seamlessly switch between
different providers without changing our application code. It acts as a
unified interface, enabling us to interact with various cloud storage
systems using the standardized Amazon S3 API.
* `apm`: In this backend, user permissions are stored in a structured
manner and an endpoint is provided to import permissions via CSV files.
Each application can be assigned a set of roles and permissions, managed
through an association table in the APM database. Roles are assigned in
the Keycloak admin console and are retrieved from tokens, while strings
defined in APM are used to grant access to specific components or views
on the frontend.

==== Starting the OneCX Document Management BFF

The command `mvn compile quarkus:dev` is used in a Maven-based Quarkus
project to compile the source code and start a live coding development
mode. In this mode, Quarkus will automatically rebuild and redeploy the
application whenever changes are detected in the source code, allowing
for rapid development and testing.

Please run:
[source,bash]

Commands Explained:

* `mvn compile`: This command tells Maven to compile the source code of
the project. It resolves dependencies, compiles the Java source files,
and generates the compiled bytecode.
* `quarkus:dev`: This is a Maven plugin goal provided by the Quarkus
framework. It starts the Quarkus dev mode, which is a live coding mode
for development. It launches your application in development mode, which
includes features like hot-reloading and automatic recompilation.

When you run mvn compile quarkus:dev, the build process compiles your
application, and once it’s built, Quarkus starts a development server
that listens for changes in the source code. If any changes are
detected, the affected parts of the application are automatically
recompiled and redeployed, allowing you to see the changes in real-time
without restarting the application manually.

==== Stopping OneCX dependencies

The `docker compose stop` command is used to stop the containers defined
in a Docker Compose file. It gracefully stops the running containers by
sending a stop signal, allowing them to perform any necessary cleanup
tasks before shutting down.

[source,bash]