Introduction

As backend applications grow, maintaining a consistent project structure becomes increasingly important.

In a small application, developers can manually create packages and folders whenever a new business entity or feature is introduced. However, in a larger application following architectural patterns such as CQRS, Domain-Driven Design, and event-driven architecture, every new feature may require a considerable number of packages. Manually creating these directories can become repetitive, error-prone, and time-consuming. To solve this problem, a reusable Batch script can be introduced to automatically generate the required package and directory structure for a new domain entity.

The script accepts two parameters:

• A base package name
• An entity or feature name

Based on these inputs, it automatically creates the required Command, Query, and Event directory structures.

This approach provides a simple form of project scaffolding that improves development speed while enforcing architectural consistency across the application.

Why Automate Project Structure Creation?

Consider a project following a CQRS-based architecture.

Whenever a new business entity is introduced, developers may need to create directories for:

• Commands
• Controllers
• DTOs
• Entities
• Exception handlers
• Infrastructure
• Repositories
• Queries
• Query handlers
• Query controllers
• Event consumers
• Event handlers
• Shared events
• Notifications

Creating these directories manually for every entity has several disadvantages.

1. Repetitive Work

Developers repeatedly perform the same directory-creation steps.

2. Human Error

It is easy to:

• Miss a directory
• Create a directory in the wrong location
• Use an inconsistent naming convention
• Create an incorrect package hierarchy

3. Architectural Inconsistency

Different developers may create different structures for different features. Over time, this can make the codebase difficult to navigate.

4. Slower Feature Development

Although creating directories takes only a few minutes, the accumulated overhead becomes significant when many entities are introduced.

5. Difficult Onboarding

New developers need to understand where each component belongs before they can start implementing a feature. Automation reduces this friction.

What Does the Script Solve?

The batch script acts as a lightweight project scaffolding tool.

Instead of manually creating the complete structure, a developer provides the required package and entity information. The script then generates the predefined directory hierarchy automatically.

Conceptually, the workflow is:

Developer Input

→ Base Package

→ Entity Name

→ Script Processing

→ Command Structure

→ Query Structure

→ Event Structure

The important point is that the script does not generate business logic.

It generates the structural foundation on which the developer can build the feature.

High-Level Architecture

The generated structure is divided into three major areas:

1. Command
2. Query
3. Shared Events

This separation reflects the responsibilities commonly associated with CQRS and event-driven architectures.

A simplified conceptual structure looks like this:

Base Package
│
├── command
│   └── Entity
│       ├── api
│       ├── dto
│       ├── entity
│       ├── exceptions
│       ├── infrastructure
│       └── repository
│
├── query
│   └── Entity
│       ├── api
│       ├── dto
│       ├── entity
│       ├── exceptions
│       ├── infrastructure
│       └── repository
│
└── shared
    └── Entity
        ├── events
        └── notification
            └── events

The exact implementation can evolve as the architecture grows, but the main principle remains the same:

Create a predictable structure automatically so developers can focus on implementing business functionality rather than repeatedly creating folders.

Understanding the Script

The script can be divided into several logical stages.

1. Parameter Validation

The first responsibility of the script is validating the input.

It expects two parameters:

Package Name

This represents the base package where the new feature should be created.

For example, conceptually: com.company.application

Entity Name

This represents the business entity or feature for which the structure should be generated.

For example: Employee

The script checks whether both parameters have been supplied. If the package name is missing, the script stops and displays an error. The same happens if the entity name is missing. This is important because generating a directory structure without the required information could result in an incomplete or incorrect project structure.

2. Converting Package Names into Directory Paths

Programming languages such as Java and Kotlin commonly represent packages using dot notation.

For example: com.company.application

However, the operating system represents directories using path separators.

The script therefore converts the package notation into a directory-compatible path.

Conceptually: com.company.application

becomes: com\company\application

This allows the script to map a logical package name directly to the corresponding filesystem structure. This small transformation is important because it makes the script reusable for different package hierarchies.

3. Creating the Command Structure

The first major structure generated by the script is the Command side. The Command side represents operations that generally change application state.

The generated structure provides dedicated locations for areas such as:

API Commands

This area can contain command definitions representing business operations.

Examples conceptually include:

• Create
• Update
• Delete

API Controllers

This area can contain controllers responsible for receiving client requests and initiating commands.

DTO

The DTO package provides a dedicated location for request and response-related data structures.

Entity

This area contains the domain or persistence-related entity representation associated with the feature.

Exception Handlers

Feature-specific exception handling can be placed here. This prevents business-specific error handling from becoming scattered throughout the project.

Infrastructure

Infrastructure-related implementations associated with the command side can be placed here.

JPA Repository

Persistence interfaces and implementations related to command-side operations can be maintained here.

4. Creating the Query Structure

The second major structure is the Query side.

Queries are generally responsible for retrieving data without changing application state. The script creates separate locations for query-related responsibilities.

Query Handlers

Query handlers process query requests and coordinate the retrieval of required information. Keeping handlers in a dedicated package makes the read side easier to locate and maintain.

Query Controllers

Controllers expose query functionality through application APIs.

DTO

The Query DTO package can contain structures specifically designed for read operations.

Entity and Enums

The entity area can contain read-side models, projections, or other representations required by the query layer. The dedicated enum package provides a clear location for feature-specific enumerations.

Exception Handlers

Query-specific exceptions can be handled separately from command-side exceptions.

Notification Consumers

The notification consumer area provides a place for components that consume notification-related messages.

Notification Handlers

Notification handling logic can be isolated from the main query processing logic.

JPA Repository

Repositories that use traditional JPA-based persistence can be organized here.

Reactive Repository

Applications that use reactive data access can maintain reactive repositories separately. This distinction becomes particularly valuable when an application supports both traditional and reactive data-access patterns.

5. Creating the Event Structure

The third area created by the script is the shared event structure. Events are useful in event-driven architectures because they allow one part of an application to communicate that something has happened without requiring direct coupling with every consumer. The generated structure provides two major locations.

Domain or Feature Events

The events directory provides a centralized location for events associated with the entity.

Examples conceptually include:

• EntityCreated
• EntityUpdated
• EntityDeleted

The actual events depend entirely on the application's business requirements.

Notification Events

The notification-events area provides a dedicated location for events related to notifications or communication workflows.

This separation makes it easier to distinguish between:

Business events and Notification-related events

Why Command, Query and Event Separation Matters

The most important architectural benefit of this structure is separation of responsibilities. Instead of placing every class related to an entity into a single package, the application separates components based on their purpose.

Conceptually:

Command

Change something

Query

Read something

Event

Communicate that something happened

This makes the architecture easier to understand and helps prevent unrelated responsibilities from becoming tightly coupled.

How to Use the Script

The script is designed to be parameter-driven.

A developer provides:

Parameter 1: Base package

Parameter 2: Entity name

The script uses those values to construct the complete directory structure.

A typical workflow is:

Step 1 — Open the Project Directory

The script should be executed from the appropriate project root.

This ensures that the generated directories appear in the expected source location.

Step 2 — Provide the Base Package

The developer provides the application's base package.

Step 3 — Provide the Entity Name

The developer provides the name of the new entity or feature.

Step 4 — Execute the Script

The script validates the parameters and begins generating directories.

Step 5 — Verify the Generated Structure

After execution, the developer should verify that:

• The package path is correct
• The entity name is correct
• Command directories exist
• Query directories exist
• Event directories exist

Step 6 — Start Implementation

Once the structure is created, developers can begin implementing:

• Commands
• Command handlers
• Queries
• Query handlers
• Controllers
• DTOs
• Entities
• Repositories
• Events
• Consumers
• Exception handling

The script therefore becomes the starting point of the feature-development workflow.

What Happens When an Entity Name Is Provided?

Suppose a developer wants to introduce a new business entity.

The developer provides:

Base Package And Entity Name

The script combines these values with the predefined architectural paths. The result is a complete feature-specific structure. This is important because the developer does not need to remember every directory required by the architecture. The architecture is effectively encoded into the scaffolding process.

Benefits of This Approach

1. Consistency

Every feature starts with the same architectural structure. This makes the codebase predictable. A developer familiar with one feature can quickly understand another feature because the package organization follows the same pattern.

2. Faster Development

Developers no longer need to manually create dozens of directories. The initial setup becomes almost instantaneous.

3. Reduced Human Error

The script eliminates many common structural mistakes. Developers don't have to remember:

• Which directories are required
• Where repositories belong
• Where event classes belong
• Where notification handlers belong

4. Easier Code Navigation

A predictable structure makes it easier to locate components. For example, when investigating a query-related issue, developers know where query handlers and repositories should exist. Similarly, when investigating an event-related issue, developers know where to look for event definitions and notification events.

5. Easier Onboarding

New developers can learn one standard feature structure and apply that knowledge across the application. The directory structure becomes part of the team's architectural documentation.

6. Architectural Enforcement

Although a batch script cannot enforce every architectural rule, it establishes a strong starting point. Instead of architecture being only documented in a wiki or design document, part of the architecture is embedded directly into the development workflow.

The Script as a Lightweight Scaffolding Tool

The script can be considered a simple form of code scaffolding. Scaffolding means automatically generating the initial structure required to implement something. Many modern development ecosystems provide sophisticated scaffolding tools. However, not every project needs a complex framework or generator.

A small batch script can be extremely effective when:

• The architecture is stable
• The directory structure is predictable
• Features repeatedly require the same structure

In such scenarios, simplicity can be an advantage.

What the Script Does Not Do

It is equally important to understand the limitations. The script creates directories, but it does not implement functionality.

It does not automatically create:

• Business logic
• Domain rules
• Commands
• Query handlers
• Controllers
• Repository implementations
• Event definitions
• Database schemas
• API documentation
• Unit tests
• Integration tests

Therefore, it should be viewed as a structural generator, not a complete feature generator.

Recommended Development Workflow

A good workflow can look like this:

1. Identify the business feature

↓

2. Define the entity

↓

3. Run the scaffolding script

↓

4. Verify the generated structure

↓

5. Create domain entities

↓

6. Define commands

↓

7. Implement command handling

↓

8. Define queries

↓

9. Implement query handling

↓

10. Add repositories

↓

11. Define required events

↓

12. Implement consumers and notification handlers

↓

13. Add exception handling

↓

14. Build and validate the application

This creates a repeatable development process for every new feature.

Naming Conventions

Automation works best when naming conventions are clearly defined. The entity name should follow the project's established naming standards.

For example, teams should decide whether entity names should be:

• Singular or plural
• PascalCase
• camelCase
• Domain-oriented
• Feature-oriented

Consistency is particularly important because the entity name becomes part of the generated package hierarchy. A poor naming convention in the input can propagate throughout the generated structure.

Important Considerations

Project Root

The script assumes that it is executed from the expected project location. Running it from an incorrect directory could create the generated structure in the wrong place. Therefore, developers should verify the current working directory before execution.

Existing Directories

The script creates directories that may already exist. In most development environments, this is generally harmless, but teams should still understand how the underlying directory commands behave when the target structure already exists.

Naming Validation

The script validates that parameters are present, but that does not necessarily mean that the values are semantically valid. For example, a malformed package name or an entity name containing unexpected characters could produce an undesirable structure. A future version could add stricter validation.

When Should You Use This Approach?

This approach is especially useful when:

• The project has a well-defined architecture
• New entities are added frequently
• Every entity follows a similar structure
• Multiple developers work on the same codebase
• Consistency is important
• Manual folder creation has become repetitive

It may be unnecessary for very small applications where the project structure is simple.

When Should You Consider a More Advanced Generator?

A batch script is excellent for simple structural generation.

However, if the project requires extensive automation, consider moving toward a dedicated generator when you need:

• Source-code templates
• Interactive configuration
• Cross-platform support
• Advanced validation
• Automatic test generation
• Database migration generation
• API generation
• IDE integration
• Multiple architecture templates

At that point, a dedicated CLI or build-tool-based generator may provide more long-term value.

Architectural Value Beyond Folder Creation

At first glance, the script may appear to be nothing more than a collection of directory-creation commands. Its real value, however, is architectural. The script captures the team's expectations about how a new feature should be organized. Without automation, developers need to remember the architecture. With automation, the architecture becomes part of the workflow.

This creates an important principle:

Development tooling can act as an executable form of architectural documentation.

When a developer creates a new feature, the generator immediately demonstrates where different responsibilities belong.

Team-Level Benefits

For a development team, standardized scaffolding can have an even greater impact.

Consistent Code Reviews

Reviewers can focus more on business logic because structural inconsistencies are reduced.

Faster Feature Setup

Developers can start implementing functionality immediately.

Easier Maintenance

Future developers can predict where components should be located.

Reduced Knowledge Dependency

The team becomes less dependent on individual developers remembering the complete package structure.

Better Architectural Discipline

The standard structure encourages developers to keep commands, queries, and events separated.

Best Practices

To get the most value from this approach, teams should follow a few practices.

Keep the Generator Simple

