Understand the Repository Structure
This part of the tutorial will briefly outline the structure of code directory, so you're comfortable navigating through the provided GitHub repository.
Also, check out our Explore the components chapter (click here), which describes the various SaaS application components and their tasks in greater detail (click here). For now, let us start with a brief overview, before deep-diving into the different sub-directories.
1. Overview
The code directory of our GitHub repository consists of several sub-directories containing the API (Service) Broker, the API Service, and the different application layers like User Interface, the Backend Business Application service layer, and the data models deployed in a tenant-specific and shared database container. Furthermore, you can find the Helm Charts (required for the Kyma deployment), content supporting local testing or even examples how to extend the SaaS application.
 | api - CAP-based API service app - SAP Fiori Elements UI modules broker - API Service Broker charts - Helm charts db - Tenant data model db-com - Shared/Common data model ext - CAP-based SaaS extension http - HTTP files for testing purposes obd - Onboarding Service (Expert Feature) router - Application Router srv - CAP-based Business Application service test - Unit tests and sample data .cdscr-private.sample.json - K8S binding samples for local testing default-env.sample.json - Environment variables for local testing package.json - CDS configs and dependencies for local testing |
Each of our CAP-based application components like the SaaS Backend Service or the API Service contain a dedicated package.json file. Instead of using the root-level package.json file we decided to provide component specific dependencies and CDS production profile configurations.
2. API Service
The api directory contains the implementation of the CAP-based API Service which can be used by SaaS consumers to upload or maintain data in their Tenant database containers. Further details can be found in a separate part of this tutorial (click here).
The API Service Docker Image is build using Cloud Native Buildpacks, therefore the directory does not contain a separate Dockerfile. Further details on the build process are provided in a separate part of the tutorial (click here)!
 | api-service.cds - CAP-based API Service definition api-service.js - CAP-based API Service handler package.json - Node.js dependencies and start script server.js - Custom server.js for health-check endpoints |
3. Application
Besides the html5-deployer directory (containing the HTML5 Application Deployer - find details here), the app directory contains all SAP Fiori Elements modules, which result in dynamically generated UIs, based on the OData Backend Service annotations. During the UI build process, all four UI modules are zipped and copied into a resources folder within the html5-deployer directory. This folder is created during the very first build.
The HTML5 Apps Deployer Docker Image is build using an existing Docker Image maintained by SAP, which is referenced in the respective Dockerfile. Further details on the build process are provided in a separate part of the tutorial (click here)!
4. API Broker
The broker directory contains the API Service Broker implementation. The catalog.json file (which is required to define service plans provided by the Service Broker) is part of the Helm Charts (click here), as the required details are only available upon deployment to your Kyma Cluster.
The API Service Broker Docker Image is build using Cloud Native Buildpacks, therefore the directory does not contain a separate Dockerfile. Further details on the build process are provided in another part of the tutorial!
 | package.json - Node.js dependencies and start script start.js - Custom start script for API Service Broker (reading credentials from env variables) |
