It's best practices in developing web applications that guarantee smooth implementation, scaling, and operationalization of the solution.

 The development comes from Heroku, the PaaS platform, as principles for building cloud-native scalable applications, so it comes from the real practices, not a theoretical point of view.

1. Scalability

2. Environment consistency

3. Flexibility

4. Cloud Native

5. Operationalization

6. Continious improvement

Practice: One codebase tracked in version control, many deploys 

Having one single repository for source code, managing different branches that should be deployed on each environment, and a feature-based branch in order to have the proper level of traceability.

Old Approach:

 Multiple codebases for different environments, instead of One codebase tracked in version control, many deploys.

Benefits:

• Simplify Version control

• Simplify collaboration

• Enablement for release train

 Example:

• Master branch for production

• Development branch

• Staging branch

• Feature-based branch

• Fixes branch

• Ad-Hocs branch

Related Design patterns:

• NA

Practice: Explicitly declare and isolate dependencies 

Isolate solution dependencies, instead of using the system's internal components, as it should be explicitly declared and isolated.

It can be:

1. Operating systems components

2. Solution dependencies components

As implementation practices, you have package.json in Node.js, Pom.xml in Java, and build. gradle in Java, as well as .csproj in C # projects. 

Old Approach: Relying on system-level packages, manual installs, instead of declaring all dependencies explicitly and isolating them.

New Approach:

1. Docker and containerization

2. Immutable infrastructure: No change after deployment, you should rebuild and redeploy.

Benefits:

• Ensure consistency across environments.

• Readiness for portability and shifting the solution from environment to another

Example:

• Messaging components at OS level.

• Java SDK version 

Related Design patterns:

• NA

Practice: Store config in environment variables: 

Store configuration in the environment, not the code.

Old Approach: Hardcoded configs in code or files (e.g., web.config, .env), instead of storing configuration in environment variables.

Benefits:

•  Separates config from code; enhances security. 

• Increase maintainability

• Increase operationalization

• Environment independent configuration

Example:

• Configurations: In config maps

  • Database connection strings

  •  Average price calculation strategy

  • Default currency

• Secrets: in secret maps, vaults, with auto-rotation enablement

  • Passwords

  • Secret Keys

  • Encryption Keys

Related Design patterns:

• External configuration design pattern

• Realtime reconfiguration design pattern

Practice: Treat backing services as attached resources

Each service that you are using should not take effort if we need to replace it.

For example, if you have to replace the SMS gateway service, you do not need to reimplement it again within the code, which implies implementing the configuration practice.

 This principle, called Interchangeability, means change with zero coding effort.

Old Approach: 

Hardwired service bindings (e.g., fixed DB address in code), instead of treating backing services as interchangeable resources.

Benefits:

• Facilitates swapping services without code changes.

• Decrease coupling 

Example:

• Switch from local SQL Server to cloud DB without code change. 

• Switching the SMS gateway without code change

• Use Redis instead of in-memory cache

• Switching Kafka Vs RabbitMQ

Difference between backing services and config factor

Think it this way: Config = “How should I behave?”, Backing Services = “Who should I connect to?”

• Both are using configurations

• Config related to runtime behavior, while backing services related to dependencies

• Config not related to swappable, while backing services is focused on that

• The ownership of the config is the application team, while the ownership of the backing service is external systems

• change effect: config affects the behavior, while the backing service focuses on what apps connect to.

Related Design patterns:

• External configuration store

• Realtime reconfiguration

Practice: Strictly separate build and run stages.

At this Principle, We segregate between the 3 phases:

• Build: 

  • • Convert code into a runnable package, which includes: Compilation, bundling assets, and resolving dependencies.

    • Developer responsibilities

    • CI takes place here to make sure that the build has the related governance practices according the the agreed quality gate

• Release: 

  • • Release = Build + dependencies

    • Combine the build with config (env vars) to create a release, Including Assign version, attach config/secrets.

    • DevOps responsibilities/CI Pipeline

    • CD:

      • • To be manual, especially in critical solutions like banking

• Run: 

  • • Release = Release + Environment configuration

    • Execute the app in an environment using the release package.

    • Like Kubernetes or Docker run 

    • DevOps responsibilities/

Old Approach:

 Manual steps, no separation between build/release/runtime, instead of Separate build (compile), release (package), and run (execute) 

Benefits:

• Separation of concern

• Enhances deployment reliability 

• Rollback capabilities

• Secure deployment process by eliminating deploy anytime

Example:

• Pipeline CICD

• Docker Image build

Related Design patterns:

• NA

Practice: Execute the app as one or more stateless processes. 

When the application is stateful, it relies on saved user session data.

Your solution should be implemented in stateless sessions, in order to serve multiple requests, without additional overheads on the server.

Old Approach: 

Long-running monolithic apps with internal session state, instead of Stateless processes, disposable and scalable.

Benefits:

• The stateful model will be on the database level, and the handling for the state will be injected at the implemented business layer, in order to:

• guarantee that the solution will run properly in case it needs to be restarted.

• Application of the retry pattern

• Application of scheduler jobs pattern