A scaffolding tool should reduce complexity, not introduce more complexity.

Keep the Generated Structure Relevant

Every generated directory should have a clear purpose. Avoid creating directories that are never used.

Document the Conventions

Developers should understand why the directories exist, not just where they are located.

Review the Structure Periodically

As the architecture evolves, the generator should evolve with it.

A Practical Mental Model

The easiest way to understand this solution is to think of it as a feature template. Every new feature starts from the same foundation.

The script essentially says:

"Whenever a new entity is introduced, this is the standard architectural structure it should begin with."

The developer then fills that structure with the actual implementation.

This creates a clear separation between:

Scaffolding and Implementation

The script handles the first part. The developer handles the second.

Conclusion

A simple batch script can provide significant value when used to automate a consistent Command, Query and Event structure. Its primary purpose is not to generate business logic. Instead, it removes repetitive structural work and establishes a standardized foundation for feature development.

The approach provides several benefits:

• Faster feature initialization
• Consistent package organization
• Reduced structural errors
• Easier navigation
• Better onboarding
• Improved architectural consistency
• Repeatable development workflows

More importantly, it demonstrates a broader engineering principle:

Whenever developers repeatedly perform the same structural task, that process is a candidate for automation.

A small amount of automation at the beginning of the development lifecycle can save considerable time over the lifetime of a project. As the system grows, the same idea can evolve from a simple directory generator into a complete scaffolding solution capable of generating source files, tests, configurations, and other feature components. The current approach is therefore a practical first step toward standardized, repeatable, and architecture-aware feature development.

We spend hours using digital products every day. We order food, book tickets, make payments, shop online, check emails, manage work and scroll through more websites than we probably remember.

Some of those experiences just work.
You open the app, find what you need, get it done and move on. Others somehow turn a simple task into a five minute struggle. You can't find the button you're looking for.

The navigation doesn't make sense. A form asks for information that feels completely unnecessary. You click something and aren't sure whether anything happened. That's usually when we start noticing the design.

That's an interesting thing about UI/UX. When it's done well, you often don't notice it at all. You just use the product.

So, UI and UX... what's the difference?

These two terms get used together so often that they've almost become one phrase.
But they aren't the same thing.

UI, User Interface, is the part you can see and interact with. Buttons, typography, colors, icons, cards, forms, menus, spacing all of that falls under UI.

UX, User Experience, is a little broader. It's about what happens while you're actually trying to use the product.

Here's an everyday example. Say you're booking an appointment with a doctor online. The color of the Book Appointment button, its size, and where it sits on the page are all UI decisions.

But think about everything you need to do around that button:

Can you easily find the right doctor?

Can you see which time slots are available?

Do you need to create an account before booking?

What happens after you confirm?

Do you receive a confirmation?

That's the experience. You can have a beautiful interface and still have a terrible booking process. The opposite is also true. Something can technically work but still feel outdated, inconsistent, or difficult to use.

The best products get both sides right.

You Shouldn't Have to Figure Out How a Website Works

Open a website you've never visited before. Within a few seconds, you should have a rough idea of where you are and what you can do. Nobody should need to explain: "Okay, first click this. Then open this menu. Ignore that button. Now scroll down."

Yet we've all used products that feel exactly like that. Sometimes the problem is surprisingly small.

Take a button that says: Submit. Submit what?

Compare that with: Book My Appointment.

Now you know exactly what's about to happen. It's a tiny change, but it removes one small moment of uncertainty. Those small moments add up.

Not Everything on the Screen Can Be Important

This is something we see quite often when designing websites. Everyone involved in the project has something they want users to notice:

• The marketing team wants the offer to stand out.
• The sales team wants Book a Demo to stand out.
• Someone wants the new feature promoted.
• Someone else wants the newsletter highlighted.
• Then there's the chatbot.

And suddenly, the homepage has six things shouting for attention. The problem isn't that any one of those things is bad. The problem is that users don't know where to look.

A strong interface makes choices on behalf of the user:

• This is the main message.
• This is the primary action.
• This information is useful, but it can come later.

That hierarchy is what makes a page feel calm and easy to scan. You don't necessarily need less content. You need clearer priorities.

Every Extra Step Has a Cost

Let's say you've downloaded a new app because you want to try one specific feature.

You open it.

Create an account.

Verify your email.

Come back.

Complete your profile.

Choose your interests.

Set your preferences.

Choose a plan.

And finally you reach the feature you originally came for.

By that point, some people have already left. This is where UX goes far beyond colors and buttons.

Every screen, click, and decision between the user and their goal creates some amount of friction.

Sometimes it's necessary. A banking product obviously needs more verification than a weather app. But every step should still earn its place. One question we like to ask when looking at a user flow is: "Do we really need the user to do this right now?"

If the answer is no, maybe that step can happen later. Or perhaps it doesn't need to exist at all.

Silence From an Interface Is Surprisingly Frustrating

You click Save. Nothing happens. You click it again. Still nothing. Now you're not sure whether it saved twice, didn't save at all, or the page is simply slow.

A tiny piece of feedback would solve the entire problem. Saving...followed by:

✓ Changes saved.

That's it. The same applies everywhere.

• Uploading a file? Show the progress.
• Placing an order? Confirm it.
• Processing a payment? Tell the user.
• Something failed? Explain what happened.

Interfaces should feel like they're responding to you. When they don't, people start second-guessing their actions.

People Are Going to Make Mistakes

No matter how carefully you design something, users will eventually do something unexpected. They'll mistype their email address. Forget a required field. Upload the wrong document. Press the wrong button.

That's normal. The experience shouldn't fall apart because of it.

There's a big difference between:

"Error 402: Invalid request."

and:

"We couldn't process your payment. Your card hasn't been charged. Please try again or use another payment method."

One leaves you wondering what happened. The other tells you exactly where you stand and what you can do next. That's good UX too. It's not only about helping people move forward when everything goes right. It's also about helping them recover when something goes wrong.

Consistency Sounds Boring. It's Actually Incredibly Useful.

Imagine if the brake pedal moved every time you got into a different car. You'd eventually figure it out, but you'd have to think about something that normally requires no thought at all.

Digital products work in a similar way. If buttons, icons, navigation, and forms behave consistently, users start building familiarity. They don't need to relearn the interface on every screen.

This is also why design systems matter. A design system isn't just a beautifully organized Figma page full of buttons and color tokens. It gives the product a shared language. Designers know how components should look. Developers know how they should behave. And users get an experience that feels like one product rather than twenty screens designed independently.

Responsive Doesn't Automatically Mean Mobile Friendly

This distinction matters. You can make a desktop website technically fit inside a 390 pixel wide screen and call it responsive. That doesn't mean it's pleasant to use.

Maybe the buttons are too small.

Maybe there's too much information.

Maybe a form designed for a large monitor takes forever to complete on a phone.

Maybe a pop-up covers half the screen.

Instead of asking: "How do we make this desktop screen fit on mobile?"it can be much more useful to ask: "What is someone likely trying to do here from their phone?"

Maybe a desktop customer wants to explore every feature. A mobile visitor might just want to call you. Those are different needs, and the design should recognize that.

Accessibility Isn't Something to Add at the End

Readable text. Good contrast. Clear labels. Keyboard navigation. Visible focus states. Comfortable touch targets.

These are often discussed under accessibility, but look at that list again. Almost everything there also makes the product easier to use in general. Good contrast helps someone with low vision, but it also helps someone looking at their phone outside on a sunny afternoon. Large touch targets help people with motor impairments, but they also help someone trying to use a phone with one hand

Accessibility isn't a separate layer sitting on top of UX. It's part of designing an experience that works for real people in real situations.

Does That Mean Everything Needs to Look Simple?

Not at all. This is where discussions about usability sometimes go too far. A usable website doesn't have to be white, minimal, and boring.

Visual personality matters. Typography can have character. Colors can be bold. Animation can make interactions feel alive. Illustrations can help tell a story.

The question isn't: "Is this decorative?"It's: "Is this getting in the user's way?"

A beautiful animation that helps communicate an idea can improve the experience. A beautiful animation that makes someone wait five seconds before they can read the page probably isn't helping. You can absolutely create something distinctive without making it difficult to use.

So, What Does Good UI/UX Actually Look Like?

There's no screenshot we can point to and say, "This is what every good interface should look like."Context matters too much. A banking platform and a fashion store shouldn't feel identical. Neither should a children's learning app and an enterprise analytics dashboard.

But the underlying principles are surprisingly consistent. A strong experience is usually:

Clear: You understand what's happening.

Simple: Unnecessary complexity has been removed.

Consistent: Things behave the way you expect them to.

Useful: Elements exist for a reason

Responsive: The experience works comfortably across devices.

Accessible: More people can actually use it.

Forgiving: Making a mistake doesn't leave you stuck.

You could probably add dozens of design principles to that list. But if those seven are working, you've already solved a lot.

Why Does Any of This Matter to a Business?

Because users don't think: "The UX of this company's checkout flow is inefficient."They think: "Buying from this company is annoying."

They don't think: "The information architecture of this website needs improvement."They think: "I can't find what I'm looking for."

That's the important part. People experience the interface, but they associate that experience with the business behind it.

If your website makes things easy, your company can feel easier to work with.

If information is clear, your company can feel more transparent.

If everything works smoothly, the business feels more professional.

UI/UX isn't going to rescue a bad product or a bad business. But poor UX can absolutely make a good product harder to use, harder to understand, and harder to trust.

Maybe the Best Design Isn't the One People Notice

Designers naturally want to create things people remember. There's nothing wrong with that. But when we're designing a product, sometimes the better compliment isn't: "This looks amazing."

It's: "That was easy."

The user found what they needed. They knew what to do. Nothing confused them. Nothing got in their way. They finished what they came to do and moved on.

It doesn't sound particularly dramatic. But that's often exactly what good UI/UX looks like.

A practical walkthrough of hierarchical folder permissions, restriction-only inheritance, multi-principal evaluation, and explainable authorization — built with Spring WebFlux and React.

The problem

Most people understand file permissions intuitively:

If I can read Finance, I should be able to read what’s inside it — unless someone deliberately locked a subfolder down.

That sounds simple until you try to implement it.

Naive approaches fall into two traps:

1. Store effective permissions on every file
   Then every ACL change forces a cascade update across thousands (or millions) of descendants. Group membership changes make it worse.

2. Recompute from scratch with recursive parent walks
   Every authorization check becomes a chain of database round-trips. Latency and load explode under concurrency.

We wanted a third path: store only explicit ACL changes, calculate effective permissions on demand, and make the result explainable in the UI so developers and admins can see why a user has (or lost) DELETE.

This post describes the model and algorithm we implemented in a full-stack proof of concept:

• Backend: Spring Boot 4 + WebFlux + Reactive MongoDB
• Frontend: React + Ant Design + Tailwind
• Auth for the demo: X-User-Id header with user switching

The permission model in one sentence

Effective permissions flow from parent to child; a child may restrict what it inherited, but must never broaden it.

Permissions used:

READ · WRITE · DELETE · SHARE

ACL modes:

No explicit DENY in v1. Empty RESTRICT (permissions: []) means: clear all permissions for that subject on this branch.

A concrete example

Hierarchy:

Root
 └── Finance
      └── Payroll
           └── salaries-2026.xlsx

ACLs for Alice:

Result on the file:

Alice → salaries-2026.xlsx
  READ  ✓
  WRITE ✓
  DELETE ✕  (removed at Payroll)
  SHARE  ✕  (removed at Finance)

That is the entire product story in four rows of ACL data.

What we store (and what we don’t)

Stored

• Nodes — folders/files with parentId, ancestors[], depth, permissionBoundary, permissionVersion
• ACL entries — only where permissions change
• Users / groups — users reference groupIds

Not stored

• Effective permissions per user per file
• “Inherited copy” of parent ACLs on every descendant

Why? Effective rights depend on who is asking. Alice and Bob looking at the same Payroll folder can get different answers. Caching a single effective set on the node would be wrong.

Permission boundaries look like this:

Root        ← ACL
Finance     ← ACL
Reports     ← no ACL (inherits Finance)
2026        ← no ACL
report.pdf  ← no ACL

Only Root → Finance are boundaries for Alice’s chain. Everything under Finance inherits until the next explicit ACL.

Users, groups, and principals

An ACL targets either a USER or a GROUP.

When evaluating Alice, we expand:

USER:user-alice
GROUP:group-employees
GROUP:group-finance
GROUP:group-managers

Each principal is evaluated independently along the path. The final answer is the union of those results.

That matters:

• Employees might only have READ at Root
• Finance Team might get READ, WRITE at Finance
• Bob, in both groups, ends up with READ ∪ WRITE under Finance

If we merged all ACLs into one running set too early, the Employees READ at Root could incorrectly cap Bob’s Finance Team grant.

Materialized paths instead of recursive lookups

Every node stores:

parentId
ancestors[]
depth

Example:

Payroll.ancestors = [Root, Finance]

