September 21, 2026 · 10 min read

Working with large PDF documents can quickly become frustrating. Whether it is a technical handbook, a company specification, a legal document, or a 300-page report, finding one specific piece of information often means scrolling, searching, and trying to understand the context around the result.

What if you could simply ask the document a question?

"What are the rules regarding player registration?"

or:

"What does the document say about match postponements?"

And get an answer based only on the content of your PDF?

In this tutorial, we are going to build exactly that.

We will create a local PDF question-answering bot using:

• Mistral 7B running locally
• LangChain to connect the different components
• Hugging Face embeddings to transform text into vectors
• Chroma as our local vector database
• Streamlit to build the user interface
• PyPDF to extract the content of our PDF

The interesting part is that the entire application can run locally.

No external LLM API is required.

Let's build it.

What Are We Building?​

The final application will allow us to load a PDF document and ask questions about its content.

The architecture looks like this:

                  ┌─────────────────┐
                  │      PDF        │
                  │   Document      │
                  └────────┬────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │   PyPDFLoader   │
                  │ Extract text    │
                  └────────┬────────┘
                           │
                           ▼
              ┌─────────────────────────┐
              │ Recursive Text Splitter │
              │                         │
              │ PDF → smaller chunks    │
              └────────────┬────────────┘
                           │
                           ▼
              ┌─────────────────────────┐
              │ Hugging Face Embeddings │
              │                         │
              │ Text → vectors          │
              └────────────┬────────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │     Chroma      │
                  │ Vector Database │
                  └────────┬────────┘
                           │
                    User question
                           │
                           ▼
                  ┌─────────────────┐
                  │ Similarity      │
                  │ Search          │
                  └────────┬────────┘
                           │
                    Relevant chunks
                           │
                           ▼
                  ┌─────────────────┐
                  │ Mistral 7B      │
                  │ Local LLM       │
                  └────────┬────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │    Streamlit    │
                  │     Answer      │
                  └─────────────────┘

This is a classic Retrieval-Augmented Generation (RAG) architecture.

Instead of asking the LLM to know everything about the PDF, we first retrieve the relevant pieces of the document and then give those pieces to Mistral as context.

Why Use RAG for a PDF?​

A large language model by itself is not a PDF search engine.

Suppose our PDF contains 200 pages.

Sending the entire document to the model for every question would be inefficient and, depending on the model's context window, may not even be possible.

RAG solves this problem by splitting the document into smaller pieces.

When the user asks a question, the application:

1. Converts the question into a vector.
2. Searches the vector database for similar pieces of text.
3. Retrieves the most relevant chunks.
4. Adds those chunks to the prompt.
5. Sends the prompt to Mistral.
6. Displays the generated answer.

The model therefore receives something like:

Context:
----------------
Relevant paragraph from page 42...

Relevant paragraph from page 87...

Relevant paragraph from page 91...
----------------

Question:
What are the requirements for player registration?

Answer:

The LLM doesn't need to search the entire document itself.

The vector database has already done the retrieval work.

The Technology Stack​

Our application is intentionally simple.

Mistral​

Mistral is our local language model.

We will use a quantized GGUF version of Mistral 7B and load it with LlamaCpp.

This means the model runs directly on our machine instead of calling a hosted LLM API.

LangChain​

LangChain provides the glue between our different components.

It handles things such as:

• PDF loading
• document splitting
• embeddings
• vector retrieval
• LLM integration

Hugging Face Embeddings​

Before we can search our document semantically, we need to transform the text into numerical vectors.

We will use:

sentence-transformers/all-mpnet-base-v2

Each chunk of our PDF becomes an embedding.

Questions can then be compared against those embeddings to find semantically similar text.

Chroma​

Chroma is our vector database.

Instead of searching the PDF with traditional keyword matching, we search the numerical representations of the document.

This allows questions such as:

"What happens when a game is postponed?"

to potentially retrieve a passage containing different wording such as:

"Postponed fixtures shall be rescheduled..."

Streamlit​

Finally, Streamlit gives us a simple web interface.

We don't need to build a React frontend or a REST API.

A few Python statements are enough to create the application.

Step 1: Create the Project

Let's start with a simple project structure:

pdf-bot/
│
├── .venv/
│
├── data/
│   └── premier-league-handbook-2026-27.pdf
│
├── chroma_db/
│
├── mistral-7b-instruct-v0.2.Q4_K_M.gguf
│
└── app.py

The data directory contains the PDF.

The GGUF file is our local Mistral model.

The chroma_db directory will contain the persistent Chroma database.

And app.py will contain our Streamlit application.

Step 2: Create the Python Environment

On macOS, we can create a virtual environment with:

python3 -m venv .venv

Activate it:

source .venv/bin/activate

Once activated, your terminal should show something similar to:

(.venv) $

Now install the required dependencies:

pip install streamlit
pip install langchain
pip install langchain-community
pip install langchain-text-splitters
pip install langchain-huggingface
pip install langchain-chroma
pip install chromadb
pip install pypdf
pip install sentence-transformers
pip install llama-cpp-python

At this point, the Python environment contains everything we need to build the application.

Step 3: Get a Local Mistral Model

Instead of calling an API, we are going to run Mistral locally.

For this example, we use a GGUF model:

mistral-7b-instruct-v0.2.Q4_K_M.gguf

Place the model at the root of the project:

pdf-bot/
├── mistral-7b-instruct-v0.2.Q4_K_M.gguf
├── app.py
└── data/

The important thing here is that LlamaCpp needs the path to the actual GGUF model file.

We configure that path in Python:

MODEL_PATH = "./mistral-7b-instruct-v0.2.Q4_K_M.gguf"

Step 4: Load the PDF

LangChain provides PyPDFLoader to extract text from PDF documents.

The basic operation is:

from langchain_community.document_loaders import PyPDFLoader

loader = PyPDFLoader(PDF_PATH)
pages = loader.load()

The PDF is converted into a collection of LangChain documents.

Each page contains both the extracted text and metadata.

For example, the metadata can contain the page number.

This becomes useful later when we want to show the user where an answer came from.

Step 5: Split the PDF Into Chunks

We don't want to store entire pages as single documents.

Instead, we divide the content into smaller chunks.

from langchain_text_splitters import RecursiveCharacterTextSplitter

text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=1000,
    chunk_overlap=200,
)

documents = text_splitter.split_documents(pages)

Here we use a chunk size of approximately 1,000 characters.

We also use an overlap of 200 characters.

Why?

Imagine that an important sentence starts near the end of one chunk.

Without overlap, the next chunk could lose some of the surrounding context.

With overlap:

Chunk 1
████████████████████████████
                    ████████

                    ████████
Chunk 2
                    ███████████████████████

The overlapping area gives the retrieval system a better chance of preserving context.

The exact values are not universal.

For a different document, you may want to experiment with:

chunk_size=500
chunk_overlap=100

or:

chunk_size=1500
chunk_overlap=300

The best values depend on the structure and density of your documents.

Step 6: Convert Text Into Embeddings

Now we need to transform each text chunk into a vector.

We can use Hugging Face embeddings:

from langchain_huggingface import HuggingFaceEmbeddings

embeddings = HuggingFaceEmbeddings(
    model_name="sentence-transformers/all-mpnet-base-v2"
)

Conceptually, the process looks like this:

"Players must be registered before..."
                    │
                    ▼
             Embedding model
                    │
                    ▼
     [0.013, -0.281, 0.721, ...]

The important idea is that semantically similar pieces of text tend to have vectors that are close to one another in vector space.

This is what allows us to perform semantic search.

Step 7: Store the Embeddings in Chroma

Now we can create our vector database.

from langchain_chroma import Chroma

db = Chroma.from_documents(
    documents=documents,
    embedding=embeddings,
    persist_directory=CHROMA_PATH,
    collection_name="pdf_documents",
)

Our document pipeline now looks like:

PDF
 │
 ▼
Extract text
 │
 ▼
Split into chunks
 │
 ▼
Generate embeddings
 │
 ▼
Store vectors
 │
 ▼
Chroma

The database is persisted locally in:

./chroma_db