• Resiliency, especially in microservices architecture

Where to store the state?

in stateless architecture, the status is not recorded in the code, it's stored in a different layer:

• Enterprise Caching layer

• Database layer

Example:

• Web APIs for integration with the mobile solution

• Background scheduler jobs

• Transaction compensation design patterns

Related Design patterns:

• Retry

• Circuit breaker

• Scheduler agent

• Cache-Aside

Practice: Export services via port binding

Moving forward to self-contained services, without the need to an application server, as Parent process, like Apache or IIS, as the old approach requires an application server, and it binds the application to a specific IP and port.

In this principle, the application/services will be self-exposed via specific port binding, even hardcoded, or configured from external configuration.

No potential conflicts, as the architecture will be implemented as following:

• Each container has its own IP

• Each container is self-contained with a port

• Ingress routing reroutes the external routes to internal routes:

  • • https://api.myapp.com → goes to service-api (port 8080)

    • https://auth.myapp.com → goes to service-auth (also 8080)

  • 
    

Old Approach: 

Depends on external servers like Apache/Nginx to serve the app, instead of Self-contained service exposing a port (e.g., via Kestrel in ASP.NET Core and container-based microservices )  

Benefits:

• Simplify selecting communication ports, for example, if you have 3 servers, with 3 apps, and lots of microservices, then use port binding for external calls to these self-contained services' ports using routing in the load balancer

• Simplifies service discovery and interaction. 

• Portability, as you have hundreds of microservices, you will not be able to configure each one, which makes it suitable for containerization

• Increase Security: Because you have specified which ports can talk to this container

Example

• NodeJS Apps: express.listen(5000)

Related Design patterns:

• Service discovery

Practice: Scale out via the process model 

This principle focuses on the ability of the software for scale out and scale down according to the workload, without modification in the solution architecture.

 Within OpenShift, you can configure the minimum PODs, the maximum PODs, and when to extend the PODs.

So, the infrastructure level detects the workload and creates new instances of the application to serve operational needs.

Old Approach:

Scaling by adding threads or servers manually (Vertical Scaling), instead of scaling out using multiple processes/instances per workload type(Horizontal Scaling).

Benefits:

• Enhances application performance and availability

• Enhance scalability

Example:

• OpenShift MinMax scaling

• Scaling trigger: CPU utilization > 70%

Sizing Min/Max Model:

• Design Phase

  • • Business SLA

    • Use architecture assumptions

      • Givings

        • Expected concurrent Requests per second: 5000 Requests

        • Business SLA: 0.01 milliseconds

        • Request size 1 K

      • Resolution

        • Concurrency=RPS×Response Time (sec) ==5000×0.01=50 concurrent requests 

        • Define Pod Capacity: 

          • • H = 500(POD CPU)/50(Request) = 10 concurrent requests/second

            • (based on 500m CPU and 512MB RAM — typical light app)  

        • Number of Pods=Concurrency/H ​=50/10​=5 Pods

        • Estimate Bandwidth: Bandwidth=RPS×Request Size=5000×1KB=5MB/sec

• Development phase

  • • Load testing for 1 POD

    • Resize the mode; 

• Production phase

  • • Load testing

    • Growth and resize

Related Design patterns:

• Service discovery: New replicas are registered dynamically to the load balancer

Practice: Fast startup and graceful shutdown 

The objectives of this principle are:

• Easy to start up

• Easy to scale out

• Easy to scale down

• Easy to shut down, with the cleaning resources

Old Approach: 

• Slow startup

• Unsafe shutdown

• Poor resilience instead of Fast startup and graceful shutdown 

• Cost of outage and shutdown for upgrades and hot fixes

Benefits:

• Zero downtime deployment, as you stop sending requests to old PODs once the new PODs are up and running (Graceful approach), using Signterm and Sigkill

• Robust Horizontal scaling

Graceful Shutdown in this context means:

• App responds to termination signals (SIGTERM)

• SIGTERM → App can intercept, finish its work, and clean up resources (gracefully).

• SIGKILL → App is immediately killed by OS. No time for cleanup.

• Stops accepting new requests

• Finishes in-flight work (requests, jobs, etc.)

• Closes open resources (DB, queues, etc.)

• Exits cleanly within allowed time (e.g. 30s)

Implementation guidelines

• Stateless design

• Preload dependencies

• Use liveness to ensure self-healing.

• Use readiness to ensure a graceful startup and deployment.

• Liveness property in YAML file: means pod is not ready to receive, kill, and create a new one

livenessProbe:

  httpGet:

    path: /healthz

    port: 8080

  initialDelaySeconds: 15    #first inspection for the pod will be after 15 seconds

  periodSeconds: 10      #next after 5 seconds

• Readiness property in YAML file: Means pod is ready to receive requests

readinessProbe:

  httpGet:

    path: /ready

    port: 8080

  initialDelaySeconds: 5    #wait 5 seconds till receiving first request

  periodSeconds: 5           #next after 5 seconds

Related Design patterns:

• Cache aside

• Service Discovery

Practice: 

Keep development, staging, and production as similar as possible 