Authorization builds the evaluation path in one shot:

path = ancestors + [target]
     = Root → Finance → Payroll → salaries-2026.xlsx

No $graphLookup. No “fetch parent, then parent’s parent” loop on the hot path.

Subtree moves are more expensive (rewrite descendants’ ancestors), but reads stay cheap — the right trade-off for a permission-heavy system.

The ACL calculation algorithm

Here is the algorithm, step by step, as implemented in PermissionService — walked against dummy MongoDB documents.

Request we will evaluate:

GET /api/v1/nodes/file-salary-2026/permissions
X-User-Id: user-alice
X-Tenant-Id: tenant-1

Question: What is Alice’s effective permission set on salaries-2026.xlsx?

Dummy data (MongoDB collections)

users

groups

nodes (subset used for this evaluation)

acl_entries (subset relevant to Alice / this path)

(No ACL on file-salary-2026 — it inherits.)

Step 1 — Load the target node

Query mapping

nodes.find({ tenantId: "tenant-1", _id: "file-salary-2026" })

Output (from dummy nodes)

Cache key candidate

tenant-1:user-alice:file-salary-2026:1

Assume cache miss → continue evaluation.

Step 2 — Resolve principals

Input: users row user-alice

Principal expansion

principals = [
  USER:user-alice,
  GROUP:group-employees,
  GROUP:group-finance,
  GROUP:group-managers
]

Running map initialized

Step 3 — Build the evaluation path

Mapping from target node

path = ancestors + [target]
     = [folder-root, folder-finance, folder-payroll] + [file-salary-2026]

Output path (ordered root → leaf)

Step 4 — Prefetch ACLs for path nodes

Query mapping

acl_entries.find({
  tenantId: "tenant-1",
  nodeId: { $in: [
    "folder-root",
    "folder-finance",
    "folder-payroll",
    "file-salary-2026"
  ]}
})

Grouped output (aclByNode)

Step 5 — Walk the path per principal

At each node, for each principal:

1. Filter ACLs to that principal
2. Split into ALLOW / RESTRICT (union within mode)
3. Apply first-grant or intersect rules

Node 1 — folder-root (Root)

ACLs at this node vs Alice’s principals

Per-principal evaluation

Combined after Root (UNION)

{R,W,D,S} ∪ {R} ∪ ∅ ∪ ∅ = {R, W, D, S}

Step snapshot

Node 2 — folder-finance (Finance)

ACLs at this node vs Alice’s principals

Per-principal evaluation

Combined after Finance

{R,W,D} ∪ ∅ ∪ {R,W} ∪ ∅ = {R, W, D}

SHARE is gone (Alice USER restricted). Employees principal cleared. Finance group still contributes R+W.

Step snapshot

Node 3 — folder-payroll (Payroll)

ACLs at this node vs Alice’s principals

Per-principal evaluation

Combined after Payroll

{R,W} ∪ ∅ ∪ {R,W} ∪ ∅ = {R, W}

DELETE is gone (Alice USER restricted at Payroll).

Step snapshot

Node 4 — file-salary-2026 (salaries-2026.xlsx)

ACLs at this node: none for any principal.

Per-principal evaluation

Combined after file

{R,W} ∪ ∅ ∪ {R,W} ∪ ∅ = {R, W}

Step snapshot

Step 6 — Union all principals (final)

Final running map

Effective permission calculation

effective(Alice, file-salary-2026)
  = {R,W} ∪ ∅ ∪ {R,W} ∪ ∅
  = { READ, WRITE }

API-shaped output

{
  "nodeId": "file-salary-2026",
  "effectivePermissions": ["READ", "WRITE"],
  "evaluationPath": [
    { "nodeId": "folder-root",    "nodeName": "Root",               "effectiveAfter": ["READ","WRITE","DELETE","SHARE"] },
    { "nodeId": "folder-finance", "nodeName": "Finance",            "effectiveAfter": ["READ","WRITE","DELETE"] },
    { "nodeId": "folder-payroll", "nodeName": "Payroll",            "effectiveAfter": ["READ","WRITE"] },
    { "nodeId": "file-salary-2026","nodeName": "salaries-2026.xlsx","effectiveAfter": ["READ","WRITE"] }
  ]
}

Human reading

Alice → salaries-2026.xlsx
  READ  ✓
  WRITE ✓
  DELETE ✕  (removed at Payroll on USER:user-alice)
  SHARE  ✕  (removed at Finance on USER:user-alice)

Step 7 — Cache

Put

key   = tenant-1:user-alice:file-salary-2026:1
value = { READ, WRITE }

Next identical request hits cache until an ACL change bumps permissionVersion on the boundary (and descendants), which changes the key and forces recompute.

Algorithm rules (quick reference)

if running is empty:
    if ALLOW exists:   running = ALLOW
    else if RESTRICT:  running = RESTRICT
else:
    if RESTRICT exists: running = running ∩ RESTRICT
    else if ALLOW:      running = running ∩ ALLOW
else:
    inherit (no change)

effective(user, node) = ⋃ running[principal]

Empty RESTRICT (permissions: []) → intersect with ∅ → that principal is cleared on the branch (see Employees at Finance above).

Diagram of the flow

HTTP request (X-User-Id)
        │
        ▼
 CurrentUserProvider → UserPrincipal
        │
        ▼
 AuthorizationService.canAccess(READ|WRITE|DELETE|SHARE)
        │
        ▼
 PermissionService.getEffectivePermissions
        │
        ├── cache hit? → return
        │
        ├── resolve principals
        ├── load path from ancestors[]
        ├── load ACLs for path
        ├── per-principal walk (ALLOW / RESTRICT / inherit)
        ├── UNION
        └── cache put
        │
        ▼
 allow or 403

Controllers never embed permission logic. There is one calculation path.

Making permissions explainable

A boolean canDelete is not enough for a demo — or for debugging production ACLs.

We return:

• Effective set — what the user has now
• Sources — which node/subject/mode contributed each permission
• Evaluation path — node-by-node effective snapshot

The UI renders this as:

✓ READ     inherited from Root
✓ WRITE    restricted at Payroll
✕ DELETE   removed at Payroll
✕ SHARE    removed at Finance

Root      R W D S
  ↓
Finance   R W D
  ↓
Payroll   R W
  ↓
file      R W

When you switch users in the header, the same file tells a different story. That is the point of the product demo.

Frontend: permission-aware browsing

The left folder tree is not a static org chart. It calls a tree API that filters by READ. Branches you cannot see disappear.

The file list only shows children you can read.
The right-hand accordion shows effective permissions + ACL entries for the selected node.
Admins can create users/groups and assign memberships; ACL edits require WRITE on the node.

Uploaded files land on a configurable local path:

filesystem:
  storage:
    local-path: ./data/files

Metadata stays in MongoDB; bytes stay on disk under {tenantId}/{nodeId}/{filename}.

Design choices worth calling out

Why restrictions instead of arbitrary overrides?

If a child could invent DELETE without the parent having it, “folder security” becomes theater. Restriction-only inheritance matches how people think about shared drives: lock down as you go deeper, don’t escalate.

Why not DENY yet?

RESTRICT with an empty set covers “this subject gets nothing here.” Explicit DENY (override even a wider group grant) is a future mode that would apply as a final mask and must also appear in the explanation path.

Why versioned cache keys?

Invalidating “everything under Finance” in Redis is painful. Versioning the node (and descendants) means old keys simply stop matching. Local cache today; Redis tomorrow behind the same interface.

Why reactive end-to-end?

Authorization fans out into many small I/O ops (node, ACLs, cache). WebFlux + Reactor keeps that composition explicit without blocking threads on every check. No .block() on the request path.

Lessons from building the POC

1. Explainability is a feature, not a debug dump. If you cannot show the path, admins will not trust the model.
2. Principals must be separate until the end. Early merging of user + group ACLs creates subtle escalation bugs.
3. Store boundaries, compute leaves. Millions of files do not need millions of ACL documents.
4. UI and API must agree. Sorting folders first, filtering trees by READ, and allowing empty RESTRICT all had to land in both layers.
5. Demo auth is fine if the principal abstraction is real. Swap X-User-Id for JWT/OIDC later without rewriting PermissionService.

Closing

Hierarchical permissions are less about clever data structures and more about a crisp rule:

Parent effective
      │
      ▼
Child restriction   →   INTERSECT
      │
      ▼
Descendant inherits

Add multi-principal union, materialized paths, and versioned caching, and you get a system that is fast enough to query, cheap enough to update, and clear enough to debug.

If you are designing a drive, DMS, or multi-tenant workspace, start with that rule — then make the evaluation path visible. The algorithm only earns trust when the UI can show its work.

Stack reference

Built as a runnable proof of concept for inherited, restriction-only, explainable file permissions.

Document upload is a common requirement in modern applications. In a multi-tenant application, document storage must also maintain clear separation among tenants, users, and system-level documents.

In our application, we use Spring Boot, Kotlin, MongoDB, and Nextcloud to manage documents.

During tenant registration, document-storage information such as the Nextcloud user, authentication details, URL, user entities, and system entities is configured.

The main idea is :

• Nextcloud stores the actual documents.
• MongoDB stores document metadata.
• Tenant configuration defines where and how documents are stored.
• Spring Boot WebFlux manages the complete upload flow.

Complete Document Upload Flow :

1. Document Configuration During Tenant Registration

When a tenant is registered, the document storage configuration is also added. The configuration contains information such as:

• Nextcloud user
• Authentication details
• Nextcloud URL
• User entities
• System entities

This configuration tells the application which document types belong to users and which belong to the system.

2. User Entity Documents

User entity documents are documents that belong to a specific user. The storage structure is:

For example:

Here:

• syc → Tenant
• users → User document category
• fe6b7664-05e1-4221-be25-2045cb9da3c8 → User ID
• PROJECT_REPORT → User entity
• abc.pdf → Uploaded document

This structure ensures that user documents remain associated with the correct tenant and user.

3. System Entity Documents

System entity documents belong to the tenant’s system rather than to a specific user. The storage structure is:

For example:

Here:

• syc → Tenant
• system → System document category
• syc-system-1 → Default system object ID
• VEHICLE_LOG_DOCUMENT → System entity
• abc.pdf → Uploaded document

The same approach can be used for other system-level document entities.

4. Default SYSTEM Tenant

The application also has a special default SYSTEM tenant for documents that are not associated with a normal tenant.

Its structure is different from both tenant user documents and tenant system documents.

For example:

Here:

• SYSTEM → Default system tenant
• default-system-1 → Default system object ID
• SYSTEM → System entity
• abc.pdf → Uploaded document

This provides a dedicated location for application-level system documents.

5. Document Upload Process

Once the destination is determined, the application then creates the corresponding storage path.

For example, if a user uploads a PROJECT_REPORT, the application identifies:

• Tenant → syc
• User → User ID
• Entity → PROJECT_REPORT
• File → abc.pdf

and creates the corresponding storage path.

6. Benefits of the Folder Structure

The folder structure is designed to provide:

Tenant Separation - Each tenant has its own document space.

User Separation - User documents are stored under the corresponding user ID.

System Separation - System documents are stored separately from user documents.

Entity Organization - Documents are grouped according to their configured entity.

Easy Retrieval - The application can determine the document locationbased on its tenant, user/system, entity, and document information.

7. Check or Create Folder

Before uploading a document, the application checks whether the required folder exists.

This prevents the application from trying to upload a document to a non-existent location.

8. Store Document in Nextcloud

Once the required folder is available, the actual document is uploaded to Nextcloud.

Application → Document Service → Nextcloud → Tenant/User Folder → Actual Document

Nextcloud is responsible for storing the physical document, while the application manages the document’s business context and storage location.

9. Store Document Metadata

After a successful upload, the application stores the document metadata in MongoDB.

The metadata can contain information such as:

• File name
• File type
• Tenant ID
• User ID
• Entity
• Document path
• Creation information

This separation allows the application to manage document-related information without storing the actual file in MongoDB.

10. Reactive Processing

The application uses Spring WebFlux, so document operations follow a reactive programming model.

Check Folder →Create Folder → Upload Document →Save Metadata.

These operations are handled using reactive processing, avoiding unnecessary blocking operations.

New developers working on this module should therefore follow the reactive approach used throughout the application.

11. Error Handling

A document upload can fail at different stages of the process:

Validation → Folder Creation → Nextcloud Upload → Metadata Storage in MongoDB

Common problems include:

• Invalid file
• File size limit exceeded
• Incorrect folder path
• Folder creation failure
• Nextcloud authentication failure
• Document upload failure
• MongoDB failure

Proper logging and error handling are important for identifying where the upload process failed.

Sensitive information, such as authentication tokens and confidential document information, should never be written to logs.

12. Document View and Thumbnail

After storing documents in Nextcloud, the application provides separate APIs for viewing the actual document and displaying its thumbnail.

1. Document View API

The Document View API is used when the application needs to display or download the actual document.

For example:

GET /api/v1/document/{id}/view