This is useful because we don't want to lose our vector database every time the application stops.

Step 8: Retrieve Relevant Information

Now comes the most important part of the RAG pipeline.

When the user asks:

What are the requirements for player registration?

we don't immediately send that question to Mistral.

First, we search Chroma.

retriever = db.as_retriever(
    search_kwargs={"k": 4}
)

source_documents = retriever.invoke(question)

The:

k=4

means that we ask the retriever for the four most relevant chunks.

We can then combine those chunks:

context = "\n\n".join(
    doc.page_content
    for doc in source_documents
)

Our question has now been transformed into a small, focused context extracted from the PDF.

Step 9: Build the Prompt

We now need to give Mistral both the retrieved context and the original question.

Our prompt is intentionally restrictive:

def build_prompt(context, question):
    return f"""
You are a helpful assistant answering questions about a PDF document.

Use ONLY the information contained in the provided context.

If the answer cannot be found in the context, say:
"I couldn't find the answer in the PDF."

Do not make up information.

Context:
----------------
{context}
----------------

Question:
{question}

Answer:
"""

This is an important part of the application.

We don't want Mistral to answer from its general knowledge.

We want it to behave as a question-answering interface for our document.

The instruction:

Use ONLY the information contained in the provided context.

helps constrain the model.

And:

Do not make up information.

makes our intention explicit.

It is still important to remember that prompt instructions are not a mathematical guarantee that an LLM will never hallucinate. Retrieval quality and model behavior both matter.

Step 10: Load Mistral Locally

Now we can load the GGUF model using LlamaCpp.

from langchain_community.llms import LlamaCpp

llm = LlamaCpp(
    model_path=MODEL_PATH,
    n_ctx=4096,
    max_tokens=512,
    temperature=0.1,
    verbose=False,
)

There are several parameters worth understanding.

model_path​

This tells LlamaCpp where the GGUF model is located.

model_path=MODEL_PATH

n_ctx​

This controls the model context window used by the application.

n_ctx=4096

Our prompt contains both the retrieved context and the question, so the context window needs to be large enough to accommodate them.

max_tokens​

This controls the maximum amount of generated output.

max_tokens=512

For a document Q&A application, a few hundred tokens are often sufficient for a concise answer.

temperature​

We use a low temperature:

temperature=0.1

For factual document Q&A, we generally want predictable answers rather than highly creative responses.

Step 11: Connect Everything Together

At this point, our RAG pipeline looks like this:

                         USER
                          │
                          ▼
                    Ask a question
                          │
                          ▼
                ┌──────────────────┐
                │ Embedding/Search │
                └────────┬─────────┘
                         │
                         ▼
                    Chroma DB
                         │
                         ▼
                  Top 4 PDF chunks
                         │
                         ▼
                    Build prompt
                         │
                         ▼
                   Local Mistral
                         │
                         ▼
                      Answer

This separation between retrieval and generation is what makes the application useful.

Chroma is responsible for finding information.

Mistral is responsible for generating the response.

Step 12: Build the Streamlit Interface

Now let's add a user interface.

First:

import streamlit as st

Then configure the page:

st.set_page_config(
    page_title="Mistral PDF Q&A",
    page_icon="📄",
    layout="wide",
)

And create the title:

st.title("📄 Mistral PDF Q&A")

For the question itself, we can use:

question = st.text_input(
    "Ask a question about the PDF:",
    placeholder="What is this document about?",
)

When the user enters a question, we execute the RAG pipeline.

Step 13: Put the Application Together

Here is the complete Streamlit application:

import os
import streamlit as st

from langchain_community.document_loaders import PyPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_chroma import Chroma
from langchain_community.llms import LlamaCpp


# --------------------------------------------------
# Streamlit UI
# --------------------------------------------------

st.set_page_config(
    page_title="Mistral PDF Q&A",
    page_icon="📄",
    layout="wide",
)

st.title("📄 Mistral PDF Q&A")


# --------------------------------------------------
# Configuration
# --------------------------------------------------

PDF_PATH = "./data/premier-league-handbook-2026-27.pdf"
MODEL_PATH = "./mistral-7b-instruct-v0.2.Q4_K_M.gguf"
CHROMA_PATH = "./chroma_db"


# --------------------------------------------------
# Load Mistral GGUF model
# --------------------------------------------------

@st.cache_resource
def load_llm():

    if not os.path.exists(MODEL_PATH):
        raise FileNotFoundError(
            f"Mistral model not found: {MODEL_PATH}"
        )

    llm = LlamaCpp(
        model_path=MODEL_PATH,
        n_ctx=4096,
        max_tokens=512,
        temperature=0.1,
        verbose=False,
    )

    return llm


# --------------------------------------------------
# Load embedding model
# --------------------------------------------------

@st.cache_resource
def load_embeddings():

    return HuggingFaceEmbeddings(
        model_name="sentence-transformers/all-mpnet-base-v2"
    )


# --------------------------------------------------
# Create / load Chroma vector database
# --------------------------------------------------

@st.cache_resource
def process_pdf(pdf_path):

    loader = PyPDFLoader(pdf_path)
    pages = loader.load()

    text_splitter = RecursiveCharacterTextSplitter(
        chunk_size=1000,
        chunk_overlap=200,
    )

    documents = text_splitter.split_documents(pages)

    embeddings = load_embeddings()

    db = Chroma.from_documents(
        documents=documents,
        embedding=embeddings,
        persist_directory=CHROMA_PATH,
        collection_name="pdf_documents",
    )

    return db


# --------------------------------------------------
# Build prompt
# --------------------------------------------------

def build_prompt(context, question):

    return f"""
You are a helpful assistant answering questions about a PDF document.

Use ONLY the information contained in the provided context.

If the answer cannot be found in the context, say:
"I couldn't find the answer in the PDF."

Do not make up information.

Context:
----------------
{context}
----------------

Question:
{question}

Answer:
"""


# --------------------------------------------------
# Check PDF
# --------------------------------------------------

if not os.path.exists(PDF_PATH):

    st.error(
        f"PDF not found at `{PDF_PATH}`. "
        "Please put your PDF inside the `data/` folder."
    )

    st.stop()


# --------------------------------------------------
# Load vector database
# --------------------------------------------------

with st.spinner("Loading PDF and building vector database..."):

    try:
        db = process_pdf(PDF_PATH)

    except Exception as e:

        st.error(
            f"Error processing PDF: {e}"
        )

        st.stop()


st.success("PDF loaded successfully!")


# --------------------------------------------------
# Load LLM
# --------------------------------------------------

with st.spinner("Loading Mistral model..."):

    try:
        llm = load_llm()

    except Exception as e:

        st.error(
            f"Error loading Mistral model: {e}"
        )

        st.stop()


# --------------------------------------------------
# Question input
# --------------------------------------------------

question = st.text_input(
    "Ask a question about the PDF:",
    placeholder="What is this document about?",
)


# --------------------------------------------------
# RAG pipeline
# --------------------------------------------------

if question:

    with st.spinner("Searching the PDF..."):

        retriever = db.as_retriever(
            search_kwargs={"k": 4}
        )

        source_documents = retriever.invoke(
            question
        )

    if not source_documents:

        st.warning(
            "No relevant information was found in the PDF."
        )

        st.stop()

    context = "\n\n".join(
        doc.page_content
        for doc in source_documents
    )

    prompt = build_prompt(
        context=context,
        question=question,
    )

    with st.spinner("Mistral is thinking..."):

        try:

            answer = llm.invoke(prompt)

        except Exception as e:

            st.error(
                f"Error generating answer: {e}"
            )

            st.stop()

    st.markdown("### Answer")

    st.write(answer)

    st.markdown("### Sources")

    for i, doc in enumerate(
        source_documents,
        start=1
    ):

        page_number = doc.metadata.get(
            "page",
            "unknown"
        )

        display_page = (
            page_number + 1
            if isinstance(page_number, int)
            else page_number
        )

        with st.expander(
            f"Source {i} — Page {display_page}"
        ):

            st.write(
                doc.page_content
            )

Step 14: Run the Application

On macOS, activate the virtual environment:

source .venv/bin/activate

Then start Streamlit:

streamlit run app.py

Streamlit will start a local development server.

You can then open:

http://localhost:8501

The application should display:

📄 Mistral PDF Q&A

PDF loaded successfully!

Ask a question about the PDF:
[_______________________________]

### Answer

...

### Sources

Source 1 — Page 42
Source 2 — Page 87
Source 3 — Page 91
Source 4 — Page 103

And that's it.

We have a local document chatbot.

What Actually Happens When We Ask a Question?

Let's walk through a real request.

Suppose we ask:

What happens if a fixture is postponed?

The first step is retrieval.

Chroma searches the document for chunks that are semantically related to the question.

It might return four pieces of text:

Page 42
"Postponed fixtures shall be rearranged..."

Page 43
"Clubs must agree on an alternative date..."

Page 44
"The competition authority may determine..."

Page 78
"Fixtures affected by exceptional circumstances..."

These pieces are then combined into our context.

Mistral receives the prompt and generates an answer based on that retrieved information.

Finally, Streamlit displays both the answer and the source passages.

This last part is particularly useful.

The user doesn't have to blindly trust the generated answer.

They can open the sources and inspect the original text.

Why Show the Sources?

One of the most useful features of this small application is the source display.

We already have access to metadata from the PDF:

page_number = doc.metadata.get(
    "page",
    "unknown"
)

We can therefore show:

Source 1 — Page 42

and expose the actual retrieved text:

with st.expander(
    f"Source {i} — Page {display_page}"
):
    st.write(doc.page_content)

This creates a much more transparent experience.

Instead of:

Question → AI → Answer

we have:

Question
   ↓
Retrieved evidence
   ↓
AI-generated answer
   ↓
Original sources

That distinction becomes increasingly important when building AI applications around business or technical documents.

Keeping Everything Local

One of the interesting aspects of this architecture is that the main components can run locally.

The flow is:

                 Your Computer
┌──────────────────────────────────────────────┐
│                                              │
│   PDF                                        │
│    │                                         │
│    ▼                                         │
│   Embeddings ───────► Chroma                 │
│                         │                    │
│                         ▼                    │
│                     Retrieval                │
│                         │                    │
│                         ▼                    │
│                    Mistral 7B                │
│                         │                    │
│                         ▼                    │
│                    Streamlit                 │
│                                              │
└──────────────────────────────────────────────┘

There is no need to send the document to an external LLM API for this architecture.

This can be particularly attractive for documents that you don't want to upload to a third-party service.

Of course, "local" does not automatically mean "secure". Your machine, dependencies, model files, logs, and application still need to be managed appropriately.

A Few Things to Watch Out For

Our application is intentionally simple, but there are several areas worth improving.

1. Rebuilding the Vector Database​

The current implementation calls:

Chroma.from_documents(...)

when process_pdf() runs.

For a prototype this is perfectly fine.

For a larger application, however, you don't want to recreate all embeddings every time Streamlit starts.

A production-oriented implementation would:

1. Calculate whether the document has changed.
2. Check whether an existing Chroma collection exists.
3. Reuse the existing embeddings.
4. Only process new documents when necessary.

That can make startup considerably faster.

2. Chunk Size Matters​

There is no perfect value for:

chunk_size=1000

A technical document may benefit from larger chunks.

A legal document might have meaningful sections that should be preserved.

A document containing tables can require a completely different strategy.

The quality of retrieval is strongly influenced by how we divide the document.

3. PDFs Are Not Always Simple Text​

PDFs can contain:

• tables
• images
• scanned pages
• multiple columns
• headers and footers
• unusual layouts

A normal text extractor may not always preserve the original structure correctly.

For scanned PDFs, OCR may be necessary before embeddings can be generated.

4. Retrieval Quality Matters​

The LLM is only as good as the information we retrieve.

If Chroma returns the wrong chunks, Mistral doesn't have the information required to answer the question correctly.

This is one of the most important lessons when building RAG systems:

Improving retrieval can be just as important as changing the LLM.

Increasing k is one possible experiment:

search_kwargs={"k": 6}

But more context is not automatically better.

Too many irrelevant chunks can make the prompt noisy.

Where Could We Take This Next?

The basic chatbot is only the beginning.

Once the architecture is working, there are several interesting improvements we can add.

Multiple PDFs​

Instead of:

One PDF
   ↓
One Chroma collection

we could support:

PDF 1 ─┐
PDF 2 ─┤
PDF 3 ─┼──► Chroma
PDF 4 ─┘

The user could then ask questions across an entire document library.

PDF Uploads​

Instead of hard-coding:

PDF_PATH = "./data/premier-league-handbook-2026-27.pdf"

Streamlit can provide a file uploader:

uploaded_file = st.file_uploader(
    "Upload a PDF",
    type="pdf"
)

This would turn our application from a single-document demo into a reusable PDF assistant.

Conversation History​

Currently every question is independent.

We could introduce conversation memory so that users can ask:

What does the document say about player registration?

followed by:

What about the deadline?

The application could use the previous question and answer to understand what "the deadline" refers to.

Better Source Citations​

Instead of displaying raw chunks, we could format the sources more elegantly:

Answer

Players must be registered before the applicable deadline...

Sources

📄 Page 42
📄 Page 43
📄 Page 44

We could also add a button to open the PDF at the relevant page.

Streaming Mistral Responses​

Rather than waiting for the entire answer to be generated, the UI could display tokens progressively.

This would make the application feel much more responsive, especially when running a local model on CPU.

A Better Retrieval Strategy​

A more advanced implementation could introduce:

• metadata filtering
• hybrid search
• reranking
• parent/child document retrieval
• query rewriting
• multiple embedding models
• retrieval evaluation

At that point, we are moving from a simple RAG prototype toward a more serious document intelligence platform.

The Architecture in One Picture

The entire application can be reduced to five major components:

┌──────────────┐
│     PDF      │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  Chunking    │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  Embeddings  │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│    Chroma    │
│ Vector Store │
└──────┬───────┘
       │
       │ relevant chunks
       ▼
┌──────────────┐
│   Mistral    │
│  Local LLM   │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  Streamlit   │
│      UI      │
└──────────────┘

Each component has a clear responsibility.

PyPDF extracts the document.

The text splitter creates manageable chunks.

The embedding model converts those chunks into vectors.

Chroma finds the relevant information.

Mistral turns that information into a natural-language answer.

Streamlit makes the whole thing accessible through a browser.

Final Thoughts

Building a PDF chatbot doesn't necessarily require a large cloud architecture or an external AI API.

With a local Mistral model, a vector database, and a lightweight Streamlit interface, we can build a surprisingly capable document assistant with just Python.

The important concept is not the chatbot interface itself.

It is the pipeline behind it:

Document
   ↓
Chunk
   ↓
Embed
   ↓
Retrieve
   ↓
Generate

Once this pattern becomes familiar, it can be applied to much more than PDFs.

The same architecture can power assistants for:

• technical documentation
• internal company knowledge
• product manuals
• research papers
• compliance documents
• meeting notes
• contracts
• knowledge bases

And because the model and vector database can run locally, it provides an interesting foundation for experimenting with private, self-hosted AI applications.

The next step is no longer simply asking an LLM questions.

It is giving an LLM the right information at the right time.

That's where RAG becomes particularly powerful.

Project Structure​

For reference, the final project looks like this:

pdf-bot/
│
├── .venv/
│
├── data/
│   └── premier-league-handbook-2026-27.pdf
│
├── chroma_db/
│
├── mistral-7b-instruct-v0.2.Q4_K_M.gguf
│
└── app.py

Start the application with:

source .venv/bin/activate
streamlit run app.py

Then open:

http://localhost:8501

And start talking to your PDF.

Tags:

AI · Mistral · RAG · LLM · Python · Streamlit · Chroma · Vector Database · LangChain · Machine Learning

In today’s fast-evolving software landscape, staying updated with the latest tools, frameworks, and practices is both a challenge and an opportunity. One powerful way to stay on top is by using a Technology Radar — a curated, visual map that helps teams make smart technology decisions.