5. Helm Charts
The charts directory contains all relevant Helm Charts for the deployment of the Sustainable SaaS sample application. Helm is one of the most popular package managers for Kubernetes environments and can therefore also be used to deploy artifacts to your Kyma Cluster!
If you are new to the topics of Kubernetes, Helm and Kyma please make sure to read our dedicated chapters on these topics (click here)! For a quick start, we also highly recommend to check out the following blog post on "Surviving and Thriving with the SAP Cloud Application Programming Model: Deployment to SAP BTP, Kyma runtime". Max gets you covered in his great and profound way of describing latest innovations in the SAP ecosphere.
While in Cloud Foundry, we make use of the mta.yaml deployment descriptor, in the Kyma environment, we rely on Helm as deployment solution. Helm allows you to generate required Kubernetes manifest (.yaml) files, in a structured and template-driven approach. While Helm feels overwhelming in the beginning, you will quickly realize and appreciate the amazing benefits. In case you are new to Helm, you can find a dedicated section on these and further Kyma related topics in one of the next chapters (click here).
The Sustainable SaaS sample application itself is based on a a so-called Umbrella Chart. So besides dedicated Helm Charts for each application component (SaaS Backend Service, Application Router, API Service, API Service Broker), the provided Umbrella Chart allows a combined deployment of all contained Helm (Sub-) Charts. As mentioned, you can learn more about Helm Charts as well as the various templates and resources sin a dedicated tutorial chapter (click here)!
Note -As the SAP Alert Notification Service can be deployed only once per Kyma Namespace, a separate so-called Helm Chart is used in our sample setup.
Learn more about Helm Charts in the official Helm documentation.
6. Tenant data model
The db directory contains the definition of our Tenant data model, which is deployed to a separate isolated SAP HANA Cloud HDI (HANA Deployment Infrastructure) database containers for each and every SaaS Tenant upon subscription. Besides a CDS-based data model, the directory also contains SAP HANA native objects (e.g., hdbgrants or synonyms) for accessing the shared HDI database container. Make sure to run a cds build --production in case of changes to the Tenant data model before building new Docker Images of your SaaS Backend Service.
As the Tenant data model is part of our SaaS Backend Service and deployed to new Tenant database containers at runtime, there is no need to build a separate Docker Image for this component. The data model definition is stored within the Backend Service and the mtxs Deployment Service (click here) allows an automated deployment to new database containers.
Based on the CDS profiles used in cds watch or cds build, the Tenant data model includes or excludes sample data. For local testing using sqlite, master data tables (e.g., Currencies or Countries) and sample values are part of the Tenant data model. For a production builds targeting SAP HANA Cloud, these tables and sample values are replaced by views pointing to a shared database container. Also check the package.json profile db-ext for a better understanding of this approach.
7. Shared data model
The db-com directory contains the definition of the shared data model, which is accessible from all isolated Tenant database containers. It is used for data required and shared by all Consumer Tenants (e.g., master data like Currencies, Languages, or Countries). To provide master data for Currencies, Languages and Countries, we make use of the @sap/cds-common-content npm package (click here). It is defined as a dependency in the root package.json file and referenced in the CAP data model definition of our shared data model.
using {
sap.common.Languages as Languages,
sap.common.Currencies as Currencies,
sap.common.Countries as Countries
} from '@sap/cds-common-content';
The shared data model has to be deployed separately into a dedicated SAP HANA Cloud HDI database container during deployment of the SaaS sample application. Therefore, a separate Docker Image is being build, which is then used by a Kubernetes Job initiating the actual deployment.
The Docker Image deploying the shared data model to a dedicated database container, is build using Cloud Native Buildpacks, therefore the directory does not contain a separate Dockerfile. Further details on the build process are provided in a separate part of the tutorial (click here)!
8. Extension Files
The ext directory contains files for a SaaS extension project, which can be used by SaaS subscribers to extend an existing SaaS Tenant instance. Please check the Expert Features for further details (click here).
9. HTTP Test Files
The http directory contains HTTP files allowing you to test the SaaS API endpoints from a SaaS Consumer perspective. Further details on how to use these HTTP files can be found in a separate part of our tutorial (click here).
 | api*.http - HTTP files for API testing tenantUpgrade.http - Sample HTTP call for Tenant upgrades |
10. Onboarding Service
The obd directory contains a separate user interfaces and workloads, including a CAP Service and an Application Router, used to offer a Self-Onboarding Service to customers interested in signing-up for a SaaS solution. Further details on how to deploy the respective Helm chart to your own Kyma Cluster after setting up the SaaS application, can be found in the respective Expert Feature chapter click here.
11. Application Router
The router directory contains all files of the Application Router required by our SaaS sample application. In this case, only the xs-app.json file and a health-check is required.
The Application Router Docker Image build process makes use of the official sapse/approuter Docker Image. Further details on the build process are provided in a separate part of the tutorial (click here)!
 | .dockerignore - Ignore package.json for docker build Dockerfile - Docker image based on sapse/approuter health.html - Used for pod health checks package.json - Required for local testing only xs-app.json - Route definitions for productive usage |
12. Annotation Files
The annotations folder in the srv directory contains all service annotations required to generate the Fiori Elements UIs of our sample application. These annotations define the capabilities of the OData Services but also set the layouts of the SAP Fiori Elements user interfaces.
As for any other changes to the SaaS Backend Service, make sure to run a cds build --production in case of any changes to the annotation files before building a new Docker Image!
 | admin - Admin Service annotations public - User Service annotations capabilities.cds - Service capability annotations fieldControls.cds - Service field control annotations layouts_*.cds - Fiori Elements layout annotations labels.cds - Label annotations valueHelp.cds - Value help annotations |
Yes, these annotation files can also be part of your UI modules as you can see in other tutorials. Feel free to move them around if you feel more comfortable storing the annotations among your actual UI components.
13. Business Application Service
The rest of the srv directory contains the implementation of our Business Application or central SaaS Backend Service. This includes OData-Services (admin-service.js/cds and user-service.js/cds) for our Fiori Elements UIs, as well as the automation logic executed on the subscription of new consumer-tenants (provisioning.js). The corresponding subscription service endpoints are exposed by using the CAP mtxs (click here for further details).
"cds": {
"requires": {
"multitenancy": true
}
}
Onboarding Automation
A lot of the Tenant onboarding steps have been automated using platform APIs and SAP BTP services. Start from the provisioning.js file and deep-dive into the various utilities like e.g., apiRule.js, creating API Rules for new subscribers by interacting with the Kyma API Server.
The SaaS Backend Service Docker Image is build using Cloud Native Buildpacks, therefore the directory does not contain a separate Dockerfile. Further details on the build process are provided in a separate part of the tutorial (click here)!
14. Test objects
The test directory contains sample data for local development and testing purposes as well as sample unit tests.
These files should not be part of a productive deployment and are not part of the production build profile.
| data - Sample data for Tenant data model index.cds - CDS file for builder test.js - Sample unit tests |