The API identifies the document using its ID, retrieves the document metadata from MongoDB, and uses the stored Nextcloud file path and authentication details to access the actual file.

This is useful when users need to open or view the complete document.

2. Document Thumbnail API

The Thumbnail API is used to display a small preview or icon of a document, such as in document lists, cards, or dashboards.

GET /api/v1/document/{id}/thumbnail

The API first retrieves the document metadata and checks whether Nextcloud provides a preview for the file. If a preview is available, the API requests the thumbnail from the Nextcloud preview endpoint.

Why Use Separate APIs?

Using separate APIs for the actual document and its thumbnail provides better performance and a cleaner user experience.

• Document View API → Returns the actual/full document.
• Thumbnail API → Returns a small preview image.
• MongoDB → Stores and provides document metadata.
• Nextcloud → Stores the actual document and generates previews.
• Placeholder → Used when a document preview is unavailable.

The overall flow is:

                                Document ID
                                    ↓
                      Find Document Metadata in MongoDB
                                    ↓
                   Get Nextcloud File Path & Authentication
                                    ↓
                     ┌─────────────────────────────┐
                     │                             │
                     ▼                             ▼
              View Document API               Thumbnail API
                     ↓                             ↓
             Nextcloud Actual File           Nextcloud Preview
                     ↓                             ↓
               Full Document                Small Preview / Icon

This approach avoids loading large documents when only a small preview is required, which helps reduce unnecessary network and resource usage.

Conclusion

The document storage architecture can be summarized as:

For the default SYSTEM tenant, application-level documents are stored separately:

SYSTEM/default-system-1/SYSTEM/

This architecture provides a clear and organized approach to managing documents across tenants, users, system entities, and application-level system data.

The overall flow is straightforward:

Tenant Configuration → Identify Document Context → Build Storage Path → Check/Create Folder → Upload to Nextcloud → Save Metadata in MongoDB

Understanding this flow provides new developers with a solid foundation for working with the document management module.

Introduction

After successfully installing Zsh, the next step is often installing Oh My Zsh.
Oh My Zsh is a popular open-source framework for managing Zsh configurations. It simplifies customization by providing themes, plugins, aliases, and useful productivity features without requiring extensive manual configuration.
This guide explains the prerequisites, installation process, and initial setup of Oh My Zsh on Ubuntu while breaking down every command used during the process.

What is Oh My Zsh?

Oh My Zsh is a community-driven framework built on top of Zsh.
It helps users:
• Manage Zsh configurations easily
• Install and use themes
• Enable plugins
• Improve terminal productivity
• Customize the shell without editing complex configuration files
Instead of manually configuring every feature, Oh My Zsh provides a ready-to-use environment that can be customized later.

Prerequisites

Before installing Oh My Zsh, the following requirements should be met:

Requirement 1: Zsh Must Be Installed
Verify that Zsh is installed.
zsh --version
Understanding the Command
• zsh = Runs the Zsh executable.
• --version = Displays the installed version.
Example output:
zsh 5.9
If a version number is displayed, Zsh is installed successfully.

Requirement 2: Git Must Be Installed
Oh My Zsh uses Git to download and manage its files.
Check whether Git is installed:
git --version
Understanding the Command
• git = Runs the Git executable.
• --version = Displays the installed Git version.
Example output:
git version 2.43.0
If a version number appears, Git is already installed.

Installing Git (If Not Installed)
If Git is not installed, install it using:
sudo apt install git -y
Understanding the Command
• sudo = Executes the command with administrator privileges.
• apt = Ubuntu package manager.
• install = Installs a package.
• git = Package name.
• -y = Automatically confirms installation prompts.
This command downloads and installs Git.

Verifying Git Installation

After installation, verify Git again:
git --version
Successful installation displays the installed version.

Installing Oh My Zsh

Once both Zsh and Git are available, Oh My Zsh can be installed.
Execute the following command:
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/
tools/install.sh)"

Understanding the Installation Command

At first glance, this command may look complicated. Breaking it into smaller parts makes it easier to understand.

Part 1: curl
curl URL
What is curl?
curl is a command-line utility used to transfer data from servers and websites.
In this case, it downloads the Oh My Zsh installation script.

Part 2: curl Options
curl -fsSL URL
Understanding the Options
• -f = Fails silently if an error occurs.
• -s = Silent mode (hides progress information).
• -S = Displays errors even when silent mode is enabled.
• -L = Follows redirects automatically.
These options ensure that the installation script is downloaded cleanly.

Part 3: Command Substitution
$(curl -fsSL URL)
The $() syntax is called command substitution.
It means:
Execute the command inside the brackets and use its output.
The downloaded installation script becomes the output.

Part 4: sh -c
sh -c "command"
Understanding the Command
• sh = Shell interpreter.
• -c = Execute the command provided as a string.
In this installation process, sh executes the downloaded installation script.

Complete Flow
The entire command performs the following actions:

1. Downloads the latest Oh My Zsh installation script from GitHub.
2. Passes the script to the shell.
3. Executes the installation automatically.

What Happens During Installation?

During installation, Oh My Zsh performs several actions automatically:

Creates the Oh My Zsh Directory
~/.oh-my-zsh
This directory contains:
• Themes
• Plugins
• Scripts
• Configuration files

Creates a Zsh Configuration File
~/.zshrc
If a .zshrc file already exists, Oh My Zsh creates a backup before making changes.

Changes the Default Theme
The default theme is usually:
robbyrussell
This theme adds useful information such as:
• Current directory
• Git branch information
• Prompt customization

Verifying Installation

After installation completes, verify that the Oh My Zsh directory exists.
ls -la ~/.oh-my-zsh
Understanding the Command
• ls = Lists files and directories.
• -l = Detailed view.
• -a = Shows hidden files.
• ~/.oh-my-zsh = Oh My Zsh installation directory.
If installation was successful, the directory contents will be displayed.

Understanding the .zshrc File

One of the most important files in a Zsh setup is:
~/.zshrc
This file controls:
• Themes
• Plugins
• Aliases
• Environment variables
• Terminal customization
Whenever a new terminal session starts, Zsh reads this file and applies the configured settings.

Reloading Configuration Changes

Whenever changes are made to .zshrc , they can be applied without restarting the terminal.
source ~/.zshrc
Understanding the Command
• source = Executes commands from a file in the current shell session.
• ~/.zshrc = Zsh configuration file.
This command reloads the configuration immediately.

Benefits of Using Oh My Zsh

After installation, users gain access to:
Themes
Customize the appearance of the terminal.
Plugins
Add functionality for tools such as:
• Git
• Docker
• Kubernetes
• Node.js
• Python
Better Productivity
Frequently used commands become easier to execute through aliases and shortcuts.
Easier Configuration
Most customizations can be performed by editing a single file:
~/.zshrc

Key Takeaways

Installing Oh My Zsh introduces several important Linux concepts:
• Git-based software installation
• Downloading scripts using curl
• Command substitution using $()
• Shell configuration files
• Theme and plugin management
Understanding these concepts provides a solid foundation for further terminal customization.

A simple beginner-friendly guide to Advanced Product Quality Planning (APQP) in the automotive industry with examples, flow diagrams, and easy explanations.

Imagine you want to build the best toy car ever for your friends.

Would you start cutting plastic and gluing wheels together immediately?

Probably not.

You would first:

• Think about what the toy should look like
• Draw a picture
• Gather the right materials
• Build one toy
• Test if it works
• Fix any problems
• Then make lots of toys

That is exactly how car companies build real vehicles and their parts.

This process is called APQP.

What Does APQP Stand For?

APQP = Advanced Product Quality Planning

Don't let the long name scare you.

It simply means:

A step-by-step way to make sure a product is good before making thousands or millions of them.

Instead of fixing mistakes after production, companies try to prevent mistakes before production starts.

Why Do We Need APQP?

Imagine making 100,000 cars.

If one tiny bolt is installed incorrectly...

You don't fix one car.

You fix 100,000 cars.

That could cost millions of dollars.

Instead, companies follow this simple idea:

Think first. Test first. Build later.

A Simple Toy Example

Imagine your teacher says:

"Tomorrow, everyone must bring one paper airplane."

There are two ways to do it.

❌ Without APQP

Make airplane quickly

↓

It doesn't fly

↓

Teacher is unhappy

✅ With APQP

Think

↓

Choose the best paper

↓

Practice folding

↓

Test flying

↓

Improve

↓

Make the final airplane

The second approach gives everyone a much better airplane.

That's APQP.

Real Automotive Example

Suppose a company wants to manufacture a car door handle.

Without APQP

Design

↓

Manufacture 50,000 handles

↓

Oops!

The handle breaks easily.

↓

Replace every handle

This is expensive and wastes time.

With APQP

Design

↓

Build prototype

↓

Test

↓

Improve

↓

Test again

↓

Approve

↓

Mass production

Now customers receive reliable products.

Think of Building a House

You don't start by building the roof.

You follow a plan.

Idea

↓

Drawing

↓

Buy materials

↓

Build

↓

Inspect

↓

Move in

Building cars works the same way.

The 5 Phases of APQP

Every new automotive product follows five simple phases.

Phase 1 — Plan

First, understand what the customer wants.

Questions include:

• What product are we making?
• How strong should it be?
• How much should it cost?
• When should it be ready?

Example

A customer says:

"I need a steering wheel."

The team asks:

• Leather or plastic?
• Airbag included?
• Buttons required?
• What size?

This phase is all about planning.

Phase 2 — Product Design

Now engineers design the product.

Example:

Steering Wheel

Diameter: 380 mm

Leather Cover

Airbag

Control Buttons

Weight: 1.8 kg

Now everyone knows exactly what needs to be built.

Phase 3 — Process Design

The question changes.

Instead of asking:

"How should we design it?"

We ask:

"How will we manufacture it?"

Example production flow:

Raw Material

↓

Machine

↓

Assembly

↓

Painting

↓

Inspection

↓

Packaging

This phase plans how the factory will produce the product.

Phase 4 — Product & Process Validation

Now it's time to test everything.

Questions include:

• Does the product work?
• Is it safe?
• Can the factory consistently make good parts?

Example:

Manufacture 300 steering wheels.

Test every one.

If everything passes...

Production can begin.

If not...

Fix the problem and test again.

Phase 5 — Production

Everything has been approved.

Now the factory starts producing thousands—or even millions—of parts.

Even during production, quality is checked continuously.

The Complete APQP Flow

Customer Requirement

        │

        ▼

Phase 1
Planning

        │

        ▼

Phase 2
Product Design

        │

        ▼

Phase 3
Process Design

        │

        ▼

Phase 4
Testing & Validation

        │

        ▼

Problems Found?

   Yes ────────────────┐
        │              │
        ▼              │
   Improve Design      │
        │              │
        └──────► Test Again

No

↓

Phase 5

Mass Production

Another Easy Example: Baking Cookies 🍪

Imagine your mom wants to bake cookies.

Phase 1

Choose a recipe.

Phase 2

Select ingredients.

Flour

Sugar

Butter

Chocolate Chips

Phase 3

Plan the baking process.

Mix

↓

Shape

↓

Bake

↓

Cool

↓

Pack

Phase 4

Taste one cookie.

Too hard?

Add more butter.

Too soft?

Bake longer.

Phase 5

Bake 500 cookies using the improved recipe.

That's APQP in everyday life.

Another Automotive Example

Suppose a company is designing a brake pedal.

Without APQP

Design

↓

Manufacture

↓

Customer uses pedal

↓

Pedal breaks

A dangerous situation.

With APQP

Customer Requirement

↓

Design

↓

Computer Simulation

↓

Prototype

↓

Strength Testing

↓

Improve

↓

Mass Production

Now the brake pedal is much safer.

APQP Is Like Preparing for an Exam

Imagine you have a big school exam.

What would you do?

Study

↓

Practice

↓

Find Mistakes

↓

Practice Again

↓

Take Exam

↓

Pass

You don't wait until the exam to discover what you don't know.

Car companies think the same way.

They don't wait until customers find problems.

They discover and fix problems first.

Who Works During APQP?

Many different teams work together.

Everyone collaborates from the beginning.

An Easy Way to Remember APQP

Think of APQP as this simple journey:

Think

↓

Plan

↓

Design

↓

Build

↓

Test

↓

Improve

↓

Produce

Or even shorter:

Think → Plan → Test → Improve → Produce

Key Benefits of APQP

Using APQP helps companies:

• Reduce mistakes
• Improve product quality
• Lower manufacturing costs
• Prevent customer complaints
• Improve safety
• Deliver products on time
• Build consistent products every time

Final Summary

APQP is simply a smart planning process used by automotive companies.

Instead of rushing into production, companies:

1. Understand customer needs
2. Design the product
3. Design the manufacturing process
4. Test everything carefully
5. Start mass production only after everything works

Just like practicing before a school play or testing a recipe before serving guests, APQP helps manufacturers build safer, better, and more reliable products.

Remember This One Sentence