If you want to build software that lasts, you need a compass to guide you. Let’s explore what a technology radar is, why it matters, and how adopting one can transform your team’s approach to technology.

What Is a Technology Radar, Anyway?​

Imagine a radar screen showing all the tech options — from emerging tools on the edge to proven stalwarts in the center. It visualizes:

• Tech you should adopt now
• Tech you should evaluate or trial
• Tech to keep an eye on
• Tech to avoid

By plotting tools, frameworks, and practices into these rings, a radar clarifies which are ready for production, and which are hype or dead ends.

This transparency empowers teams to align around shared technology decisions — avoiding fragmentation or chasing every shiny new thing.

A Living, Breathing Technology Radar​

A technology radar is not a static list but a living document, regularly updated by tech leads and experts. It categorizes technologies across different domains:

• Programming Languages
• Frameworks & Libraries
• DevOps Tools
• Cloud Platforms
• Testing & QA Tools
• And more

Each tech is assigned to one of four rings:

• Adopt: Mature, proven, recommended for immediate use.
• Trial: Promising tech worth evaluating in projects.
• Assess: Worth watching but not yet ready.
• Hold: Technologies that have issues or are becoming obsolete.

This methodical approach brings clarity to choices, reduces risk, and encourages innovation responsibly.

Why Your Team Needs a Technology Radar​

1. Encourages Strategic Technology Adoption
   With so many options, it’s tempting to jump on the latest trends. A radar prevents impulse decisions by grounding tech adoption in research and experience.

2. Facilitates Communication and Alignment
   Developers, architects, and management get a shared language and framework for discussing tech. This helps break down silos and build consensus.

3. Improves Onboarding and Knowledge Sharing
   New team members quickly grasp what’s recommended, what’s experimental, and what’s off-limits — reducing onboarding friction.

4. Supports Continuous Improvement
   By reviewing the radar regularly, teams keep learning and adapting, staying relevant without chaos.

How To Build Your Own Technology Radar​

Here’s a simple approach:

• Form a cross-functional team: Include engineers, architects, QA, and product owners.
• Define radar categories: Pick domains relevant to your stack and projects.
• Collect tech candidates: Gather inputs from projects, hackathons, experiments, and community buzz.
• Evaluate and classify: Use criteria like maturity, adoption, risk, and business value.
• Publish and update regularly: Keep it visible and alive — review every 3-6 months.

Putting Your Technology Radar Online: Step-by-Step Tutorial​

Building your technology radar is just the first step. Sharing it effectively across your organization is key to its success.

One efficient way to do this is by using an open-source Technology Radar website project that visualizes your radar interactively and attractively.

Here’s a detailed guide on how to deploy your own radar website using this project.

Step 1: Clone the Radar Website Repository​

Start by cloning the project repository to your local machine:

git clone https://github.com/AOEpeople/aoe_technology_radar.git
cd aoe_technology_radar

Step 2: Prepare Your Radar Data​

Inside the repository, you’ll find a directory for data (commonly src/data or similar) with files in YAML or JSON format describing your radar contents.

Example structure:​

rings:
  - name: Adopt
  - name: Trial
  - name: Assess
  - name: Hold

quadrants:
  - name: Languages & Frameworks
  - name: Tools
  - name: Platforms
  - name: Techniques

items:
  - name: React
    ring: Adopt
    quadrant: Languages & Frameworks
    description: A popular JavaScript library for building user interfaces.

  - name: GraphQL
    ring: Trial
    quadrant: Tools
    description: A query language for APIs.

Step 3: Install Dependencies and Run Locally​

The radar site typically uses Node.js and React. Install dependencies with:

npm install

Then start a local development server:

npm run start

Open your browser at http://localhost:3000 (or specified port) to preview your radar live as you make changes.

Step 4: Customize the Radar Website​

You can modify:

• Colors and styling: Update CSS or theme files to match your brand.
• Content: Add more metadata or links to technology items.
• Layout: Adjust quadrant names, rings, or add new features.

The project is designed to be easily extensible and customizable — check the README and source code for further options.

Step 5: Build and Deploy​

When you’re happy with your radar, build the static files:

npm run build

This generates production-ready HTML, CSS, and JS files in the build folder.

You can deploy these files to any static web host, such as:

• GitHub Pages
• Netlify
• Vercel
• Your company’s internal web server

For example, to deploy on GitHub Pages:​

1. Create a GitHub repository for your radar site.
2. Push your built files to the repository’s gh-pages branch (or configure as needed).
3. Enable GitHub Pages in your repo settings.

Real-World Benefits of a Technology Radar Website​

Publishing your radar online:

• Makes tech decisions transparent and accessible
• Encourages team engagement and contributions
• Provides a central reference point for all stakeholders
• Supports continuous updates without complicated distribution

Teams using a tech radar website report faster decision cycles, better alignment, and more confident adoption of new technologies.

Final Thoughts​

In an ever-shifting technology landscape, a Technology Radar acts as a vital compass for your software journey. By thoughtfully building, maintaining, and sharing your radar through a user-friendly website, you create a culture of strategic tech choices and continuous improvement.

If you want to stay ahead of the curve, start your own technology radar today — and empower your team with clarity and confidence.

• TechRadar By AOE
• Static site generator for AOE Technology Radar

Photo by Markus Spiske

What is a RESTful API?​

RESTful APIs are a cornerstone of modern web development, allowing systems to communicate over HTTP using principles of Representational State Transfer (REST). RESTful APIs are designed to be scalable, stateless, and follow the HTTP protocol standards, making them highly effective for a wide range of applications.

In this blog, we'll explore the levels of RESTful APIs as defined by the Richardson Maturity Model, a framework that describes the stages of RESTful API maturity.

The Richardson Maturity Model​

The Richardson Maturity Model breaks down RESTful APIs into four distinct levels, each building upon the previous one. These levels highlight the increasing adherence to REST principles.

Level 0: The Swamp of POX​

At this level, APIs act as simple endpoints that accept requests and return responses. These APIs are typically not RESTful—they often use HTTP as a transport protocol rather than leveraging its full capabilities.

Characteristics:​

• No standard structure for requests or responses.
• Often uses XML or JSON but lacks meaningful use of HTTP methods.
• Example:

POST /api/resource HTTP/1.1
Host: example.com
Content-Type: text/xml

<data>
<value>Example</value>
</data>

This is more like an RPC (Remote Procedure Call) using HTTP as a vehicle.

Level 1: Resources​

At Level 1, APIs start organizing data into distinct resources. Each resource is identified by a unique URI (Uniform Resource Identifier).

Characteristics:​

• Resource-based design.
• Unique URIs for different entities.
• Still lacks proper use of HTTP methods.

Example:​

GET /api/users/12345 HTTP/1.1
Host: example.com

In this example, the URI /api/users/12345 identifies a specific user resource.

Level 2: HTTP Verbs​

At Level 2, APIs begin using HTTP methods like GET, POST, PUT, and DELETE to indicate the desired operation on resources.

Characteristics:​

• Full utilization of HTTP methods.
• Improved clarity of intent.
• Status codes convey the results of operations (e.g., 200 OK, 404 Not Found).

Example:​

POST /api/users HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "name": "Jane Doe",
  "email": "jane.doe@example.com"
}

This example demonstrates creating a new user resource using a POST request.

Level 3: Hypermedia Controls (HATEOAS)​

At the highest level, APIs provide Hypermedia as the Engine of Application State (HATEOAS). This means responses include links to related actions or resources, allowing clients to navigate the API dynamically.

Characteristics:​

• Responses include hypermedia links.
• Self-documenting API through navigable relationships.
• Closest adherence to REST principles.

Example:​

{
  "id": 12345,
  "name": "Jane Doe",
  "links": [
    { "rel": "self", "href": "/api/users/12345" },
    { "rel": "update", "href": "/api/users/12345" },
    { "rel": "delete", "href": "/api/users/12345" }
  ]
}

This response includes links that guide clients to other actions, such as updating or deleting the user resource.

Build a product query api using Spring Data​

Let's condiser the following business requirement we want to address:

Currently, local grocery stores must either visit large distribution companies or contact them individually to inquire about pricing, stock availability, and delivery schedules when placing orders. This process is time-consuming and inefficient for grocery managers. To address this challenge, we propose developing a platform that enables managers to easily check prices, view stock levels, place orders, and track deliveries in one streamlined solution.

We aim to develop a RESTful API to provide access to product data, enabling consumers like microservices, mobile apps, and web applications to retrieve and display the information. This will allow end users, such as grocery store managers, to view, read, and stay informed about the available products on our platform.

What is Spring Data​

Spring Data is a part of the broader Spring Framework ecosystem that simplifies data access in Java applications. It provides a set of powerful tools and abstractions that make it easier to interact with various data sources, such as relational databases, NoSQL databases, and more. Spring Data eliminates a lot of the boilerplate code typically involved in working with databases, enabling developers to focus on the business logic rather than the intricacies of data access.

In our case we will use PostgresSQL database, so let's first create a docker container for postgres and create also our database "grocery-marketplace":

docker run -d \
  --name postgres-db \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=grocery-marketplace \
  -p 5432:5432 \
  postgres:latest

The Grocery Marketplace Product Query API Project​

Our project is a maven with the following main dependencies:

Here is the informative list of the dependencies from the provided XML:

• spring-boot-starter-data-jpa (Spring Boot, JPA support)
• spring-boot-starter-data-rest (Spring Boot, Data REST support)
• flyway-core (Flyway, Database migrations)
• flyway-database-postgresql (Flyway, PostgreSQL database support)
• kotlin-reflect (Kotlin, Reflection support)
• kotlin-stdlib (Kotlin, Standard library)
• postgresql (PostgreSQL JDBC driver, runtime scope)

An operational application that covers our use case is shared through Github at the end of this post.

Database Schema​

There are several strategies you can use to create and manage tables in a PostgreSQL database, with Flyway being one of the most popular tools for handling database migrations in a structured way. Let's see how to intstruments Flyway to create our tables and inserts sample data.

Flyway is a versioned migration tool that allows you to manage your database schema in a controlled and repeatable way. It works by applying SQL-based migration scripts to your database.

1. Create SQL Migration Scripts

Flyway applies migrations sequentially based on versioned SQL scripts. These scripts should follow a naming convention like V1__Initial_schema.sql, V1__create_product_table.sql, etc.

Below a snippet of our V1__create_product_table.sql

-- Create tables for all related entities
CREATE TABLE category (
    id INT PRIMARY KEY,
    name VARCHAR(100) NOT NULL
);

-- Sample Data Insertion for related tables

-- Insert categories
INSERT INTO category (id, name) VALUES (1, 'Electronics');
INSERT INTO category (id, name) VALUES (2, 'Furniture');
INSERT INTO category (id, name) VALUES (3, 'Clothing');

2. Flyway Configuration

You can configure Flyway in your application.yml (for Spring Boot) to point to your PostgreSQL database.

  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: true
    clean-disabled: falsek

JPA Entities​

In JPA (Java Persistence API), an entity is a lightweight, persistent domain object that is mapped to a table in a relational database. It represents a record in the database and can be used to interact with that record through the application.

Below we define our first JPA Entity Category, which defines the category of product such as Electronics, Clothing, etc ...

@Entity
data class Category(
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE)
    val id: Int? = null,
    val name: String
)

Repositories​

a Spring Data Repository is an interface that allows you to interact with a data store (e.g., a relational database like MySQL, or a NoSQL database like MongoDB) without needing to write the implementation of the basic CRUD (Create, Read, Update, Delete) operations yourself. In our case we will use the Spring Data JPA Repository which is a specific type of repository provided by the Spring Data project that simplifies the implementation of the Data Access Layer (DAL) for JPA-based (Java Persistence API) applications. Below a snippet of our CategoryRepository:

@Repository
interface CategoryRepository : JpaRepository<Category, Int>

As we may notice all we need to do is to implement an the generic interface JpaRepository that takes as first type an entity and a second type the identifier of the entity.

Configurations​

By default, Spring Data REST provides basic CRUD operations for the entities it exposes, including: GET, POST, PUT, and DELETE. In order to restrict operations to readonly one by implementing the following Spring interface:

@Configuration
class SpringDataRestConfiguration : RepositoryRestConfigurer {
  companion object {
        const val BASE_PATH = "/grocery/marketplace/query/api/v1"
    }
  override fun configureRepositoryRestConfiguration(
        config: RepositoryRestConfiguration,
        cors: CorsRegistry,
    ) {
        val exposureConfiguration = config.setBasePath(BASE_PATH).exposureConfiguration
        exposureConfiguration.withItemExposure { metadata: ResourceMetadata?, httpMethods: ConfigurableHttpMethods ->
            httpMethods.disable(HttpMethod.PUT)
                .disable(HttpMethod.PATCH).disable(HttpMethod.POST).disable(HttpMethod.DELETE)
        }
            .withCollectionExposure { metadata: ResourceMetadata?, httpMethods: ConfigurableHttpMethods ->
                httpMethods.disable(HttpMethod.PUT)
                    .disable(HttpMethod.PATCH).disable(HttpMethod.POST).disable(HttpMethod.DELETE)
            }
    }
}

• First we set the default base path of our query api to: "/grocery/marketplace/query/api/v1"
• Second we restricted the allowed operations to only GET

Application in Action​

When starting our Spring Boot Application, the Flyway will create the tables defined in our migration files and insert the data

docker run -p 5050:80 \
  -e PGADMIN_DEFAULT_EMAIL=admin@example.com \
  -e PGADMIN_DEFAULT_PASSWORD=admin \
  --name pgadmin \
  -d dpage/pgadmin4

Now, let's access our query api and explore the result:

GET /grocery/marketplace/query/api/v1
Host: http://localhost:8080

{
  "_links" : {
    // a subset of the full response, other entities cutted to make this example shorter
    "products" : {
      "href" : "http://localhost:8080/grocery/marketplace/query/api/v1/products{?page,size,sort*}",
      "templated" : true
    },
    "categories" : {
      "href" : "http://localhost:8080/grocery/marketplace/query/api/v1/categories{?page,size,sort*}",
      "templated" : true
    },
    "profile" : {
      "href" : "http://localhost:8080/grocery/marketplace/query/api/v1/profile"
    }
  }
}

Above we have a Spring Data REST response uses HAL format, which provides links to related resources.

• "products" and "categories": These are URLs for fetching product and category data, with templated parameters (page, size, sort) that allow for pagination and sorting.
• "profile": A link to the API's profile, which provides metadata about the API.

These links allow clients to navigate the API easily and interact with related data without hardcoding URLs.

Conclusion​

Understanding the levels of RESTful APIs helps developers create systems that are more robust, scalable, and easier to use. While many APIs remain at Levels 1 or 2, aiming for Level 3 ensures a fully RESTful experience that adheres to the principles of the web.

Which level does your API align with? Share your thoughts in the comments below!

• Richardson's Maturity Model
• Spring in Action
• Spring Data REST

Use case​

In this phase, we begin by collecting requirements from a business perspective to ensure a thorough understanding of the objectives. Once these requirements are established, we then investigate how architectural patterns and software development methodologies can be utilized to construct the product effectively.

Currently, local grocery stores must either visit large distribution companies or contact them individually to inquire about pricing, stock availability, and delivery schedules when placing orders. This process is time-consuming and inefficient for grocery managers. To address this challenge, we propose developing a platform that enables managers to easily check prices, view stock levels, place orders, and track deliveries in one streamlined solution.

Personas and User Journey​

To develop a system that effectively tackles the relevant challenges and provides significant value, it is imperative that every aspect of the system is designed with users in focus. This makes it vital to thoroughly understand their frustrations, motivations, and expectations regarding the new product we are creating

• Grocery Manager
  • Profile: Typically has a bachelor's degree.
  • Frustrations: Running out of stock, lack of visibility over deliveries, price comparison is a time-consuming task.
  • Motivations: Save management time, focus on customer relationships and service quality, ensure stock levels are always adequate.

Architecture & Design