Make the environment similar, for the same dependencies, tools, and database, otherwise, containerization.

 The objectives of this principle is to prevent any risks when moving the code from development to the production environment, as a results from the variation between environments, different components and factors.

Old Approach: 

Different tools/versions/configs between dev and production, instead of Keep development, staging, and production environments as similar as possible 

Benefits:

• Reduces environment-specific bugs. 

Practices:

• Same containers

• Same Backing services (Like database type, message queues, ..)

Related Design patterns:

• NA

Practice: 

Treat logs as event streams 

As a large-scale solution, in order to confirm that your solution is alive, in a healthy state, you should have a continuous stream of logs, that capture what is running in your solution.

It should be independently implemented, like EFK.

Why Stream?

• Event streaming

• Realtime analysis

• Centeralized Log

• Can be handled as data pipeline

  • • Collect: Using FluentD

    • Transport: Kafka/Redis stream

    • Analysis: Logstash

    • Store: ElasticSearfch

    • Visualize/Alert: Kibana/Grafana/Prometheus

    • Retention

Old Approach: 

Store logs in local files or ignore them, instead of Stream logs to stdout/stderr and aggregate externally  

Benefits:

• Facilitates centralized monitoring and debugging 

• Visualization

• Transparency and control

• Governance

Tools

• EFK (Elastic search, FluentD, Kibana)

• ELK (Elastic search, Logstack, Kibana)

• Loki + Grafana

Related Design patterns:

• Sidecar design pattern:

  • • Collect Docker logs

    • Application logs

      • • Errors

        • Info

        • Traces

    • Access Logs

    • Security logs

    • Traffic Logs

Practice: 

Run admin/management tasks as one-off processes.

short-lived, separate from main app. 

What do you mean by one-off job?

The job that runs once, and is no longer used for it, like:

• Data migration

• Update the database structure for the new deployment

• Data cleansing

You have 2 types of functionalities:

1. Business functionalities, which should be embedded within your business modules

2. Administrative functionalities, which should be embedded within your business modules, to enable the operationalization of the solution, like:

• Managing users

• Data cleansing

• Backup/restore operations

Old Approach: 

Manual admin tasks on production machines (risky), instead of Run admin tasks as one-off processes inside the app context,

Benefits:

• Keeps admin tasks consistent with the application environment. 

• Fast startup and scale-up for the solution.

Usecase:

• Scaling the PODs

Related Design patterns:

• Scheduler jobs: Can run one-off jobs

Adding 3 new factors:

• First Approach: API First

What Is?

API-First architecture/strategy is a new architecture approach the shift the mindset of software development for APIs to consider APIs as independent product,  with different journeys in order to achieve business objectives, independent from the UX journey that may mislead/abuse the API architecture and design.

You can just imagine it if you just think that your final product is the APIs, and you will commercialize it alone, without UX.

It means, you have API as a product, so you have:

1. Product manager

2. Product Roadmap

3. And product lifecycle

As example, the target persona of your product (APIs) which will use your product, like mobile app, web app, and smart watch.

So, We are starting with the API, not the application.

So, It's about "How will you image the solution upon the API first, not how to build the API upon the design first solution".

Why?

• Async Development

• Reduce development Cost

• Reduce time-to-market

Principles

Same like software engineering lifecycle, passing all journeys as the opposite diagram mentioning, considering that your product is APIs, including its documentation and journeys.

As a pre-requisites, We should build the culture, which implies the following principles:

• Your API is a product

• Foundational design, not ad hoc retrofit

• Team collaboration and impact

• API-first supports microservices

• The API contract

Ten Process Steps

Step 1: Create API Micro-Service architecture according to DDD, which each object has the following attributes:

• Who Am I?  I'm Employee Class

• What I know? I know my code, name, birthdate, current salary, current role.

• What I do?  I can Create employee, delete employee, activate employee, deactivate employee, update employee, and block employee, and unblock employee

• What is my state? like : blocked employee, Unblocked employee, Active employee and Inactive employee

Step 2: Determine key domains

Step 3: Determine each domain lifecycle

Step 4: Model your architecture domains

Step 5: Model your architecture sequence diagrams

Step 6: Model your architecture state-chart diagrams

Step 7: Develop CRUD APIs according to data models characteristics

Step 8: Create the journeys according to the sequence diagrams, with validating the pre-requisites

Step 9: Create APIs to validate product states

Step 10: Create Security model for the APIs

API Improvement model

As opposite figure, We have consumer and publisher, They are shared improvement the model, due to the required improvement after design, as a nature of any product lifecycle. 

Are You API First Company?

Since you have the following characteristics, you can consider yourself as API-First company:

1. You have APIs that operate and maintain your data models

2. You are providing you APIs as independent product

3. You make APIs available to your customers and partners as a source of your revenue stream

4. You know how to Manage and discover your APIs

5. You have standardized processes to build APIs

6. Your APIs is independent from any UX design

There are five new approaches:

1. Containers (Docker)

2. Orchestration

3. Microservices architecture

4. Serverless architecture

5. DevSecOps