APQP is like practicing before the final performance—you plan everything, test everything, fix every mistake, and only then build thousands of products with confidence.

Learn how to design, analyze, and improve a business using the Business Model Canvas (BMC) framework. This guide explains each of the nine building blocks with a practical QMS (Quality Management System) Issue Management Platform example.

What is a Business Model Canvas?

A Business Model Canvas (BMC) is a one-page strategic framework that helps organizations visualize how a business creates, delivers, and captures value.

Instead of writing a lengthy business plan, the Business Model Canvas allows founders, product managers, consultants, and business leaders to quickly understand:

• Who are the customers?
• What value is being delivered?
• How is value delivered?
• How does the business generate revenue?
• What resources and partners are required?

The framework was introduced by Alexander Osterwalder and has become one of the most widely used business planning tools worldwide.

Why Use a Business Model Canvas?

Business Model Canvas helps organizations:

• Validate business ideas quickly
• Align teams around a common business vision
• Identify business risks
• Improve existing business models
• Discover new revenue opportunities
• Simplify strategic planning
• Present ideas to investors and stakeholders

The 9 Building Blocks of Business Model Canvas

The Business Model Canvas consists of nine interconnected building blocks.

Reference - https://en.wikipedia.org/wiki/Business_model_canvas

1. Customer Segments

What is it?

Customer Segments define who your customers are.

Every business serves one or more customer groups. Understanding them is the first step toward building a successful product.

Ask yourself:

• Who are our customers?
• Who gets the most value?
• Who pays?
• Who uses the product?

Example: QMS Issue Management Platform

Primary customers include:

• OEM Quality Engineers
• OEM Supplier Quality Teams
• Supplier Engineers
• Supplier Managers
• Supplier Quality Teams

Why it matters

Without clearly identifying customer segments, it becomes difficult to create products that solve real problems.

2. Value Proposition

What is it?

The Value Proposition explains why customers choose your product instead of alternatives.

It answers:

What problem are you solving?

Examples include:

• Saving time
• Reducing cost
• Improving quality
• Increasing productivity
• Better customer experience

Example: QMS Issue Management Platform

For OEMs

• Real-time supplier issue tracking
• Faster issue resolution
• Centralized quality management
• Better supplier performance visibility

For Suppliers

• Receive issues instantly
• Track corrective actions
• Automated reminders
• Better collaboration with OEMs

Why it matters

Customers don't buy software.

They buy solutions to their problems.

3. Key Resources

What is it?

Key Resources are the assets required to deliver your value proposition.

They can include:

• Technology
• Software
• Infrastructure
• Employees
• Brand
• Data
• Intellectual Property

Example: QMS Issue Management Platform

Key resources include:

• Cloud Platform
• Issue Tracking Software
• Notification Engine
• Reporting Dashboard
• Supplier Network
• Customer Database
• Security Infrastructure
• Development Team

Why it matters

Without the right resources, the business cannot operate effectively.

4. Key Partners

What is it?

Key Partners are organizations that help your business succeed.

Examples:

• Suppliers
• Technology providers
• Cloud vendors
• Consultants
• Payment providers

Example: QMS Issue Management Platform

Partners include:

• OEM Companies
• Supplier Organizations
• Cloud Infrastructure Providers
• Email & Notification Services
• Authentication Providers
• Technology Vendors
• Compliance Consultants

Why it matters

Strategic partnerships reduce costs and increase business capabilities.

5. Key Activities

What is it?

Key Activities describe the critical work required to operate the business.

Examples include:

• Software development
• Marketing
• Customer support
• Sales
• Operations

Example: QMS Issue Management Platform

Important activities:

• Build platform
• Maintain software
• Deploy new features
• Monitor system uptime
• Customer onboarding
• Technical support
• Security updates
• Regulatory compliance
• Platform monitoring

Why it matters

Activities transform resources into customer value.

6. Customer Relationships

What is it?

Customer Relationships describe how you interact with customers throughout their journey.

Examples include:

• Self-service
• Personal support
• Dedicated account manager
• Community forums
• Knowledge base

Example: QMS Issue Management Platform

Relationship methods:

• 99.9% System Availability
• Automated Notifications
• Email Alerts
• Help Desk
• Knowledge Base
• Training Sessions
• Customer Success Team
• SLA-based Support

Why it matters

Strong customer relationships improve retention and satisfaction.

7. Revenue Streams

What is it?

Revenue Streams explain how the business earns money.

Possible models include:

• Subscription
• Licensing
• Usage-based pricing
• Premium support
• Consulting
• Advertising

Example: QMS Issue Management Platform

Revenue sources:

• Subscription per organization
• Number of users
• Number of issues managed
• Data storage usage
• Premium analytics
• Enterprise support
• API integrations
• Training services

Why it matters

Revenue determines business sustainability.

8. Cost Structure

What is it?

Cost Structure identifies where money is spent.

Typical costs include:

• Salaries
• Cloud hosting
• Marketing
• Licenses
• Infrastructure
• Research
• Customer Support

Example: QMS Issue Management Platform

Major costs:

• Employee Salaries
• Cloud Infrastructure
• Technology Development
• Software Licenses
• Marketing
• Customer Support
• Security Compliance
• Research & Development

Why it matters

Understanding costs helps improve profitability.

9. Channels

What is it?

Channels define how customers discover, purchase, and use your product.

Examples include:

• Website
• Mobile App
• Web Application
• Social Media
• Sales Team
• Partners

Example: QMS Issue Management Platform

Customer channels:

• Web Application
• Mobile Application
• Email
• Sales Team
• Customer Portal
• Social Media
• Product Demonstrations
• Online Documentation

Why it matters

Even a great product needs effective channels to reach customers.

Business Model Canvas Example

QMS Issue Management Platform

Tips for Creating an Effective Business Model Canvas

✅ Focus on solving customer problems.

✅ Keep customer segments specific.

✅ Clearly define your unique value proposition.

✅ Identify measurable revenue streams.

✅ Build strategic partnerships.

✅ Regularly revisit and update your canvas.

✅ Validate assumptions through customer feedback.

Common Mistakes

• Trying to serve everyone
• Weak value proposition
• Ignoring customer relationships
• Missing revenue strategy
• Underestimating operating costs
• Not identifying key partners
• Treating the canvas as a one-time activity

Benefits of Using Business Model Canvas

• Simple one-page business overview
• Faster strategic planning
• Easier stakeholder communication
• Better product-market fit
• Improved innovation
• Faster business validation
• Supports agile business development

Conclusion

The Business Model Canvas is one of the most effective frameworks for understanding and designing a business. By breaking a business into nine essential building blocks, teams can quickly identify strengths, weaknesses, opportunities, and risks.

Whether you're launching a startup, improving an existing product, or building an enterprise platform like a QMS Issue Management System, the Business Model Canvas provides a structured way to think about customers, value, operations, and financial sustainability.

A well-maintained Business Model Canvas is not just a planning document—it becomes a living blueprint that evolves alongside your business.

Before deciding whether to build software internally or purchase an existing solution, organizations should first understand which part of the business the software supports. The answer is not purely technical—it is a strategic business decision.

Introduction: Why Build vs Buy Matters

Every organization eventually faces the question:

Should we build this solution ourselves or buy an existing product?

Building software requires significant investment in engineering talent, maintenance, and long-term ownership. Buying software accelerates implementation but may limit flexibility and differentiation.

The right decision depends on how strategically important the capability is to the business.

Understanding Technology Solutions

Not every software system contributes equally to business success.

Some systems create competitive advantage.

Others simply help run the business efficiently.

Understanding this difference is the foundation of Build vs Buy decisions.

Business Domains and Subdomains

A business can be divided into multiple subdomains.

These subdomains generally fall into three categories:

Generic Subdomain

Generic subdomains solve problems that almost every organization has.

Examples include:

• Email
• Payroll
• HR Management
• Accounting
• Calendar
• Authentication

These functions rarely differentiate one company from another.

Recommended Strategy

✅ Buy established products

or

✅ Use SaaS platforms

Examples:

• Microsoft 365
• Google Workspace
• SAP SuccessFactors
• Workday

Building these systems usually offers little business value.

Supporting Subdomain

Supporting subdomains are important but are not the primary reason customers choose your business.

Examples:

• CRM customization
• Vendor Management
• Procurement
• Reporting
• Customer Support

These systems often require organization-specific workflows.

Recommended Strategy

• Buy a mature product
• Customize where necessary
• Outsource implementation if appropriate

This provides flexibility without reinventing existing capabilities.

Core Subdomain

Core subdomains are where the organization creates unique value.

They represent the company's competitive advantage.

Examples:

• Recommendation engine (Netflix)
• Search algorithm (Google)
• Route optimization (Uber)
• Pricing engine
• Risk model
• Trading platform

These capabilities differentiate the business from competitors.

Recommended Strategy

✅ Build internally

Maintain ownership of:

• source code
• business rules
• intellectual property
• innovation

This is where the organization's best engineering team should focus.

Why Categorization Comes Before Build vs Buy

Many organizations make Build vs Buy decisions too early.

Instead, they should first ask:

Which business subdomain does this solution belong to?

Once categorized, the strategy becomes much clearer.

Categorization removes ambiguity and aligns technology investment with business goals.

Core Subdomain: Build or Outsource?

Core subdomains represent the organization's competitive advantage. They contain the business logic, proprietary algorithms, and unique processes that differentiate the company from its competitors.

Unlike generic or supporting subdomains, core capabilities should rarely be purchased as off-the-shelf products because doing so may limit differentiation.

However, organizations don't always need to build everything with a fully in-house engineering team.

The real decision is often:

Build with your own team or Build with a trusted outsourcing partner.

Option 1: Build In-house

Building internally is ideal when:

• The capability is strategically critical.
• Business requirements evolve rapidly.
• Close collaboration with domain experts is required.
• The organization wants complete ownership of the product and intellectual property.
• Long-term innovation is a priority.

Advantages

• Complete control over architecture and roadmap
• Faster business feedback loops
• Strong knowledge retention
• Better protection of intellectual property
• Continuous innovation

Option 2: Build with an Outsourcing Partner

Outsourcing does not mean giving away your competitive advantage.

Instead, it means extending your engineering capacity while retaining ownership of the solution.

The business continues to own:

• Product vision
• Business rules
• Architecture decisions
• Intellectual property
• Source code
• Product roadmap

The outsourcing partner contributes engineering expertise and delivery capacity.

When Outsourcing Makes Sense

• Need to scale engineering teams quickly
• Limited availability of specialized skills
• Faster time-to-market is important
• Temporary increase in development workload
• Cost optimization without compromising ownership

Benefits of Outsourcing Core Development

• Access to experienced engineers
• Faster product development
• Reduced hiring time
• Flexible team scaling
• Lower operational overhead
• Ability for internal teams to focus on product strategy and innovation

The key is that the outsourced team works as an extension of the internal engineering organization, not as an independent owner of the product.

Build vs Outsource Decision

Important Principle

Whether development is performed by internal employees or an outsourcing partner, the organization should retain ownership of the product, architecture, intellectual property, and business knowledge.

The strategic mistake is not outsourcing development—it is outsourcing ownership and decision-making.

Think of outsourcing as adding more skilled engineers to your team, while keeping product strategy, business expertise, and innovation firmly under your control.

             Core Business Capability
                      │
      ┌───────────────┴───────────────┐
      │                               │
 Build In-house                 Build via Outsourcing
      │                               │
      └───────────────┬───────────────┘
                      │
          Business Owns Everything
    • Product Vision
    • Architecture
    • Source Code
    • Intellectual Property
    • Product Roadmap

Build vs Buy Decision Matrix

Decision flow:

New Requirement
        │
        ▼
Identify Business Subdomain
        │
        ├──────── Generic ───────► Buy
        │
        ├──────── Supporting ────► Buy + Customize
        │
        └──────── Core ──────────► Build

Maximizing ROI Through Core Investment

Technology budgets are always limited.

Organizations achieve the highest return on investment by allocating their best resources toward core business capabilities.

Instead of spending months building payroll or email systems, engineering teams should focus on solving problems that directly improve:

• customer experience
• revenue generation
• operational excellence
• competitive differentiation

This creates long-term strategic value.

Common Mistakes

Building Generic Solutions

• Reinvents existing software
• High maintenance cost
• Low business value

Buying Core Capabilities

• Loss of differentiation
• Vendor dependency
• Limited innovation

Treating Every Requirement as "Special"

Not every business process is unique.

Many organizations overestimate the uniqueness of their operations, resulting in unnecessary custom development.

Key Takeaways

• Build vs Buy is a business strategy, not just a technical decision.
• Categorize business domains before selecting a technology approach.
• Buy solutions for generic capabilities.
• Buy and customize supporting capabilities.
• Build core capabilities using the organization's strongest engineering team.
• Invest engineering effort where it creates competitive advantage.
• Businesses maximize ROI by focusing technology investment on their core subdomains.

Final Thought

A successful technology strategy is not about building everything.