In the previous section, we presented a brief overview of the business domain, requirements, and one of the system's future users. At this stage, we need to make architectural and design decisions.

Architectural Style​

While the brainstorming outputs for this example are somewhat limited, we can easily envision various services, such as Order Service, Provider Service, Delivery Service, and Product Service. Now, suppose we want to develop all these services simultaneously, with different teams specializing in distinct technology stacks. It is essential that these services remain decoupled from one another, ensuring that a change in the design of one service does not affect the others.

Regarding deployment, we aim to deploy the Product Service before the others to deliver value as quickly as possible. This necessitates that the services be independently deployable and scalable.

By organizing our product around services, we can enhance fault tolerance. For example, if the Delivery Service is unavailable, users should still be able to access other services. For these reasons, we believe that a microservices architecture is the most suitable architectural style for this project.

Regarding deployment, we aim to deploy the Product Service before the others to deliver value as quickly as possible. This requires that services be independently deployable and scalable.

Domain Design​

The complexity of the business domain, the rules, and the number of services (system components) lead us to consider Domain-Driven Design (DDD). So, what is DDD?

In traditional object-oriented design, a domain model is a collection of interconnected classes. For example:

Figure 1: Object Oriented Domain Model

With this design, operations such as loading or deleting an Order object encompass more than just the Order itself; they also involve related data, such as order items and delivery details. The absence of clear boundaries complicates updates, as business rules, imagine a business logic such as "minimum order amounts" must be enforced meticulously to preserve invariants

This is where DDD can help, by using Aggregates

An aggregate is a cluster of domain objects within a boundary that can be treated as a unit

Figure 2 shows a simplified version of the domain model aggregates. Designing domain model using the DDD Aggregate pattern recommand that aggregates match a set of rules: 1. Reference only the aggregate root 2. Inter-aggregate references must use primary keys 3. One transaction creates or updates one aggregate

Figure 2: Domain Model Aggregates Simplified

Implementation

Now that we have designed the domain model aggregates and the achitecture implementation view Microservices, let's dive into the architecture logical view Hexagonal Architecture , please refer to this post to learn about Architecture Implementation view, Hexagonal option and why we adopt it

I'm going to use Kotlin as programming language and maven as a build tool

Pilot feature​

Bootstrap the project​

Let's consider the following feature: place order

As a grocery manager, I need to place an order for a product so I can provision the stock Constraint 1: The minimum order quantity is 20.

Using maven build tool, let's create a project for kotlin.

1. create a maven project using the following cmd:

    mvn archetype:generate \
    -DgroupId=com.algodema \
    -DartifactId=grocery-marketplace-order-service \
    -DarchetypeArtifactId=maven-archetype-quickstart \
    -DarchetypeVersion=1.4 \
    -DinteractiveMode=false

2. convert the project to kotlin by replacing the src/main/java and src/test/java directories with src/main/kotlin
3. modify pom.xml for Kotlin, JUnit, and AspectJ
4. checkout the project on github: (https://github.com/algodema/microservices-labs/tree/main/grocery-marketplace-order-service)

Implement the place order feature using TDD​

What about starting with writing a test scenario for our uese case using TDD (Test Driven Development), this approach help me immediately implement business logic, in this case ensure no order will be created with quantity less than 20 unit.

    @Test
    fun `should not place order with quantity lower than 20`() {

        val productId: ProductId = ProductId(UUID.randomUUID())
        val providerId: ProviderId = ProviderId(UUID.randomUUID())
        val quantity: Int = 16

        val orderCreated = placeOrder.invoke(productId, providerId, quantity)

        Assertions.assertEquals(orderCreated.state, OrderState.PLACED)
    }

I started by creating "PlaceOrderFeatureTest" test class, then writing my first test as we see in the snippet above. If we look at the project structure in figure below:

The approach involves declaring instances of productId, providerId, and placeOrder prior to the existence of their respective classes. Subsequently, these classes are developed and organized into packages in accordance with the principles of hexagonal architecture, which positions business logic at the core, as represented by the domain package.

We continue writing tests, they should be fixed and failed as we implement the business requirements in our place order feature.

Infrastructure implementation​

Now that we created our first feature, we would like to expose it through a REST API endpoint, but also persist the created Order in a storage, for the purpose of this tutorial, we will implement a in-memory persistence.

The hexagonal architecture defines ports and adapters as interfaces and implementations consequentially used to make the domain interacting and connecting with other components of the application such as (persistency, api, messaging, ...)

Let's create the follwing ports and adapters:

1. OrderRepository as an outbond port.
2. PlaceOrder as inbound port.
3. OrdersApi as inbound adapter that will use PlaceOrder port to expose the feature as REST API endpoint.
4. InMemoryOrderRepostory as an outbound adapter that will implement the OrderRepository port interface.

Below we created the InMemoryOrderRepository class that implements the domain port OrderRepository interface, Note also that we annotate this class with the Spring framework @Repository in order to make it discoverable by Spring IoC container. Remember that we use Spring at the infrastcuture level without any coupling with the domain.

    package com.algodema.grocery.marketplace.orderservice.infrastructure.spi

    import com.algodema.grocery.marketplace.orderservice.domain.models.order.Order
    import com.algodema.grocery.marketplace.orderservice.domain.ports.outbound.OrderRepository
    import org.springframework.stereotype.Repository

    @Repository
    open class InMemoryOrderRepository: OrderRepository {
        override fun save(order: Order): Order {
            throw NotImplementedError("not yet implemented")
        }
    }

Next, we will introduce the Spring framework at the infrastructure layer to create a REST API. We rely on the Spring framework's dependency injection to make our component connections decoupled. Using Dependency Injection, the place order feature will hold an instance of OrderRepository to save the created order, and at the infrastructure's API adapter, the REST Controller will hold instances of our features by dependency injection as well.

To enable Spring to identify our features for dependency injection, we will create a new root package designated as ddd. This package will encompass the necessary annotations:

1. Feature Annotation: marks our features classes

    package com.algodema.grocery.marketplace.orderservice.ddd

    @Retention(AnnotationRetention.RUNTIME)
    annotation class Feature()

After creation, we utilize the Feature annotation to designate our place order functionality accordingly.

    @Feature
    class PlaceOrder(private val repository: OrderRepository) : PlaceOrder {
        // ...
    }

Let's create the OrdersApi in the infrastructure package under the sub package api, as follow:

    package com.algodema.grocery.marketplace.orderservice.infrastructure.api

    import com.algodema.grocery.marketplace.orderservice.domain.features.PlaceOrder
    import com.algodema.grocery.marketplace.orderservice.domain.models.order.Order
    import com.algodema.grocery.marketplace.orderservice.domain.models.product.ProductId
    import com.algodema.grocery.marketplace.orderservice.domain.models.provider.ProviderId
    import org.springframework.web.bind.annotation.PostMapping
    import org.springframework.web.bind.annotation.RequestBody
    import org.springframework.web.bind.annotation.RequestMapping
    import org.springframework.web.bind.annotation.RestController

    @RestController
    @RequestMapping("/orders")
    class OrderServiceApi(private val placeOrder: PlaceOrder) {

        @PostMapping
        fun placeOrder(@RequestBody placeOrderRequest: PlaceOrderRequest): Order {

            val productId: ProductId = ProductId.from(placeOrderRequest.productId)
            val providerId: ProviderId = ProviderId.from(placeOrderRequest.providerId)
            val quantity: Int = placeOrderRequest.quantity

            return placeOrder.invoke(productId, providerId, quantity)
        }

    }

We now need to configure Spring to recognize our annotated features, enabling them to be loaded into its bean container. To achieve this, we will create a configuration class within a subpackage named config under the infrastructure package. Below is our configuration class:

    package com.algodema.grocery.marketplace.orderservice.infrastructure.config

    import com.algodema.grocery.marketplace.orderservice.ddd.Feature
    import org.springframework.context.annotation.ComponentScan
    import org.springframework.context.annotation.Configuration
    import org.springframework.context.annotation.FilterType

    @Configuration
    @ComponentScan(
        basePackages = ["com.algodema.grocery.marketplace.orderservice"],
        includeFilters = [ComponentScan.Filter(
            type = FilterType.ANNOTATION,
            value = [Feature::class]
        )]
    )
    open class DomainInjectionConfig

The final step is to transform our application's entry point class into a Spring Boot application as follows:

    package com.algodema.grocery.marketplace.orderservice

    import org.springframework.boot.autoconfigure.SpringBootApplication
    import org.springframework.boot.runApplication


    @SpringBootApplication
    open class App

    fun main(args: Array<String>) {
        runApplication<App>(*args)
    }

You may have noticed the presence of the keyword "open" preceding the classes App, DomainInjectionConfig, and InMemoryOrderRepository. Here is the rationale behind this choice:

For the purpose of this exercice we decided to use the open modifier to make our classes annotated with Spring not final as we have few classes, but for large application we can use the All-open compiler plugin instead of preceeding each classe required to be open with the open keyword.

Finally, let's run the application either using your IDE such as Intellij Idea or from command line using maven as follow:

mvn spring-boot:run

Below a screenshot of the place order request response overview:

Conclusion​

This post has walked you through the entire process of building a fully functional Microservice, from design to implementation, using DDD and Hexagonal Architecture. My goal was to share knowledge and experiences regarding the methodology, architecture, and patterns needed to create a maintainable, extensible, and deployable Microservice. However, delivering a production-ready product requires addressing more advanced aspects. Below is a non-exhaustive list of such considerations:

• Api Errors Handling
• Application security
• Database persistency
• Api documentation
• Env variable config

Keep in mind that no single pattern, architectural style, or programming language suits all software product requirements. It's important to focus on understanding and defining the requirements, parameters, and challenges to make the most informed and effective decisions

References:​

• Domain Driven Design
• Microservies Patterns
• Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin
• Dependency Injection
• The IoC Container
• Software Architecture: The Logical View
• Software Architecture: The Implementation View

photo source

Functions​

Functions constitute a centric component in the recent software programs, the reason why we should care a lot about all of their aspects from naming, length, composition, arguments and error handling.

Small​

Yes "small" is the main rule a function should comply with, so it tell us what it does exactly because a function should do one thing, do it well and only.

To keep the function also short, [if, else, while, etc ...] statements should be only one line, and probably this line is function call:

fun bookTrain(bookingRequest: BookingRequest): Booking {
    validBookingRequest(bookingRequest)
    val booking = Booking.from(bookingRequest)
    booking.status(BookingStatus.PENDING)
    return booking
}

Single abstraction level​

Or the principle of "Doing one thing", the idea is not about writing function with single line of code, or one step but writing it with the restriction to cover only one computation, see example below:

   fun validBookingRequest(bookingRequest: BookingRequest) {
    if (bookingRequest.from == bookingRequest.to) {
        throw InvalidBookingRequestException("departure and arrival stations are the same")
    } else if (bookignRequest.stops > 5) {
        throw InvalidBookingRequestException("more than 5 stops is not allowed")
    }

}

The Step-down rule​

We write code to be read, so writing functions in an order like a narrative text, if we have to put the functions of the above two examples, they should appear in the following order:

   fun bookTrain(bookingRequest: BookingRequest): Booking {
    validBookingRequest(bookingRequest)
    ...

    fun validBookingRequest(bookingRequest: BookingRequest) {
        ...

we can see clearly that the caller function is above the called one

Switch statements​

While switch statement can easily impact badly you clean code, The key issue with switch statements is that they often lead to violations of the Single Responsibility Principle (SRP) and can make code harder to extend and maintain.

   fun calculateWashCost(vehicle: Vehicle): Money {
    when (vehicle.type) {
        CAR -> calculateCarWashCost(vehicle)
        BUS -> calculateBusWashCost(vehicle)
        MOTOCYCLE -> calculateMotoCycleWashCost(vehicle)
        else -> {
            throw InvalidVehiculeType(vehicle.type)
        }
    }
}

There many issues with this function above, first the function is large and each time new vehicle type will be added, it will grow even more. Second it violates the Single Responsibility Principle (SRP) because there is more one reason for it to change, but the worst probem is there will be more functions that will have the same structure:

• CalculateParkingCost(vehicle: Vehicle): Money
• CalculateCarbonTax(vehicle: Vehicle): Money

A solution proposed by Robert C.Martin is his book "Clean Code" is to hide the switch statement in an abstract factory, and the factory will use the switch statement to create the appropriate instances of the derivatives of Vehicle. And the various functions such as CalculateParkingCost, CalculateCarbonTax will be dispatched polymorphic through the Vehicle interface.

abstract class Vehicle {
    abstract fun calculateWashCost(): Money
    abstract fun calculateParkingCost(): Money
    abstract fun calculateCarbonTax(): Money
}

abstract interface VehicleFactory {
    abstract fun createVehicle(vehicle: Vehicle): Vehicle
}

class VehicleFactoryImpl() {
    fun createVehicle(vehicle: Vehicle): Vehicle {
        return when (vehicle.type) {
            CAR -> Car(vehicle)
            BUS -> Bus(vehicle)
            MOTOCYCLE -> MotoCycle(vehicle)
            else -> {
                throw InvalidVehiculeType(vehicle.type)
            }
        }
    }
}

Functions common patterns​

Don't hesitate to make your function's name long if necessary in order to ensure a significant name. When it comes to function argument the ideal number is 3, then comes one (monadic), followed closely by two (dyadic). Three arguments (triadic) should be avoided where possible. The challenge with arguments resides in testing you can imagine the difficulty of writing all the test cases to ensure that all the various combinations of arguments work correctly. Have you ever heard about "Flag Argument"? Flag argument is an argument of type boolean where the function do a thing when it's true and another thing if it's false, these arguments violates the Single Responsibility Principle (SRP).

Argument Objects​

If a function needs more than two or three arguments, there is probably a way to wrap some of them into an object, see the following example:

  fun deployApplication(applicationId: Int, cpu: Int, memory: Int, storage: Int, tag: String) {
    //  do something ...
}

We can reduce the number of argument by passing an object representing the infrastructure requirements, see example below

  fun deployApplication(applicationId: Int, infrastructureRequirements: InfrastructureRequirements, tag: String) {
    // do something ...
}

Command Query Separation​

The Command-Query Separation (CQS) principle states that a function should either perform an action (a command) or return data (a query), but not both. This makes the code more predictable, easier to test, and cleaner.

  // Query function: returns whether the withdrawal can happen (no state modification)
fun canWithdraw(balance: Int, amount: Int): Boolean {
    return amount <= balance
}

// Command function: performs withdrawal by returning the new balance (state modification, no return of query data)
fun withdraw(balance: Int, amount: Int): Int {
    return if (canWithdraw(balance, amount)) {
        balance - amount  // Returns the updated balance
    } else {
        balance  // No changes if insufficient funds
    }
}

fun main() {
    var balance = 100

    // Query if withdrawal is possible
    if (canWithdraw(balance, 50)) {
        // Command: Update the balance by performing withdrawal
        balance = withdraw(balance, 50)
        println("Withdrawal successful. New balance: $balance")
    } else {
        println("Insufficient funds")
    }
}

Conclusion​

Let's admit that functions are fundamental components of our code, so it's crucial to invest time and effort into defining them properly, including their names, arguments, and statements. Writing software is similar to any other form of writing—you begin by drafting your ideas, then refine them until they flow smoothly. Remember, we write code not just for execution, but also to be easily understood by others.

• The Clean Code Blog
• Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin
• Functional Design: Principles, Patterns, and Practices by Robert C. Martin
• 10 steps to clean code
• Kotlin coding conventions

photo source

Clean Code!​

Why should I care?​

We, software engineers almost spent more time reading code than writing new lines, how many times do we complain about someone else's code? Many factors can give us an idea about the quality of code and how much the writer cares about it. If you dislike reading bad code, you already made your first step toward writing good code if you care about your heritage. There are many good reasons to care about writing clean code, adding the artistic layer to your code is an inspiring reason for me to learn and apply the clean code rules and principles.

What clean code brings to me?​

Clean code is what makes us professional programmers, someone with high-level ethics who cares about the present and the future of his code, he believes that lines of code can live for long and can be enhanced by others with ease and passion. Like a book author what makes him happy is how readers enjoy turning the pages of his book one after the other without realizing the time elapsed.

Clean code is about philosophy!​

Clean code makes us more than a programmer, it helps us develop a good vision of the software we are building, caring about its growth, evolutionary, and enhancement. Clean code makes us a thinker about maintainability, design, and the ability of the software to cope with changes quickly and easily. Code is written to live but also to change and evolve.

We are authors​

Yes, we programmers are authors, that said, we have readers, Indeed we are responsible for communicating well with readers. The next time we write a line of code, we'll remember we are authors, writing for readers who will judge our effort.

What clean code covers?​

Naming​

As a programmer the first step of writing code is choosing names, for variables, functions, classes, packages and source code files. While this seems easy and instinctive, choosing good names takes time but saves more than it takes.

Let's look at the following code snipped:

 d = Date.now();

The name "d" above has nothing to reveal, even tough it is a date object, but we cannot know the intention of usage, either its start date or end date. Note that even naming it startDate doesn't give it any sense, because we need to know as a reader what is the context of the start date. Hers is a suggestion for this example:

taskStartDate = Date.now();

Abbreviation​

Abbreviation Is one of the most common mistakes concerning variable naming, as a programmer can you guess what this variable name below means?

msg

Can you know that msg may mean "message" or "most scored goal"? Personally, I don't want to spend time exploring many lines before or after this one to understand the context of this variable in case I need to make a change. The rule is to avoid any disinformation.

Distinction​

Another issue with naming is the number-series such as (variable1, variable2), consider the following function:

public static void duplicateString(char a1[], char a2[]){
        ...
        }

is it not more readable if we use "source" and "destination" as the names of the two arguments? I think yes, it is.

Adding noise words is another problem that impacts the cleanness of the code, you may want to specify that a variable is a String, so you name it: "emailContentString", Here the "String" is just redundant as is not part of the name but the type which has nothing to do with the meaning of the variable.

Word Sounding​

As a programmer, there is a good chance that while we are writing code, our brain is pronouncing the text we type. when we cut the connection between our brain and the activity of writing, we usually type variable names that could be difficult to pronounce, and the consequences are multiple: other developers won't be able to retain them easily and these names will be demanding to discuss with the business analysts. While English is the most used natural language used to write code, using other languages such as French or Italian, apply the same rules regarding how easily the variables, functions, or classes names are pronounceable.

Are names accessible?​

Each time I take over developing a new feature or fixing a bug that requires modifying a source code that not has been writing by me, I start by searching some keywords that I got from the context of the domain system. For Example when I was asked to fix a UI bug in a web application developed using ReactJS then I was trying to find the matching component in the source code, but it was not as easy as expected and I spent 30 minutes before finding the component named with a number prefix: 1CounterComponent. This is why choosing names that are straightforward to find is a very useful rule to follow.

Coding Conventions​

Every programming language provides coding conventions regarding variables, functions, classes, and naming source code files. While the naming took a good part of these conventions, they also cover indentation, comments, declaration order, etc ... I don't hesitate to refer to these conventions. But during my modest experience, I came across some coding conventions from specific programming languages applied to another one. This is strongly discouraged or prohibited by the teams themselves.

Technical Vs Business Names​

We write code to build software that will be solving a problem, For example: coding an application that computes taxes. Trying to be a good programmer implies differentiating technical things from business-related ones. whenever you code a technical concept don't try to use mainly a domain name, For example: declaring a variable that holds an instance of the HTTP client could have the following name: httpClient, but if we try to include the business-related usage we can name it: taxesRulesHttpClient as you can see in this case the domain doesn't bring any help instead is just making a technical thing harder.

A last note​

Writing clean code requires a piece of cultural knowledge and good descriptive, communication, and writing skills, we can develop these skills by learning from communication experts either by reading books or taking courses on how to write, synthesis, and order ideas. Also evolving on the natural language we use to code. For example, if we write code in English, it will be helpful to learn more words, synonyms, sentences, etc...

So far I wanted to pay your attention to the importance of clean code, and how can impact the software's quality and maintenance, We covered mainly the naming concept in this part. Other articles will follow to cover other aspects concerned by clean code.

• The Clean Code Blog
• Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin
• 10 steps to clean code
• Kotlin coding conventions

photo source

Functional Testing​

What is a functional test ?​

Functional tests are one of these software testing approaches or test types such as (unit tests, integration tests, load tests, penetration tests, ...) all with one mission to test that the software is compliant whether with business specification, technical requirements or other quality and usability metrics. But functional tests focus on ensuring that the software functions behave as expected by the business specifications, these tests don't interact with source code such as unit tests, but mainly with the software features. A functional test usually puts the system, the application or the software we want to test in an initial state where we provide the necessary elements to make the test executable such as storing a list of cars in the database, then we test the feature find a car for the period of (2nd march to 7th march), then we validate that the output matches the expected result.

Why do we need to write functional tests?​

We need to write functional test to validate the features from a user perspective, hence we validate the following:

• Feature is working as expected by the specifications
• Usability: checks whether the feature is easily usable, for example, a button is freely reachable on the page.
• Errors: when a subsystem is not responding, do we display an error message to the user to help him understand what's going on.

Functional testing style​

A common form that functional testing take is the Given-When-Then, this approach coming from the BDD (Behaviour Driven Development) defines the structure of many testing frameworks such as Cucumber that we will cover in our example later in this article. The prime idea is to break down a scenario (test) into three sections:

• Given: the given part defines the pre-conditions before challenging the system by executing or running a feature.
• When: is do we want to do with the system, for example ( when I book a car)
• Then: describes the expected result or output after the application or the software behaves in to respond to your action.

To simplify the idea, let's write an example for a rental car website using the Cucumber Tool (Framework):

Feature: User book a car Scenario: User requests to book a car from 1st March to 7th March 2022 Given I select a car from the available cars for the period (1st March to 7th March 2022) And I select GPS as an additional Option And I select Full Insurance When I book the car Then I should receive a confirmation

BDD: Behavior Driven Development​

BDD combines the best practices of Test Driven Development TDD, Domain-driven Development (DDD), and Object Oriented Programming (OOPs) For an agile team, scoping a feature is a very important task, as the stakeholders are talking about the business requirements, the development team is more interested in the technical challenges, Here comes the BDD to provide a common language that allows efficient communication and feedback and then a perfect specification, development vision, and feature delivery.

BDD closes the gap between the business and the technical people by:

• Encouraging collaboration across roles to build a shared understanding of the problem to be solved.
• Working in a rapid and small iteration to promote the feedback and optimize the value delivery.
• Producing documentation that is automatically checked against the software behavior.

There is a good chance that you're agile at your organization so you already plan your work in small increments of value like User Stories. In this case, BDD will help you to deliver your promises of agile on time. BDD does not replaces your processes but enhances them.

BDD and Functional Testing​

Let's focus on the word Behaviour so functional testing of behavior testing is these tests your write to check your system or the software you're building how behaves. Functional testing can also be called behavior testing.

Behaviour Testing in action​

To illustrate all these abstract notions explained briefly in this article, let's write a small application and its behavior tests using Kotlin programming language and Cucumber

• Kotlin is a JVM programming language, like Java, Scala, or Groovy
• Cucumber is a testing tool that supports Behavior Driven Development
• Gherkin is a business readable language that helps you to describe business behavior without going into details of implementation

We will need the following to build this example:

1. Java SE (Java 9 and higher are not yet supported by Cucumber)
2. Maven - version 3.3.1 or higher
3. IntelliJ IDEA (which will be used in this tutorial)

• IntelliJ IDEA Cucumber for Java plugin
• IntelliJ IDEA Kotlin plugin

1. Clone the project from github

git clone https://github.com/reda-jaifar/hands-on-kotlin.git
cd sportair

2. Open the project in IntelliJ IDEA:

   • File -> Open… -> (Select the pom.xml)
   • Select Open as Project

3. Verify Cucumber installation

mvn test