It is about building only what makes your business unique and leveraging proven solutions for everything else.

Organizations that consistently apply this principle deliver software faster, reduce costs, and invest where innovation creates the greatest business value.

Sending marketing emails at scale can be one of the most effective ways to reach users, drive engagement, and grow revenue. However, poor practices can quickly lead to spam complaints, high bounce rates, or even domain blacklisting.

Below are essential best practices to ensure your email campaigns are effective, compliant, and well-received.

1. Always Include an Unsubscribe Link

Every marketing email must include a clear and easy way for users to opt out.

Why it matters:

• Required by regulations like GDPR, CAN-SPAM, and similar laws
• Builds trust with recipients
• Reduces spam complaints

Best practices:

• Place the unsubscribe link in the footer
• Make the process one-click or simple (no login required)
• Process unsubscribe requests immediately

2. Avoid Sending Too Many Emails in a Short Time

Email fatigue is real. Overloading users leads to higher unsubscribe rates and lower engagement.

Why it matters:

• Protects sender reputation
• Improves open and click-through rates
• Prevents users from marking emails as spam

Best practices:

• Set a consistent sending schedule (e.g., weekly or bi-weekly)
• Use frequency caps per user
• Segment audiences to control email volume per group

3. Validate Email Addresses Before Sending

Invalid or fake email addresses can damage deliverability and sender reputation.

Why it matters:

• Reduces bounce rates
• Improves inbox placement
• Saves cost on email service providers

Best practices:

• Use real-time email validation during sign-up
• Periodically clean your email list
• Remove hard bounces automatically

4. Segment Your Audience

Not all users should receive the same message.

Why it matters:

• Increases relevance and engagement
• Reduces unsubscribe rates
• Improves conversion rates

Best practices:

• Segment by behavior (clicks, purchases, activity)
• Segment by demographics (location, language, age)
• Segment by lifecycle stage (new users, active users, churned users)

5. Use Double Opt-In for Subscriptions

Double opt-in requires users to confirm their email address before being added to your list.

Why it matters:

• Ensures valid email addresses
• Confirms user intent
• Improves list quality

6. Monitor Deliverability Metrics

Tracking performance helps you identify issues early.

Key metrics to watch:

• Bounce rate
• Open rate
• Click-through rate (CTR)
• Spam complaint rate
• Unsubscribe rate

Best practices:

• Set up domain authentication (SPF, DKIM, DMARC)
• Use a reputable email service provider
• Warm up new domains gradually

7. Write Clear and Honest Subject Lines

Misleading subject lines may increase opens short-term but harm trust long-term.

Best practices:

• Keep subject lines concise
• Avoid spam trigger words (e.g., "FREE!!!", "URGENT!!!")
• Ensure content matches the subject line

8. Optimize Email Content and Design

A well-structured email improves engagement.

Best practices:

• Use responsive design for mobile users
• Keep paragraphs short and scannable
• Include a single primary call-to-action (CTA)
• Avoid overly image-heavy emails (can trigger spam filters)

9. Respect Time Zones and Sending Time

Sending emails at the right time improves engagement rates.

Best practices:

• Analyze user behavior by region
• Schedule emails during active hours
• Test different send times (A/B testing)

10. Maintain a Clean Sender Reputation

Your domain and IP reputation determine whether emails reach inboxes.

Best practices:

• Avoid sudden spikes in email volume
• Regularly remove inactive users
• Monitor blacklists
• Use dedicated IPs if sending at high volume

11. Provide Value in Every Email

Users should feel that opening your email is worth their time.

Best practices:

• Share useful content, not just promotions
• Personalize messages where possible
• Avoid repetitive or irrelevant messaging

Conclusion

Effective bulk email marketing is a balance between compliance, technical setup, and user experience. By following these best practices, you can improve deliverability, maintain trust, and maximize engagement over time.

Useful links and references

Remember: a high-quality email list is more valuable than a large but disengaged one.

1. Domain Registration

Before setting up your mail server, you need a domain.

Steps

1. Register a domain from a registrar:

   • Namecheap
   • GoDaddy
   • Cloudflare Registrar
   • Google Domains (if available in your region)

2. Choose a domain like: example.com

3. Ensure you have access to DNS management.

2. Server Requirements

You need an Ubuntu 24.04 server with:

• Static public IP (important)
• Open ports:
  • 25 (SMTP)
  • 587 (Submission)
  • 465 (SMTPS optional)
  • 143 (IMAP)
  • 993 (IMAPS)
  • 110 (POP3 optional)
  • 995 (POP3S optional)

3. Update System

sudo apt update && sudo apt upgrade -y

4. Install Postfix (SMTP Server)

Installation

sudo apt install postfix -y

During installation:

• Select: Internet Site
• Set system mail name: example.com

Configure Postfix

Edit:

sudo nano /etc/postfix/main.cf

Basic configuration:

myhostname = mail.example.com
mydomain = example.com
myorigin = /etc/mailname
inet_interfaces = all
inet_protocols = all

mydestination = $myhostname, localhost.$mydomain, localhost, $mydomain
home_mailbox = Maildir/

smtpd_banner = $myhostname ESMTP

Enable SMTP authentication

Later we integrate with Dovecot:

smtpd_sasl_auth_enable = yes
smtpd_sasl_type = dovecot
smtpd_sasl_path = private/auth
smtpd_recipient_restrictions =
    permit_sasl_authenticated,
    permit_mynetworks,
    reject_unauth_destination

5. Install Dovecot (IMAP/POP3 Server)

sudo apt install dovecot-core dovecot-imapd dovecot-pop3d -y

Configure Mailbox Format

Edit:

sudo nano /etc/dovecot/conf.d/10-mail.conf

Set:

mail_location = maildir:~/Maildir

Enable IMAP & POP3

Edit:

sudo nano /etc/dovecot/dovecot.conf

Ensure:

protocols = imap pop3

Configure Authentication Socket for Postfix

Edit:

sudo nano /etc/dovecot/conf.d/10-master.conf

Add:

service auth {
  unix_listener /var/spool/postfix/private/auth {
    mode = 0660
    user = postfix
    group = postfix
  }
}

6. Install OpenDKIM (Email Signing)

sudo apt install opendkim opendkim-tools -y

Generate DKIM key

sudo opendkim-genkey -s mail -d example.com

Move keys:

sudo mv mail.private /etc/opendkim/keys/example.com/

Configure OpenDKIM

Edit:

sudo nano /etc/opendkim.conf

Add:

Domain                  example.com
KeyFile                 /etc/opendkim/keys/example.com/mail.private
Selector                mail
Socket                  local:/var/spool/postfix/run/opendkim/opendkim.sock

Connect to Postfix

smtpd_milters = local:/var/spool/postfix/run/opendkim/opendkim.sock
non_smtpd_milters = local:/var/spool/postfix/run/opendkim/opendkim.sock

7. DNS Configuration (VERY IMPORTANT)

All DNS records must be configured correctly for deliverability.

7.1 A Record

mail.example.com → x.x.x.x

7.2 MX Record

example.com → mail.example.com (priority 10)

7.3 SPF (TXT record)

example.com TXT

v=spf1 mx ip4:x.x.x.x -all

7.4 DKIM Record

mail._domainkey.example.com TXT

v=DKIM1; k=rsa; p=PUBLIC_KEY_HERE

7.5 DMARC Record

_dmarc.example.com TXT

v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com; adkim=s; aspf=s; pct=100

Recommended later:

p=reject

7.6 MTA-STS (Security)

DNS record:

_mta-sts.example.com TXT

v=STSv1; id=2026070501

Policy file:

Host:

https://mta-sts.example.com/.well-known/mta-sts.txt

Content:

version: STSv1
mode: enforce
mx: mail.example.com
max_age: 604800

7.7 TLS Reporting (TLS-RPT)

_smtp._tls.example.com TXT

v=TLSRPTv1; rua=mailto:tlsrpt@example.com

8. SSL/TLS Setup (Let’s Encrypt)

Install Certbot:

sudo apt install certbot -y

Generate certificate:

sudo certbot certonly --standalone -d mail.example.com

Configure Postfix TLS:

smtpd_tls_cert_file=/etc/letsencrypt/live/mail.example.com/fullchain.pem
smtpd_tls_key_file=/etc/letsencrypt/live/mail.example.com/privkey.pem
smtpd_tls_security_level=may

Configure Dovecot TLS:

ssl = required
ssl_cert = </etc/letsencrypt/live/mail.example.com/fullchain.pem
ssl_key = </etc/letsencrypt/live/mail.example.com/privkey.pem

9. Open Required Ports

sudo ufw allow 25
sudo ufw allow 587
sudo ufw allow 465
sudo ufw allow 143
sudo ufw allow 993
sudo ufw enable

10. Restart Services

sudo systemctl restart postfix
sudo systemctl restart dovecot
sudo systemctl restart opendkim

11. Testing Email Setup

Check DNS

dig MX example.com
dig TXT example.com

Check DKIM

opendkim-testkey -d example.com -s mail -vvv

Send test email

Use:

• Gmail
• Mail-Tester.com

Check:

• SPF PASS
• DKIM PASS
• DMARC PASS

12. Deliverability Best Practices

To avoid spam filtering:

Always:

• Use verified email lists
• Enable unsubscribe links
• Warm up IP gradually
• Monitor bounce rates

Avoid:

• Bulk sending immediately
• Purchased email lists
• High bounce rates

13. Production Architecture Recommendation

For better scalability:

Apps → Postfix (queue) → DKIM → SMTP → Internet
        ↓
   Dovecot (mailboxes)

For marketing:

• Use separate domain or IP
• Use rate limiting
• Track engagement

14. Summary

A production email server requires:

• Proper DNS (SPF, DKIM, DMARC)
• Correct Postfix + Dovecot configuration
• TLS encryption
• IP reputation management
• Controlled sending behavior

Final Note

Self-hosted email servers give full control but require careful management of:

• reputation
• deliverability
• rate limits

For bulk marketing, consider separating transactional mail and marketing infrastructure to maintain inbox placement quality.

This repository uses a multi-environment GitLab CI/CD pipeline for a Spring Boot Reactive (WebFlux) application.

The pipeline provides:

• Automated build and deployment
• Parallel deployment to multiple test environments
• Mattermost notifications with changelog support
• Automatic handling of unavailable GitLab runners
• Deployment status tracking
• Production deployment authorization controls
• Deployment failure notifications with job logs

Architecture

Test Environments

Both environments build and deploy independently.

Pipeline success requires at least one test deployment to complete successfully.

Pipeline Stages

notify_start
    │
    ▼
build_test
    ├── build_test_th
    ├── build_test_kp
    └── pending_job_monitor_build_test
    │
    ▼
deploy_test
    ├── deploy_test_th
    ├── deploy_test_kp
    └── pending_job_monitor_deploy_test
    │
    ▼
pipeline_complete
    │
    ▼
deploy_prod (manual)

Stage Details

1. notify_start

Purpose

Sends a pipeline start notification to Mattermost.

Features

• Includes pipeline link
• Includes changelog
• Displays recent commits

Example:

🚀 Build STARTED

Changes in this build:

- abc123 Fixed login issue
- def456 Added Kafka consumer
- ghi789 Updated API validation

2. build_test

Jobs

build_test_th

Builds application for TH environment.

build_test_kp

Builds application for KP environment.

Build Process

1. Copy example property files
2. Generate environment-specific property file
3. Run Gradle build

./gradlew clean build \
-Pspring.config.additional-location=file:./application-test.properties

Generated Artifacts

build/libs/spring-boot-template-cqrs-1.0.0.jar
application-test.properties

Artifacts expire after:

1 day

3. Runner Availability Monitoring

pending_job_monitor_build_test

Problem:

If a dedicated runner is unavailable, jobs can remain stuck in Pending.

Solution:

After 30 seconds:

1. Wait configured timeout
2. Query GitLab API
3. Detect pending jobs
4. Cancel stuck jobs automatically

Current timeout:

PENDING_JOB_TIMEOUT=15

4. deploy_test

Jobs

deploy_test_th

Deploys build artifact to TH environment.

deploy_test_kp

Deploys build artifact to KP environment.

Deployment Flow

Step 1

Backup existing JAR

old.jar -> old.jar_bkp

Step 2

Upload new JAR

scp build/libs/app.jar

Step 3

Upload generated property file

scp application.properties

Step 4

Execute remote deployment command

Example:

docker compose restart

or

systemctl restart my-service

Deployment Validation

Deployment only proceeds if:

Build succeeded
AND
Artifact exists

Otherwise deployment is skipped.

5. Runner Availability Monitoring (Deploy)

pending_job_monitor_deploy_test

Automatically cancels deploy jobs that remain pending due to unavailable runners.

6. pipeline_complete

Purpose

Determines final pipeline status.

Success Criteria

Pipeline succeeds if:

TH deployment succeeded
OR
KP deployment succeeded

Failure Criteria

Pipeline fails if:

TH deployment failed
AND
KP deployment failed

Examples:

7. deploy_prod

Type

Manual deployment.

Authorization

Only approved GitLab users can deploy to production.

Validation:

GITLAB_USERS_IDS_FOR_PROD_DEPLOY

contains:

GITLAB_USER_ID

Unauthorized users receive:

❌ User is not authorized for production deployment

Production Deployment Steps

1. Backup current JAR
2. Upload new JAR
3. Upload property file
4. Execute production deployment command
5. Send Mattermost notification

Mattermost Notifications

Start Notification

Color:

Blue

Example:

🚀 Build STARTED

Deployment Success

Color:

Purple

Example:

✅ TH Deploy SUCCESS

Pipeline Success

Color:

Green

Example:

🎉 Pipeline SUCCESS

Failure Notification

Color:

Red

Includes:

• Error details
• Last 50 log lines
• Pipeline link
• Job URL

Example:

❌ Deploy FAILED

Job Log:
...

Changelog Generation

Each pipeline automatically generates a changelog.

Information included:

• Commit hash
• Author
• Commit message

Example:

- abc123 Added Kafka consumer [John]
- def456 Fixed Redis configuration [Mike]

Limits:

Required GitLab Variables

General

APP_NAME

GYRI_TEST_PROPERTY_FILE

GYRI_TEST_MATTERMOST_WEBHOOK
ALL_FAIL_MATTERMOST_WEBHOOK

GITLAB_API_TOKEN

TH Environment

GYRI_TEST_TH_SERVER_USER
GYRI_TEST_TH_SERVER_01
GYRI_TEST_TH_SERVER_01_DEPLOYMENT_PATH

TEST_TH_DEPLOY_COMMAND

TEST_TH_APP_LOG_FILE_PROPERTY
TEST_TH_APP_BASE_SERVER_URL
TEST_TH_SWAGGER_SERVER_URL

TEST_TH_REDIS_HOST
TEST_TH_REDIS_PORT
TEST_TH_REDIS_TOPIC_PREFIX

TEST_TH_MONGO_HOST
TEST_TH_MONGO_PORT
TEST_TH_MONGO_DATABASE
TEST_TH_MONGO_USERNAME
TEST_TH_MONGO_PASSWORD
TEST_TH_MONGO_AUTH_DATABASE

TEST_TH_KAFKA_SECURITY_PROTOCOL
TEST_TH_KAFKA_SASL_MECHANISM
TEST_TH_KAFKA_SASL_JAAS_CONFIG
TEST_TH_KAFKA_SERVERS
TEST_TH_KAFKA_CONSUMER_GROUP_ID
TEST_TH_KAFKA_TOPIC_PREFIX

KP Environment

GYRI_TEST_KP_SERVER_USER
GYRI_TEST_KP_SERVER_01
GYRI_TEST_KP_SERVER_01_DEPLOYMENT_PATH

TEST_KP_DEPLOY_COMMAND

TEST_KP_APP_LOG_FILE_PROPERTY
TEST_KP_APP_BASE_SERVER_URL
TEST_KP_SWAGGER_SERVER_URL

TEST_KP_REDIS_HOST
TEST_KP_REDIS_PORT
TEST_KP_REDIS_TOPIC_PREFIX

TEST_KP_MONGO_HOST
TEST_KP_MONGO_PORT
TEST_KP_MONGO_DATABASE
TEST_KP_MONGO_USERNAME
TEST_KP_MONGO_PASSWORD
TEST_KP_MONGO_AUTH_DATABASE

TEST_KP_KAFKA_SECURITY_PROTOCOL
TEST_KP_KAFKA_SASL_MECHANISM
TEST_KP_KAFKA_SASL_JAAS_CONFIG
TEST_KP_KAFKA_SERVERS
TEST_KP_KAFKA_CONSUMER_GROUP_ID
TEST_KP_KAFKA_TOPIC_PREFIX

Production

GYRI_PROD_SERVER_USER
GYRI_PROD_SERVER_HOST
GYRI_PROD_SERVER_SSH_PORT
GYRI_PROD_SERVER_DEPLOYMENT_PATH

PROD_DEPLOY_COMMAND

GYRI_PROD_MATTERMOST_WEBHOOK

GITLAB_USERS_IDS_FOR_PROD_DEPLOY

GitLab Runner Registration

The pipeline requires three runners:

Install GitLab Runner

Ubuntu/Debian

curl -L \
https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh \
| sudo bash

sudo apt install gitlab-runner

Verify:

gitlab-runner --version

Register TH Runner

sudo gitlab-runner register

Prompts:

GitLab URL:
https://gitlab.example.com

Registration Token:
<project-runner-token>

Description:
th-runner

Tags:
th-runner

Executor:
shell

Register KP Runner

sudo gitlab-runner register

Prompts:

GitLab URL:
https://gitlab.example.com

Registration Token:
<project-runner-token>

Description:
kp-runner

Tags:
kp-runner

Executor:
shell

Register Production Runner

sudo gitlab-runner register

Prompts:

GitLab URL:
https://gitlab.example.com

Registration Token:
<project-runner-token>

Description:
prod-runner

Tags:
prod-runner

Executor:
shell

Verify Registered Runners

sudo gitlab-runner list

Example:

th-runner
kp-runner
prod-runner

Start Runner Service

sudo systemctl enable gitlab-runner
sudo systemctl start gitlab-runner

Check status:

sudo systemctl status gitlab-runner

Deployment Directory Structure

Expected structure on target servers:

template-spring-cqrs-reactjs/

├── server/
│
├── artifacts/
│   ├── application.jar
│   └── application.jar_bkp
│
└── server-config/
    └── application.properties

Failure Handling

The pipeline is designed to tolerate infrastructure failures.

Examples:

TH Runner Offline

TH Build → Failed

KP Build → Success

KP Deploy → Success

Pipeline → SUCCESS

KP Runner Offline

TH Build → Success

TH Deploy → Success

Pipeline → SUCCESS

Both Runners Offline

TH Build → Failed

KP Build → Failed

Pipeline → FAILED

Summary

This pipeline provides:

• Multi-location deployment (TH + KP)
• Spring Boot Reactive build automation
• Automatic changelog generation
• Mattermost notifications
• Job log reporting on failures
• Runner health monitoring
• Automatic cancellation of stuck jobs
• Production deployment authorization
• Artifact backup and rollback preparation
• High availability deployment strategy

If you've recently upgraded to React Redux v9 and are using IntelliJ, VS Code, or another TypeScript-aware IDE, you may have noticed a warning when hovering over connect():

@deprecated
We recommend using the useSelector and useDispatch hooks instead.
See https://react-redux.js.org/api/hooks

If you need to use connect without this visual deprecation warning,
import legacy_connect instead:

import { legacy_connect as connect } from 'react-redux'

This can be surprising, especially because many existing React applications still use connect() extensively.

Let's understand what's happening and explore the available options.

Is connect() Actually Deprecated?

Not exactly.

React Redux v9 adds a TypeScript/JSDoc deprecation annotation to encourage developers to adopt the modern Hooks API:

• useSelector()
• useDispatch()

However, connect() still works and remains supported.

The warning is primarily intended to guide developers toward the recommended pattern for function components.

Example: Existing connect() Implementation

Many applications use a pattern similar to this:

import { useNavigate } from 'react-router-dom';
import { useEffect } from 'react';
import { connect } from 'react-redux';

const ForgotPassword = ({ auth }) => {
  const navigate = useNavigate();

  useEffect(() => {
    if (auth.loggedIn) {
      navigate('/dashboard');
    }
  }, [auth.loggedIn, navigate]);

  return <div>Forgot Password</div>;
};

const mapState = (state) => ({
  auth: state.auth,
});

export default connect(mapState)(ForgotPassword);

This code is completely valid and will continue to work.

The only issue is the IDE warning.

Option 1: Migrate to Hooks (Recommended)

For function components, React Redux recommends using hooks instead of connect().

Before

export default connect(mapState)(ForgotPassword);

After

import { useSelector } from 'react-redux';

const ForgotPassword = () => {
  const auth = useSelector((state) => state.auth);

  return <div>Forgot Password</div>;
};

export default ForgotPassword;

A more complete example:

import { useNavigate } from 'react-router-dom';
import { useEffect } from 'react';
import { useSelector } from 'react-redux';

const ForgotPassword = () => {
  const navigate = useNavigate();

  const auth = useSelector((state) => state.auth);

  useEffect(() => {
    if (auth.loggedIn) {
      navigate('/dashboard');
    }
  }, [auth.loggedIn, navigate]);

  return <div>Forgot Password</div>;
};

export default ForgotPassword;

Benefits

• Less boilerplate
• No mapStateToProps
• Better TypeScript support
• Officially recommended by React Redux

Option 2: Continue Using connect()

If your application already contains many connected components, there is no immediate need to refactor everything.

You can simply keep using:

import { connect } from 'react-redux';

The warning is informational and does not affect runtime behavior.

This approach is often preferred in mature enterprise applications where consistency is more important than adopting the latest syntax.

Option 3: Use legacy_connect

React Redux v9 introduces a special alias called legacy_connect.

Replace:

import { connect } from 'react-redux';

with:

import { legacy_connect as connect } from 'react-redux';

The rest of your code remains unchanged:

const mapState = (state) => ({
  auth: state.auth,
});

export default connect(mapState)(ForgotPassword);

Why Use legacy_connect?

• Removes IDE deprecation warnings
• No behavior changes
• No refactoring required
• Useful for large existing codebases

Recommended Approach for Different Scenarios

New Projects

Use hooks:

useSelector()
useDispatch()

This is the modern React Redux pattern.

Existing Applications

If your project already contains dozens or hundreds of connected components:

import { legacy_connect as connect } from 'react-redux';

can be a practical intermediate solution.

Gradual Migration Strategy

Many teams adopt the following approach:

1. Keep existing connect() components.
2. Use hooks for all new components.
3. Gradually migrate old components when they are modified.
4. Use legacy_connect to suppress warnings during the transition.

This avoids large-scale refactoring while moving toward modern React Redux patterns.

TypeScript Bonus: Typed Hooks

For Redux Toolkit applications, consider creating typed hooks.

// store.ts
export type RootState = ReturnType<typeof store.getState>;
export type AppDispatch = typeof store.dispatch;

// hooks.ts
import { useDispatch, useSelector } from 'react-redux';

export const useAppDispatch =
  useDispatch.withTypes<AppDispatch>();

export const useAppSelector =
  useSelector.withTypes<RootState>();

Usage:

const auth = useAppSelector((state) => state.auth);

This provides stronger type safety and a better developer experience.

Conclusion

The connect() warning in React Redux v9 is not an indication that the API has been removed. It is a recommendation from the React Redux team to use the Hooks API in modern React applications.

You can choose one of three paths:

• Best for new code: useSelector() and useDispatch()
• Best for existing code: continue using connect()
• Best for removing warnings without refactoring: legacy_connect

For most teams, a gradual migration strategy offers the best balance between modernizing the codebase and minimizing risk.

Introduction

After installing Ubuntu, one of the first things many users encounter is the Linux terminal. By default,Ubuntu uses Bash (Bourne Again Shell) as its command-line shell. While Bash is powerful and widely used,many developers and Linux enthusiasts prefer an alternative shell called Zsh (Z Shell).
This guide explains what Zsh is, why it is popular, how to install it on Ubuntu, and what happens during its
first-time setup. The explanations are written with beginners in mind, breaking down every command used
during the installation process.

What is a Shell?

Before understanding Zsh, it is important to understand what a shell is.

A shell is a program that allows users to interact with the operating system through commands. Whenever commands such as the following are executed:

ls
cd
mkdir

the shell interprets those commands and communicates with the operating system to perform the requested actions.

Ubuntu uses Bash (Bourne Again Shell) as its default shell.

What is Zsh?

Zsh stands for Z Shell. It is an advanced shell that provides all the features of Bash while adding many enhancements that improve the command-line experience.

Some of the most popular features of Zsh include:
• Better command auto-completion
• Easier navigation through directories
• Command suggestions and corrections
• Customizable themes
• Plugin support
• Improved productivity for developers

Because of these features, Zsh has become one of the most widely used shells in the Linux community.

Why Use Zsh?

Many users choose Zsh for the following reasons:
Better Auto-Completion
Zsh provides intelligent suggestions when typing commands, file names, and directories.
Improved Productivity
Frequently used commands can be executed more quickly with the help of plugins and shortcuts.
Customization
The terminal appearance can be customized using themes, making it more informative and visually appealing.
Learning Modern Linux Tools
Many developers use Zsh along with frameworks such as Oh My Zsh, making it a valuable tool for anyone learning Linux development environments.

Installing Zsh

Step 1: Updating Package Information
Before installing any software, Ubuntu's package information should be updated.
sudo apt update
Understanding the Command
• sudo = Super User DO. Temporarily grants administrator privileges.
• apt = Advanced Package Tool used to manage software packages.
• update = Downloads the latest package information from Ubuntu repositories.
This command does not upgrade software. It only refreshes the package database so Ubuntu knows which software versions are available.
Step 2: Installing Zsh
Install Zsh using the following command:
sudo apt install zsh -y
Understanding the Command
• sudo = Runs the command with administrator privileges.
• apt = Ubuntu package manager.
• install = Installs a software package.
• zsh = The package to be installed.
• -y = Automatically answers "Yes" to confirmation prompts.
This command downloads and installs Zsh along with any required dependencies.
Step 3: Verifying Installation
After installation, verify that Zsh has been installed correctly.
zsh --version
Understanding the Command
• zsh = Runs the Zsh executable.
• --version = Displays version information.
Example output:
zsh 5.9
Displaying a version number confirms that the installation was successful.
Step 4: Making Zsh the Default Shell
Installing Zsh does not automatically replace Bash. To make Zsh the default shell, execute:
chsh -s $(which zsh)
Understanding the Command
This command consists of multiple parts.
which zsh
• which = Finds the location of an executable program.
• zsh = The program being searched for.
Example output:
/usr/bin/zsh
This shows the location of the Zsh executable.
$(which zsh)
The $() syntax is known as command substitution.
It executes the command inside the brackets and uses its output.
Therefore:
$(which zsh)
becomes:
/usr/bin/zsh
chsh -s
• chsh = Change Shell.
• -s = Specifies which shell should be used.
Therefore:
chsh -s $(which zsh)
effectively becomes:
chsh -s /usr/bin/zsh
This tells Linux to use Zsh as the default login shell for the current user.
After running the command, log out and log back in.

First Launch of Zsh

After logging back in and opening the terminal, Zsh may display a configuration screen called zsh-newuser-install.
This happens because no Zsh configuration files currently exist in the user's home directory. Zsh therefore launches a setup wizard to create an initial configuration.
The setup wizard presents four options.
Option (q)
(q) Quit and do nothing.
• Exits the setup wizard.
• The wizard will appear again the next time Zsh starts.
Option (0)
(0) Exit, creating the file ~/.zshrc containing just a comment.
• Creates a minimal .zshrc file.
• Prevents the setup wizard from appearing again.
• Useful for users who want to configure everything manually.
Option (1)
(1) Continue to the main menu.
• Opens the advanced configuration menu.
• Allows customization of history settings, key bindings, completion settings, and other shell features.
Option (2)
(2) Populate your ~/.zshrc with the configuration recommended by the system
administrator.
• Automatically creates a recommended .zshrc file.
• Applies sensible default settings.
• Recommended for beginners.

Recommended Choice for Beginners
For users who are new to Zsh, selecting:
2
is generally the best option.
This option:
• Creates the configuration file automatically.
• Applies useful default settings.
• Allows immediate use of Zsh without manual configuration.

Understanding the .zshrc File
During the setup process, a file named:
~/.zshrc
is created.
Breaking It Down
• ~ = Home directory of the current user.
• .zshrc = Zsh Run Commands file.
• The dot ( . ) indicates that it is a hidden file.
The .zshrc file stores:
• Shell settings
• Aliases
• Plugins
• Themes
• Environment variables
• Custom terminal configurations
Every time Zsh starts, it reads this file and applies the stored settings.

Verifying the Configuration File
To verify that the configuration file was created successfully:
ls -la ~/.zshrc
Understanding the Command
• ls = Lists files and directories.
• -l = Displays detailed information.
• -a = Shows hidden files.
• ~/.zshrc = Path of the configuration file.
If the file exists, Linux displays its details.

Key Takeaways
Installing Zsh introduces several important Linux concepts:
• Linux supports multiple shells.
• Users can choose their preferred shell.
• Shell behavior is controlled through configuration files.
• Commands can be combined using command substitution.
• Terminal environments can be customized extensively.
Understanding these concepts provides a strong foundation for further Linux learning.

Conclusion
Zsh is a modern and feature-rich shell that enhances the Linux terminal experience through improved auto-completion, customization, and productivity features. Installing Zsh is a simple process, but it also serves as an excellent opportunity to learn about package management, shell configuration, and Linux command-line fundamentals.
For beginners exploring Ubuntu and Linux, Zsh provides a practical introduction to terminal customization while maintaining compatibility with familiar Bash workflows.

Definition:
Kafka, in simple terms, is a distributed-infrastructure used to store, manage and process events in real-time.

In traditional software world, developers visualized data as tables which represents things in real world like for example, items in an inventory, signed-up users, cars in a showroom, etc.
But what about things like item being dispatched from storeroom, user clicking somewhere on your website, driver picking up the client from a particular location?
You guessed it right! These are all events.
So, Kafka helps us process these events in real time, meaning the moment that particular event took place.
Hence, there is no such concept of storing these events in a file or a table for processing them in a batch in future.
However, this does not goes on to conclude that Kafka cannot remember events that already took place. Kafka is built to remember these events.

Lets understand the need for Kafka with the help of this simple example.

Consider a thermostat_readings table.

Now, suppose we need to update the thermostat reading for sensor_id 42 from 24 to 20, we will destructively change the value in temperature column for sensor id 42 from 24 to 20.
So our new table, looks like:

The critical issue here is that, we lost our previous info (context) of the sensor_id in Mumbai, like how quickly the temperature shoots up here or at what time of day it heats up.

To overcome this crucial challenge, Kafka implements logs.

Now you might be wondering what are logs?
Logs can be interpreted as an abstraction used by Kafka to store events as a sequence of data items. Mostly these data items are referred as events and quiet rarely called as messages.
The data items are appended at the very end, and items which are already present are never changed! You never modify these logs.
In Kafka, logs are known as Topics. So topics are where our messages get accumulated. And ALWAYS remember, messages in Kafka are IMMUTABLE! Once you write them into a topic, you cannot modify them. Basically, its an event which has happened and you cannot rewrite history; as same as you cannot change your past, simple as that!

So, in a gist, a topic is analogous to a table in a database, and we have numerous tables in a database; similarly we can have numerous topics in a single Kafka cluster.

NOTE: The messages in a topic can be of different format unlike a schema which needs to be followed in a database table.
The reason behind this is, that Kafka stores these messages as plain bytes. So format or schema doesn't matter.

How do you filter out messages out of a topic then?
Just like we deal with immutable data structures in various programming languages. Create a copy of that topic and filter out the unnecessary messages.

MISCONCEPTION: Topics are Logs. Not queues.
When a queue is read, the item is taken out of the queue and read. Now, nobody else can read that value. In a Kafka topic, when a message is read, it still stays intact. I can comeback after a few years and read that same message again!

More on Kafka message:
Its a value, associated with a key.
For example, consider this JSON:
{
"sensor_id": 42,
"location": "Mumbai",
"temperature": 22,
"read_at": 1700
}
Here, the 'sensor_id' becomes the key. This key is basically an identifier the payload relates to. Generally any unique id is taken as the key. Its not mandatory, but highly recommended to have a key!
We also got the timestamp, which tells us the moment the producer created that message.
The message also has some light-weight headers, and the most important parts of a Kafka message are topic, partition and offset!

Policies available in Kafka to prevent your disk from running out of space:
1. Log retention: delete old data or trim logs by size
2. Log compaction: keep only the latest value per key as sometimes context or history is irrelevant to maintain.

How Kafka scales?
If we limit our Kafka topic to a single node, then we will be restricting the topic's ability to scale to the node's disk space.
Since, Kafka is a distributed system, we partition the topic into several partitions.
Once partitions are created we need to decide to which partition the message goes to.
The message key helps us to make this decision. If the key is NULL, the messages are distributed in a round robin fashion. If not NULL and to ensure that a message with a certain key ALWAYS goes into a particular partition, hash the message key against a hash function mod the number of partitions and the output of this hash function is the partition number where the message goes to. This also helps us order our messages.

A few terminologies:

1. Cluster: A collection of one or more Kafka brokers working together to share the workload and provide redundancy (simply, a network of nodes).
2. Node: The underlying physical or virtual infrastructure that hosts a broker (simply, machine with some disk space for storage purposes).
3. Broker: A single Kafka server process that receives, stores, and fetches data (simply, a Kafka software process running on a node).

Point to note here is that, a broker has access to disk space on that node on which it's running; this disk space is basically SSD which is tightly coupled next to the processor.

Brokers are responsible for handling incoming requests to write new messages to partitions as well as read messages out of them.

Replication (for fault tolerance):

What is Replication factor?
Number of copies created for each partition.

We set the replication factor (n), which in above case is 3. The darker one is termed as Leader (lead replica) whereas the remaining (n-1) copies are called as followers.
Messages are preferred to be written into and read from the leader but in rare scenarios we might write and read from a replica which is nearest to us in the network.
Meanwhile, as messages are written into the lead replica, the followers keep scrapping out the newly written messages from the leader to keep themselves updated and have everything replicated.

Now in case the Broker 1 fails, we still have copies of Partitions 0 (with brokers 2, 3) and 2 (with brokers 3, 4).
Here, Broker 1 had the leader of partition 0. So new leader will be elected for partition 0.

PRODUCER:
A producer is nothing but a Kafka client which writes data into the Kafka partition.
CONSUMER:
A consumer is a Kafka client that reads from the Kafka topic.

In short, anything which is not a broker, is, at the end of the day a producer or a consumer.

REFERENCE:
Apache Kafka 101 - https://developer.confluent.io/courses/apache-kafka/events/

SSH stands for Secure Shell.
It is a secure protocol used to:

• Connect to remote servers
• Clone Git repositories
• Push and pull code securely
• Deploy applications

Instead of using passwords, SSH uses cryptographic key pairs.

Step 2: Understand SSH Key Pair

When you create an SSH key, two files are generated:

How it works:

1. You give your public key to GitLab.
2. GitLab stores it.
3. When you connect, GitLab verifies you using your private key.
4. If matched → Access granted.
   
   No password needed.

Step 3: Why We Use SSH in GitLab

GitLab is used for:

• Hosting repositories
• CI/CD
• Version control
• Collaboration

Without SSH (using HTTPS):

git clone https://gitlab.com/username/project.git
Every push asks for username & password.

With SSH:git clone git@gitlab.com:username/project.git
Push → Done instantly 🚀
That’s why developers prefer SSH.

Step 4: Generate SSH Key on Ubuntu

1️⃣ Open Terminal

Press:Ctrl + Alt + T

2️⃣ Check If SSH Already Exists
ls -al ~/.ssh
If folder doesn’t exist → no problem.

3️⃣ Generate New SSH Key

Recommended modern algorithm:
ssh-keygen -t ed25519 -C "your_email@example.com"
If not supported:
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
Press Enter to accept default location:/home/username/.ssh/id_ed25519
Set passphrase (optional but recommended).

4️⃣ Start SSH Agent
eval "$(ssh-agent -s)"

5️⃣ Add Key to SSH Agent
ssh-add ~/.ssh/id_ed25519

6️⃣ Copy Public Key
cat ~/.ssh/id_ed25519.pub
Copy the entire output.

Step 5: Generate SSH Key on Windows

Option 1: Using Git Bash (Recommended)

1. Install Git for Windows
2. Open Git Bash

Run:ssh-keygen -t ed25519 -C "your_email@example.com"
Keys are stored in:C:\Users\YourUsername\.ssh\

View public key:cat ~/.ssh/id_ed25519.pub

Option 2: Using PowerShell

Open PowerShell and run:

ssh-keygen -t ed25519 -C "your_email@example.com"
Same process..

Step 6: Generate SSH Key on macOS

1️⃣ Open Terminal

Cmd + Space → Terminal

2️⃣ Generate Key

ssh-keygen -t ed25519 -C "your_email@example.com"

3️⃣ Start SSH Agent

eval "$(ssh-agent -s)"

4️⃣ Add Key

ssh-add ~/.ssh/id_ed25519

5️⃣ Copy Public Key

pbcopy < ~/.ssh/id_ed25519.pub

Step 7: Add SSH Key to GitLab

1. Login to GitLab
2. Click Profile → Preferences
3. Click SSH Keys
4. Paste copied public key
5. Click Add Key

Now GitLab trusts your machine.

Step 8: Test SSH Connection

Run: ssh -T git@gitlab.com
If successful, you’ll see:Welcome to GitLab!

Step 9: Clone Using SSH

Instead of HTTPS:
git clone git@gitlab.com:username/project.git
Now: git push
No password required.

Step 10: Security Best Practices

✔ Use ed25519
✔ Protect private key
✔ Add passphrase
✔ Never share private key
✔ Set correct permissions (Linux/macOS):

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519

Bonus: How SSH Works Internally

1. Client connects to GitLab
2. GitLab checks public key
3. GitLab sends encrypted challenge
4. Your private key decrypts it
5. Verified → Access granted

This uses asymmetric cryptography — extremely secure.

Final Conclusion

Setting up SSH keys:

• Improves security
• Removes password dependency
• Enables automation
• Essential for DevOps
• Industry best practice

If you are serious about professional development, SSH is not optional — it’s foundational