When I first started looking into how they worked, I assumed there had to be a huge amount of complicated code behind all of it.

But the basic idea is actually pretty simple.

At its core, a Discord bot is just a Python program that connects to Discord, waits for something to happen, and then decides how to respond. Once you understand that basic idea, you can start adding features one at a time and turn a simple bot into something much more interesting.

In this tutorial, we'll start with a very small bot and gradually build it into something more capable. Along the way, you'll learn about Discord commands, events, asynchronous Python, user state, environment variables, and basic deployment.

One quick disclaimer before we start: the mental-wellness feature that we'll be integrating in this bot in this project is not therapy, and the bot is not a therapist or medical professional. It should only provide general supportive suggestions and encourage users to reach out to a trusted person when appropriate.

With that out of the way, let's get coding!

What We'll Cover:

• What We're Building

• What You Need

• Create the Discord Bot

• Give the Bot Permission to Read Messages

• Create the Project

• Create a Virtual Environment

• Install discord.py

• Create Your First Bot

  • Importing Our Libraries

  • Loading the Token

  • Understanding Intents

  • What Isctx?

  • Why Does Everything Sayasyncandawait?

  • Run the Bot

• Build the Storytelling System

  • Let's Make the Story Remember the User

  • Add a Story Choice

  • Add a Casual Chat Command

  • Add a Mental-Wellness Support Feature

  • Add a Help Command

  • Improve Error Handling

• Put Everything Together

• Our Bot Doesn't Actually Remember Anything

  • Create the Database

  • Save a User's Story

  • Get the Story Back

  • Put It Into a Command

• Adding Real AI Chat

  • Install the Hugging Face Library

  • Create the Hugging Face Client

  • Connect the AI Model to the Bot

  • Handle AI Errors

• How Do We Keep the Bot Online?

  • Option 1: Run It on Your Computer

  • Option 2: Host It on a Server

• What "Forever" Actually Means

• Don't Try to "Keep It Awake" With Random Tricks

• Additional Features and Where to Go Next

• Test Everything Locally First

• Deploying the Bot

  • The Start Command

• Remember: Keep Your Secrets Secret

• What You Learned

• Final Thoughts

What We're Building

Our finished bot will have several commands:

!hello
!story
!chat hello!
!support I'm having a stressful day
!help

For example:

User:
!story

Bot:
You wake up inside an abandoned library.

There are three doors in front of you:

1. A red wooden door
2. A metal door covered in strange symbols
3. A staircase leading underground

Which one do you choose?

The user can then continue the story.

For chat:

User:
!chat What's a good way to learn Python?

Bot:
Try building small projects instead of only reading tutorials.
A Discord bot is actually a pretty fun project to start with.

And for mental-wellness support:

User:
!support I'm really stressed about school.

Bot:
That sounds like a lot to deal with. You could try breaking
the work into one small task at a time and taking a short
break between tasks.

I'm a bot, not a therapist, so if you need personal support,
consider talking with someone you trust.

The goal isn't to make a magical robot therapist. It's to build a useful bot while learning how Discord APIs, Python functions, events, asynchronous programming, and basic conversational logic fit together.

What You Need

You only need a few things:

• Python (version 3.8+ is recommended)

• A Discord account

• A Discord server where you have permission to add a bot

• A code editor (I personally prefer VS Code or PyCharm)

• The discord.py library

We'll also use Python's built-in os module for reading environment variables.

If you don't already have Python installed, install a current supported version of Python from the official Python website.

Then check that Python works:

python --version

You should see something similar to:

Python 3.x.x

Create the Discord Bot

Before Python can control Discord, we need to create a Discord application.

Go to the Discord Developer Portal: https://discord.com/developers/applications

This is what the page will look like, you might need to login with your discord email/username and password before you start.

Click on the "New Application" button on the top right and give your bot a name. For this tutorial, let's call ours StoryBot.

The application is basically the home for your bot.

Discord's developer platform provides the tools needed to create and configure applications and bots.

Once you've created the application, open its Bot section and create the bot user. You can add your own icon picture and your own banner if you want to.

You will then go to the Token section and click on "Reset Token" to generate your token. Treat that token like a password. Do NOT put it directly into your Python source code.

Never do this:

bot.run("my-secret-token")

And definitely don't upload a token to GitHub or commit it to source control. Instead, we'll store it in an environment variable, which we'll talk about later.

Give the Bot Permission to Read Messages

Our bot needs to see the messages that contain commands.

Discord uses something called Gateway Intents to control which types of events a bot receives. The discord.py documentation explains that intents must be enabled both in your code and, for privileged intents, in the Discord Developer Portal.

In the Developer Portal, find:

Bot
→ Privileged Gateway Intents

Enable:

Message Content Intent

It should look somewhat like this:

We'll also enable it in Python, which we will talk about later in this article.

Create the Project

Create a folder:

discord-story-bot/

Inside it, we'll eventually have:

discord-story-bot/
│
├── bot.py
├── requirements.txt
└── .env

The three important files are:

• bot.py: our Python program

• requirements.txt: text file that contains the name of the packages our bot needs

• .env: our secret token during local development

Create a Virtual Environment

Open your terminal inside the project folder.

Run:

python -m venv venv

Then activate it.

On Windows:

venv\Scripts\activate

On macOS/Linux:

source venv/bin/activate

A virtual environment gives this project its own little Python bubble.

That means packages installed for this bot won't randomly interfere with packages used by another project.

Install discord.py

Now install the Discord library:

pip install -U discord.py

The official discord.py documentation uses this installation approach for setting up the library.

We'll also install python-dotenv, which makes reading our local .env file easier:

pip install python-dotenv

Then save the dependencies:

pip freeze > requirements.txt

Your requirements.txt should contain the packages needed by the project.

Create Your First Bot

Let's start small.

Open bot.py:

import os

import discord
from discord.ext import commands
from dotenv import load_dotenv


load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")

intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(
    command_prefix="!",
    intents=intents
)


@bot.event
async def on_ready():
    print(f"Logged in as {bot.user}")


@bot.command()
async def hello(ctx):
    await ctx.send("Hello! I'm online.")


bot.run(TOKEN)

That is already a functional Discord bot.

Let's break it apart piece by piece.

Importing Our Libraries

First:

import os

os lets Python communicate with parts of the operating system.

We'll use it to read environment variables.

Next:

import discord

This imports discord.py.

Then:

from discord.ext import commands

The commands extension makes creating commands much easier.

Instead of manually checking every message for something like !hello, we can write:

@bot.command()
async def hello(ctx):
    await ctx.send("Hello!")

The discord.py command system is built around Python functions decorated as commands.

Finally:

from dotenv import load_dotenv

This lets us load values from our .env file.

Loading the Token

Our bot needs a token to connect our Python program to Discord. Think of the token as a password that allows our program to authenticate as the bot.

We don't want to put this secret directly into our Python code. Instead, we'll store it in an environment variable.

First, install python-dotenv:

pip install python-dotenv

This package lets Python read values from a .env file.

Now create a new file called .env in the same folder as bot.py.

Inside .env, add:

DISCORD_TOKEN=YOUR_BOT_TOKEN_HERE

Replace YOUR_BOT_TOKEN_HERE with the token you copied from the Discord Developer Portal.

Your file should look something like this:

DISCORD_TOKEN=your_actual_token_here

Don't share this token with anyone or upload your .env file to GitHub. Your bot token should be treated like a password.

To make sure Git doesn't accidentally include the .env file in a repository, create a file called .gitignore in your project folder and add:

.env
venv/
__pycache__/

Now let's load the token in Python.

At the top of bot.py, add:

import os
from dotenv import load_dotenv

Then add:

load_dotenv()

This tells Python to look for the .env file and load the variables inside it.

Now we can get our Discord token:

TOKEN = os.getenv("DISCORD_TOKEN")

os.getenv() looks for the environment variable named "DISCORD_TOKEN" and gives us its value.

We can also check that the token was actually found:

if not TOKEN:
    raise RuntimeError("DISCORD_TOKEN is not set.")

If Python can't find the token, the program stops and gives us a clear error message instead of failing later in a confusing way.

Understanding Intents

Remember how we talked about enabling message content readability in python? We are going to do that now.

Add:

intents = discord.Intents.default()
intents.message_content = True

The first line creates a set of Discord's default intents.

The second line tells Discord that our bot needs access to message content.

Now we need to give these intents to our bot when we create it:

bot = commands.Bot(
    command_prefix="!",
    intents=intents
)

The command_prefix="!" means our bot will recognize commands that begin with !.

For example:

!hello

The intents=intents part gives our bot the permissions we configured above.

There are two steps here because Discord needs to know that our bot is allowed to receive message content, while our Python program also needs to tell Discord that it wants to receive it.

Our basic setup should now look like this:

import os
import discord

from dotenv import load_dotenv
from discord.ext import commands

load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")

if not TOKEN:
    raise RuntimeError("DISCORD_TOKEN is not set.")

intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(
    command_prefix="!",
    intents=intents
)

Now our bot has its token safely loaded and discord.py knows which intents to request when it connects to Discord.

What Is ctx?

This part can look weird when you're learning Discord bots:

async def hello(ctx):

What is ctx? ctx stands for context. It contains information about the command that was used.

For example, it can tell us:

• Who ran the command

• Which server it came from

• Which channel it came from

• What message triggered it

Then:

await ctx.send("Hello!")

means:

"Send this message back to the place where the command was used."

Why Does Everything Say async and await?

You might notice:

async def hello(ctx):

and:

await ctx.send(...)

Discord bots spend a lot of time waiting.

They wait for:

• Messages

• Discord responses

• API requests

• Timers

• Other events

Python's asynchronous programming features allow the bot to wait for these operations without freezing everything else.

You don't need to become an async-programming expert before building your first bot.

For now, think of await as:

"Pause this task until this operation finishes, while letting the bot handle other things."

Run the Bot

Start it with:

python bot.py

If everything works, your terminal should print something similar to:

Logged in as StoryBot

Now go to your Discord server and type !hello. Your bot should respond.

Congratulations! You've officially made a Discord bot.

Now let's make it interesting.

Build the Storytelling System

First, we're going to create an interactive storytelling command.

At the top of bot.py, add:

import random

Then create some story ingredients:

story_locations = [
    "an abandoned library",
    "a mysterious island",
    "a futuristic city",
    "a hidden underground laboratory",
    "a forest that never appears on maps"
]

story_items = [
    "a glowing key",
    "an ancient notebook",
    "a strange compass",
    "a locked metal box",
    "a mysterious photograph"
]

story_events = [
    "You hear footsteps behind you.",
    "The lights suddenly turn off.",
    "A hidden door opens nearby.",
    "Your phone starts displaying a message from an unknown sender.",
    "You notice that the room has changed."
]

Now create the command:

@bot.command()
async def story(ctx):
    location = random.choice(story_locations)
    item = random.choice(story_items)
    event = random.choice(story_events)

    story_text = (
        f"You wake up in {location}.\n\n"
        f"Next to you is {item}.\n\n"
        f"{event}\n\n"
        "What do you do?"
    )

    await ctx.send(story_text)

Now !story might produce:

You wake up in a futuristic city.

Next to you is an ancient notebook.

A hidden door opens nearby.

What do you do?

Run it again and you might get something completely different.

That's because of:

random.choice(...)

Python randomly picks one item from each list.

It's a simple technique, but suddenly your bot can generate hundreds of different combinations.

Let's Make the Story Remember the User

Random stories are fun, but interactive stories are much better when the bot remembers what happened.

We can create a dictionary:

user_stories = {}

The dictionary will store story information for each user.

For example:

user ID → current story

Now let's modify the story command:

@bot.command()
async def story(ctx):
    user_id = ctx.author.id

    location = random.choice(story_locations)
    item = random.choice(story_items)
    event = random.choice(story_events)

    user_stories[user_id] = {
        "location": location,
        "item": item,
        "event": event
    }

    await ctx.send(
        f"You wake up in {location}.\n\n"
        f"Next to you is {item}.\n\n"
        f"{event}\n\n"
        "What do you do?"
    )

Now each user can have their own active story.

Add a Story Choice

Let's give users choices.

@bot.command()
async def choose(ctx, choice: str):
    user_id = ctx.author.id

    if user_id not in user_stories:
        await ctx.send("You don't have an active story. Try `!story` first.")
        return

    choice = choice.lower()

    if choice == "left":
        response = (
            "You head left and discover a room filled with old maps. "
            "One of them has your name written on it."
        )

    elif choice == "right":
        response = (
            "You head right and find a staircase leading toward "
            "a strange blue light."
        )

    else:
        response = "Try choosing `left` or `right`."

    await ctx.send(response)

Now users can type:

!choose left

or:

!choose right

Notice this:

async def choose(ctx, choice: str):

The choice parameter receives the text after the command.

So:

!choose left

becomes approximately:

choice = "left"

This is one of the reasons command frameworks are so convenient. A command framework is a set of tools that makes it easier to create and manage commands in a program. In our case, discord.py provides the command framework that lets us turn Python functions into Discord commands using decorators like @bot.command().

Instead of manually checking every message to figure out whether someone typed !choose, discord.py handles that work for us. It recognizes the command, takes the user's arguments, and passes them to our function.

So when someone types:

!choose left

discord.py knows that choose is the command, "left" is the argument, and that it should call our choose() function with that information.

Add a Casual Chat Command

Now let's make the bot capable of basic conversation.

We could connect it to a large language model API, but you don't actually need AI to learn how a chat command works. We'll start with a simple keyword-based response system.

First, we'll create a dictionary containing some keywords and possible responses:

chat_responses = {
    "hello": [
        "Hey! What's up?",
        "Hello! How's your day going?",
        "Hi! What are you working on?"
    ],
    "python": [
        "Python is a great language for beginners because its syntax is pretty readable.",
        "If you're learning Python, try building something instead of only watching tutorials."
    ],
    "discord": [
        "Discord bots are a fun way to practice Python because you get instant feedback.",
        "Once you understand commands and events, you can build some surprisingly complex bots."
    ]
}

Think of `chat_responses` as a small collection of things our bot knows how to talk about. Each key, such as `"python"` or `"discord"`, represents a keyword the bot can look for. The value associated with each key is a list of possible responses.

We use a list instead of a single response so the bot doesn't give exactly the same answer every time. Later, we'll randomly choose one of these responses.

Now let's create the actual `!chat` command:

```python
@bot.command()
async def chat(ctx, *, message: str):
    text = message.lower()

    for keyword, responses in chat_responses.items():
        if keyword in text:
            await ctx.send(random.choice(responses))
            return

    await ctx.send(
        "I'm still learning how to respond to that. "
        "Try talking to me about Python or Discord!"
    )

There are a few things happening here, so let's break it down.

First, this part:

@bot.command()
async def chat(ctx, *, message: str):

turns the chat() function into a Discord command. The * is important because it tells discord.py to treat everything after the command as one argument.

For example, if someone types:

!chat I want to learn Python

the entire phrase after !chat becomes the value of message:

message = "I want to learn Python"

Next, we have:

text = message.lower()

This converts the message to lowercase. That means Python, python, and PYTHON will all become python. Without this, our keyword check could miss a match simply because the user capitalized a word differently.

Now we get to the loop:

for keyword, responses in chat_responses.items():

.items() lets us go through both the keyword and its corresponding list of responses. During each loop, keyword contains something like "python", while responses contains the list of responses associated with it.

Then we check:

if keyword in text:

This asks whether the current keyword appears anywhere in the user's message.

If the user writes:

!chat I want to learn Python

the lowercase version becomes:

i want to learn python

Since "python" appears inside that text, the condition is true.

The bot can then choose a random response:

await ctx.send(random.choice(responses))

random.choice() picks one item from the response list, while ctx.send() sends that response back to the Discord channel.

Finally, we have:

return

This stops the function after a matching keyword is found. Without it, the loop would continue checking the other keywords even after the bot had already responded.

But what happens if none of the keywords match?

That's what this part handles:

await ctx.send(
    "I'm still learning how to respond to that. "
    "Try talking to me about Python or Discord!"
)

If the loop finishes without finding a keyword, the bot sends this fallback message instead.

For example:

!chat I like pizza

doesn't contain "hello", "python", or "discord", so the bot doesn't have a specific response to use.

This gives us a simple way for the bot to have conversations without needing an AI model.

Add a Mental-Wellness Support Feature

Now for the feature that needs a little more care.

Instead of calling this a "therapy command" internally, we'll call it:

!support

Quick additional disclaimer before we start...this is just a fun wellness script, not a real therapist!

Create:

support_responses = {
    "stress": [
        "That sounds like a lot to handle. Try breaking the situation into one small task at a time.",
        "When everything feels overwhelming, it can help to pause and focus on what needs attention right now."
    ],

    "school": [
        "School can pile up quickly. Consider choosing one assignment to work on first instead of trying to solve everything at once.",
        "If school stress is getting difficult to manage, talking with a trusted person can make things feel less like something you have to handle alone."
    ],

    "sad": [
        "I'm sorry you're having a difficult moment. Taking a short break, doing something calming, or talking with someone you trust may help.",
        "You don't have to solve everything immediately. Give yourself some time and consider reaching out to someone you trust."
    ]
}

Now create the command:

@bot.command()
async def support(ctx, *, message: str):
    text = message.lower()

    for keyword, responses in support_responses.items():
        if keyword in text:
            response = random.choice(responses)

            await ctx.send(
                f"{response}\n\n"
                "I'm a bot, not a therapist or medical professional. "
                "If you need personal support, consider talking with "
                "someone you trust."
            )
            return

    await ctx.send(
        "It sounds like something is bothering you. "
        "I can offer general wellness suggestions, but I'm not a therapist. "
        "If you need personal support, consider reaching out to someone you trust."
    )

Now someone can type:

!support I'm stressed about school

The bot sees the word:

school

and chooses one of the school-related responses.

This is deliberately simple.

For a real public bot, you'd want much more careful safety handling, testing, moderation, privacy protection, and escalation logic before allowing users to rely on it for sensitive situations.

Add a Help Command

A good bot should explain itself.

@bot.command()
async def commands_help(ctx):
    await ctx.send(
        "**Available commands:**\n"
        "`!hello` - Say hello\n"
        "`!story` - Start a new story\n"
        "`!choose left` - Choose the left path\n"
        "`!choose right` - Choose the right path\n"
        "`!chat <message>` - Have a casual conversation\n"
        "`!support <message>` - Get general wellness support"
    )

There's one small issue.

Discord's default help command is already called help.

So instead of:

async def help(ctx):

we've named ours:

commands_help

If you want the command itself to be called !help, you can write:

@bot.command(name="help")
async def commands_help(ctx):
    ...

That tells Discord:

Use !help for this function even though the Python function has another name.

Improve Error Handling

Bots shouldn't crash just because someone enters an invalid command.

Add:

@bot.event
async def on_command_error(ctx, error):
    if isinstance(error, commands.MissingRequiredArgument):
        await ctx.send(
            "You're missing something. Try `!help` to see how the command works."
        )

    elif isinstance(error, commands.CommandNotFound):
        return

    else:
        print(f"Error: {error}")

Now if someone types:

!chat

without giving the bot a message, it can respond with a useful explanation instead of dumping a confusing error into the conversation.

Put Everything Together

At this point, your bot.py can look like this:

import os
import random

import discord
from discord.ext import commands
from dotenv import load_dotenv


load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")

if not TOKEN:
    raise RuntimeError("DISCORD_TOKEN is not set.")


intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(
    command_prefix="!",
    intents=intents
)


story_locations = [
    "an abandoned library",
    "a mysterious island",
    "a futuristic city",
    "a hidden underground laboratory",
    "a forest that never appears on maps"
]

story_items = [
    "a glowing key",
    "an ancient notebook",
    "a strange compass",
    "a locked metal box",
    "a mysterious photograph"
]

story_events = [
    "You hear footsteps behind you.",
    "The lights suddenly turn off.",
    "A hidden door opens nearby.",
    "Your phone starts displaying a message from an unknown sender.",
    "You notice that the room has changed."
]


user_stories = {}


chat_responses = {
    "hello": [
        "Hey! What's up?",
        "Hello! How's your day going?",
        "Hi! What are you working on?"
    ],

    "python": [
        "Python is a great language for beginners because its syntax is pretty readable.",
        "If you're learning Python, try building something instead of only watching tutorials."
    ],

    "discord": [
        "Discord bots are a fun way to practice Python because you get instant feedback.",
        "Once you understand commands and events, you can build some surprisingly complex bots."
    ]
}


support_responses = {
    "stress": [
        "That sounds like a lot to handle. Try breaking the situation into one small task at a time.",
        "When everything feels overwhelming, it can help to pause and focus on what needs attention right now."
    ],

    "school": [
        "School can pile up quickly. Consider choosing one assignment to work on first instead of trying to solve everything at once.",
        "If school stress is getting difficult to manage, talking with a trusted person can make things feel less like something you have to handle alone."
    ],

    "sad": [
        "I'm sorry you're having a difficult moment. Taking a short break, doing something calming, or talking with someone you trust may help.",
        "You don't have to solve everything immediately. Give yourself some time and consider reaching out to someone you trust."
    ]
}


@bot.event
async def on_ready():
    print(f"Logged in as {bot.user}")


@bot.command()
async def hello(ctx):
    await ctx.send("Hello! I'm online.")


@bot.command()
async def story(ctx):
    user_id = ctx.author.id

    location = random.choice(story_locations)
    item = random.choice(story_items)
    event = random.choice(story_events)

    user_stories[user_id] = {
        "location": location,
        "item": item,
        "event": event
    }

    await ctx.send(
        f"You wake up in {location}.\n\n"
        f"Next to you is {item}.\n\n"
        f"{event}\n\n"
        "What do you do?"
    )


@bot.command()
async def choose(ctx, choice: str):
    user_id = ctx.author.id

    if user_id not in user_stories:
        await ctx.send(
            "You don't have an active story. Try `!story` first."
        )
        return

    choice = choice.lower()

    if choice == "left":
        response = (
            "You head left and discover a room filled with old maps. "
            "One of them has your name written on it."
        )

    elif choice == "right":
        response = (
            "You head right and find a staircase leading toward "
            "a strange blue light."
        )

    else:
        response = "Try choosing `left` or `right`."

    await ctx.send(response)


@bot.command()
async def chat(ctx, *, message: str):
    text = message.lower()

    for keyword, responses in chat_responses.items():
        if keyword in text:
            await ctx.send(random.choice(responses))
            return

    await ctx.send(
        "I'm still learning how to respond to that. "
        "Try talking to me about Python or Discord!"
    )


@bot.command()
async def support(ctx, *, message: str):
    text = message.lower()

    for keyword, responses in support_responses.items():
        if keyword in text:
            response = random.choice(responses)

            await ctx.send(
                f"{response}\n\n"
                "I'm a bot, not a therapist or medical professional. "
                "If you need personal support, consider talking with "
                "someone you trust."
            )
            return

    await ctx.send(
        "It sounds like something is bothering you. "
        "I can offer general wellness suggestions, but I'm not a therapist. "
        "If you need personal support, consider reaching out to someone you trust."
    )


@bot.command(name="help")
async def commands_help(ctx):
    await ctx.send(
        "**Available commands:**\n"
        "`!hello` - Say hello\n"
        "`!story` - Start a new story\n"
        "`!choose left` - Choose the left path\n"
        "`!choose right` - Choose the right path\n"
        "`!chat <message>` - Have a casual conversation\n"
        "`!support <message>` - Get general wellness support"
    )


@bot.event
async def on_command_error(ctx, error):
    if isinstance(error, commands.MissingRequiredArgument):
        await ctx.send(
            "You're missing something. Try `!help` to see how the command works."
        )

    elif isinstance(error, commands.CommandNotFound):
        return

    else:
        print(f"Error: {error}")


bot.run(TOKEN)

This is enough to create a surprisingly capable beginner Discord project.

But there's an important limitation.

Our Bot Doesn't Actually Remember Anything

There's one small problem with our bot so far: it doesn't actually remember anything after it shuts down.

Right now, we're storing our story information in a Python dictionary:

user_stories = {}

This works while the bot is running. But if you stop the program and start it again, the dictionary starts empty.

To fix this, we need somewhere to permanently store our data. That's where a database comes in.

For this project, we'll use SQLite. SQLite is a lightweight database that stores information in a file on your computer. Python already includes SQLite through the built-in sqlite3 module, so we don't need to install anything extra.

Create the Database

First, add this import near the top of bot.py:

import sqlite3

Then create a connection to a database file:

db = sqlite3.connect("bot.db")
cursor = db.cursor()

The first line creates a database file called bot.db if one doesn't already exist. If the file already exists, SQLite simply opens it.

The second line creates a cursor. You can think of the cursor as the part of our Python program that lets us send instructions to the database.

Now we need to create a table where we can store our users' story information:

cursor.execute("""
    CREATE TABLE IF NOT EXISTS user_stories (
        user_id INTEGER PRIMARY KEY,
        location TEXT,
        item TEXT,
        event TEXT
    )
""")

db.commit()

Let's break this down.

cursor.execute() tells SQLite to run the SQL command inside the parentheses.

The SQL command starts with:

CREATE TABLE IF NOT EXISTS user_stories

This tells SQLite to create a table called user_stories, but only if that table doesn't already exist.

Inside the parentheses, we define the information that each row can contain:

user_id INTEGER PRIMARY KEY,
location TEXT,
item TEXT,
event TEXT

user_id stores the Discord user's ID. We use it as the PRIMARY KEY, which means each user gets their own unique row.

location, item, and event are all pieces of information about the user's current story.

Finally:

db.commit()

saves the changes to the database.

At this point, your project folder should contain a new file called:

bot.db

You don't need to open or edit this file manually. SQLite will manage it for us.

Save a User's Story

Now let's actually put information into our database.

Suppose we have these variables:

user_id = ctx.author.id
location = "an abandoned castle"
item = "a mysterious key"
event = "a locked door"

We can save them using:

cursor.execute(
    """
    INSERT OR REPLACE INTO user_stories
    (user_id, location, item, event)
    VALUES (?, ?, ?, ?)
    """,
    (user_id, location, item, event)
)

db.commit()

The SQL statement tells SQLite to insert the information into the user_stories table.

The ? symbols are placeholders for the actual values. The values are provided separately here:

(user_id, location, item, event)

This is safer than manually inserting values directly into the SQL string.

INSERT OR REPLACE also means that if this user already has a saved story, their old story information can be replaced with the new information.

Get the Story Back

Saving information is only half of the job. We also need to be able to retrieve it.

We can search the database for a user's story like this:

cursor.execute(
    """
    SELECT location, item, event
    FROM user_stories
    WHERE user_id = ?
    """,
    (user_id,)
)

story = cursor.fetchone()

This time, we're using SELECT to ask SQLite for information.

The WHERE part is important:

WHERE user_id = ?

It tells SQLite to find the row belonging to this specific Discord user.

Then:

story = cursor.fetchone()

gets the first matching result.

If the user has a saved story, story will contain their information. If they don't, story will be None.

We can check for that:

if story:
    location, item, event = story

    await ctx.send(
        f"You're currently in {location}. "
        f"You have {item}, and you're facing {event}."
    )
else:
    await ctx.send("I don't have a saved story for you yet!")

Now the bot can retrieve information that was saved earlier, even after the Python program has been restarted.

Put It Into a Command

We can turn this into a simple command that lets users check their saved story:

@bot.command()
async def status(ctx):
    user_id = ctx.author.id

    cursor.execute(
        """
        SELECT location, item, event
        FROM user_stories
        WHERE user_id = ?
        """,
        (user_id,)
    )

    story = cursor.fetchone()

    if story:
        location, item, event = story

        await ctx.send(
            f"You're currently in {location}. "
            f"You have {item}, and you're facing {event}."
        )
    else:
        await ctx.send(
            "You don't have a saved story yet. "
            "Start one with `!story`!"
        )

Now a user can type:

!status

and the bot can look up their story from the database.

This is a big improvement over our original dictionary. A dictionary only remembers information while the Python program is running. SQLite lets us save that information so it can still be there when the bot starts again.

For a larger bot, you could eventually store things like user preferences, story progress, inventory, conversation history, or other data. But for now, this simple database is enough to give our bot some real memory.

Adding Real AI Chat

Before we connect our bot to an AI model, let's quickly talk about Hugging Face.

If you've never used it before, Hugging Face is a platform where developers can find, share, and use machine learning models and datasets. Think of it as a huge community and library for AI tools.

Hugging Face also provides tools that let Python programs communicate with these models without having to build and train an AI model from scratch.

For our bot, we'll use Hugging Face's Inference Providers to send a user's message to a supported language model and receive its response.

We won't be training an AI model ourselves. Instead, we'll use an existing model and connect it to our Discord bot through Python.

Now that we know what Hugging Face is, let's connect it to our bot.

Install the Hugging Face Library

First, install huggingface_hub:

pip install -U huggingface_hub

We already installed python-dotenv, so we can use the same .env file from earlier to keep our Hugging Face token out of the source code.

Add your Hugging Face token to .env:

DISCORD_TOKEN=YOUR_BOT_TOKEN_HERE
HF_TOKEN=YOUR_HUGGING_FACE_TOKEN_HERE

Replace YOUR_HUGGING_FACE_TOKEN_HERE with your actual Hugging Face access token.

Just like your Discord bot token, don't share this token or upload it to GitHub.

Create the Hugging Face Client

Now add this import near the top of bot.py:

from huggingface_hub import InferenceClient

Then load the token:

HF_TOKEN = os.getenv("HF_TOKEN")

if not HF_TOKEN:
    raise RuntimeError("HF_TOKEN is not set.")

The first line gets the token from our environment variables. The if statement checks whether the token actually exists. If it doesn't, Python stops and gives us a useful error instead of letting the program fail later in a confusing way.

Now create the Hugging Face client:

client = InferenceClient(
    api_key=HF_TOKEN
)

The InferenceClient is what our Python program will use to communicate with Hugging Face's inference service.

Connect the AI Model to the Bot

Now we can replace our previous keyword-based !chat command with one that sends the user's message to a language model.

@bot.command()
async def chat(ctx, *, message: str):
    try:
        response = client.chat_completion(
            model="YOUR_SUPPORTED_MODEL_ID",
            messages=[
                {
                    "role": "system",
                    "content": (
                        "You are a friendly Discord bot. "
                        "Keep responses helpful, concise, and conversational."
                    )
                },
                {
                    "role": "user",
                    "content": message
                }
            ],
            max_tokens=200
        )

        answer = response.choices[0].message.content

        await ctx.send(answer)

    except Exception as error:
        print(f"AI error: {error}")
        await ctx.send(
            "I couldn't generate a response right now. "
            "Please try again later."
        )

There's quite a bit happening here, so let's walk through it.

We start with the same command structure we've already used:

@bot.command()
async def chat(ctx, *, message: str):

This creates our !chat command and stores everything the user types after it in message.

For example:

!chat What is Python?

gives us:

message = "What is Python?"

Next, we use:

try:

This tells Python that we're about to run code that could potentially fail. Since we're communicating with an external service, things like an unavailable model, an invalid token, or a temporary connection problem can happen.

Now we call:

response = client.chat_completion(

This sends a chat-completion request to the model through Hugging Face. The messages parameter contains the conversation we want the model to respond to.

The first message has the role "system":

{
    "role": "system",
    "content": (
        "You are a friendly Discord bot. "
        "Keep responses helpful, concise, and conversational."
    )
}

The system message gives the model instructions about how it should respond.

Then we provide the user's actual message:

{
    "role": "user",
    "content": message
}

If the user typed:

!chat What is Python?

then message contains:

What is Python?

So the model receives that as the user's input.

We also have:

max_tokens=200

This limits how much text the model can generate for one response. Keeping responses relatively short works well for Discord because huge blocks of text aren't always very pleasant to read in a chat channel.

You also need to replace:

model="YOUR_SUPPORTED_MODEL_ID"

with the ID of a model currently available through the Hugging Face Inference Providers you are using. Hugging Face's documentation shows that InferenceClient can use a model ID hosted on the Hugging Face Hub for chat completion.

Once the request is complete, we need to get the actual text from the response:

answer = response.choices[0].message.content

The response contains information about the model's output. choices[0] gets the first generated response, and .message.content gives us the actual text.

Then we send it to Discord:

await ctx.send(answer)

So the whole process looks like this:

User types !chat
        ↓
Discord sends the command to our bot
        ↓
Python gets the user's message
        ↓
Hugging Face receives the message
        ↓
The AI model generates a response
        ↓
Python gets the generated text
        ↓
The bot sends it back to Discord

Handle AI Errors

The last part of our command is:

except Exception as error:
    print(f"AI error: {error}")
    await ctx.send(
        "I couldn't generate a response right now. "
        "Please try again later."
    )

If something goes wrong inside the try block, Python jumps to the except block instead of crashing the entire bot.

The error is printed in the terminal so you can investigate what happened:

print(f"AI error: {error}")

Meanwhile, the Discord user gets a simple message:

I couldn't generate a response right now. Please try again later.

This is much better than letting an API error take down the whole bot.

At this point, you have a real AI-powered !chat command. You can type something like:

!chat Tell me an interesting fact about space.

and the model can generate a response instead of choosing from a small list of pre-written messages.

One thing to remember is that this bot is sending user messages to an external AI service. Don't automatically send private or sensitive conversations to an AI provider. If you make this bot available to other people, be clear about what information it processes and avoid storing or sending more data than the bot actually needs.

You can also combine this AI system with the SQLite database from earlier. For example, you could save a limited amount of conversation history and send relevant previous messages along with a new message. That would allow the bot to keep some context between messages instead of treating every message as a completely new conversation.

How Do We Keep the Bot Online?

Here's where the phrase "online forever" needs a little clarification.

There are two different situations.

Option 1: Run It on Your Computer

When you run:

python bot.py

the bot stays online while that program is running.

Close the terminal?

Bot goes offline.

Turn off the computer?

Bot goes offline.

Lose internet?

Bot goes offline.

This is perfect for development but it's not a 24/7 production setup.

Option 2: Host It on a Server

For a bot that should stay online while your computer is off, you need a computer somewhere that stays available.

That computer can be a cloud server.

You upload your project, install the dependencies, add your environment variables, and start:

python bot.py

Now the cloud machine runs the program instead of your laptop.

Services designed for continuously running workloads can be used for this kind of application. For example, Render currently provides a Background Worker service type for continuously running processes that don't need to receive incoming web traffic.

But you should check the provider's current pricing and service limitations before deploying. Free hosting tiers aren't necessarily designed for an always-on Discord bot, and a "free forever" 24/7 setup isn't something you should assume a hosting platform will provide.

What "Forever" Actually Means

There isn't really a magical:

ONLINE_FOREVER = True

setting.

A bot can stay online continuously only as long as the computer or server running it continues operating.

Even a professionally hosted bot can go offline because of:

• Server maintenance

• Deployments

• Bugs

• Network problems

• Provider outages

• Invalid credentials

• API changes

• Billing or account issues

So the realistic goal is to keep the bot running automatically and restart it when something goes wrong.

That is what production hosting is designed to help with.

If your provider supports automatic restarts, enable them.

You can also make your Python code fail clearly when an important environment variable is missing:

if not TOKEN:
    raise RuntimeError("DISCORD_TOKEN is not set.")

A clear error is much easier to debug than a mysterious bot that simply doesn't appear online.

Don't Try to "Keep It Awake" With Random Tricks

You may find tutorials suggesting that you deploy a web server and repeatedly ping it from another service to prevent a free hosting instance from sleeping.

Be careful with that approach.

Hosting providers change their free-tier rules, and attempting to work around those limits can violate their terms.

If you need an actually persistent bot, use a hosting option that explicitly supports the workload.

For example, a background worker is designed for continuously running processes. That's much cleaner than trying to convince a web service that your Discord bot is secretly a website.

Additional Features and Where to Go Next

Now that you have a working Discord bot, there are plenty of directions you can take the project next.

You could turn the storytelling system into a more complete game by adding an inventory, multiple chapters, puzzles, or different endings. You could also replace text-based commands with Discord slash commands and buttons to make the bot easier to interact with.

If you're interested in AI, you could expand the chat system by giving the bot different personalities, adding carefully limited conversation context, or using AI to generate parts of the stories.

You could also add moderation features, daily story prompts, or other commands that fit the kind of Discord community you're building.

These are ideas for extending the project rather than features we'll build step by step in this tutorial. The important thing is that you now have the foundation to experiment with them yourself.

Start with one small feature, figure out how it works, and build from there. You don't need to turn the bot into a massive project all at once.

The more you experiment with the code, the more you'll start seeing how Python, Discord, databases, and AI can work together in a real application.

Test Everything Locally First

Before deploying, test:

!hello
!story
!choose left
!choose right
!chat hello
!chat I want to learn Python
!support I'm stressed
!help

Then test weird inputs:

!choose banana
!chat
!support
!unknowncommand

You want to discover bugs while you're sitting in front of your computer, not three days later when someone tells you:

"Your bot has been broken since Tuesday."

Deploying the Bot

First, make sure your project contains:

discord-story-bot/
│
├── bot.py
├── requirements.txt
├── .gitignore
└── .python-version

A .python-version file can contain something like:

3.13

Using a version file makes your deployment environment more predictable. Render currently supports specifying a Python version through .python-version or an environment variable.

Your requirements.txt should contain your dependencies.

For example:

discord.py
python-dotenv

For deployment, you generally don't need the local .env file.

Instead, add:

DISCORD_TOKEN

as an environment variable in your hosting provider's dashboard.

That way the secret isn't stored inside your repository.

The Start Command

Your deployment service needs to know what to run.

For this project, the start command is:

python bot.py

The important thing is that the process doesn't immediately exit.

A Discord bot stays alive because bot.run(TOKEN) starts the Discord connection and keeps the program running.

If your hosting service supports background workers, that's a natural fit for a bot like this because the bot doesn't need to serve normal HTTP requests. Render specifically describes background workers as continuously running services that don't receive incoming network traffic.

Remember: Keep Your Secrets Secret

This is worth repeating because it causes a lot of beginner projects to get compromised.

Never commit this:

bot.run("YOUR_REAL_TOKEN")

Never upload:

.env

Never paste your actual token into a public GitHub issue.

If a token accidentally becomes public, treat it as compromised and regenerate it.

Environment variables are your friend.

What You Learned

You've now built a Discord bot that demonstrates several real programming concepts.

You learned how to:

• Create a Discord application

• Connect Python to Discord

• Use discord.py

• Configure Gateway Intents

• Create commands

• Use asynchronous functions

• Read command arguments

• Generate random stories

• Store temporary user state

• Create a basic chat system

• Create a mental-wellness support feature

• Handle command errors

• Keep secrets out of source code

• Prepare a project for deployment

• Think about persistent hosting

And underneath all those features, the architecture is still surprisingly simple:

User sends command
        ↓
Discord receives message
        ↓
discord.py receives event
        ↓
Python function runs
        ↓
Bot generates response
        ↓
Discord displays response

You don't need thousands of lines of code to get started.

You need a clear idea, a few Python concepts, and the willingness to keep debugging when something inevitably breaks.

Final Thoughts

The coolest part of this project isn't really the Discord bot. It's what the project teaches you.

And once you understand the pieces, you can reuse the same ideas in countless projects.

A Discord bot can become a game, which could become a web application, which could also become a larger software project.

And suddenly you're not just learning Python syntax anymore. You're learning how software actually gets built, one command at a time.

Happy coding!

This absence of direction makes the journey significantly harder. Faced with an overwhelming abundance of online resources, many beginners become confused about where to start and often attempt to learn everything at once.

This is where the struggle with knowledge retention begins.

Not because they lack intelligence or effort, but because they're learning in a way that contradicts how the human brain actually works.

They dive into tutorials and courses without understanding the mechanism of the brain – that is, how the brain processes, stores, and retrieves information. As a result, much of what they learn simply doesn’t stick.

How the Brain Processes Information

So what's the connection between the brain and learning how to code, you might ponder?

The connection is direct and unavoidable.

Coding isn't learned through willpower or motivation — though both matter — or by spending countless hours watching tutorials.

It's learned through the brain’s ability to process, store, and retrieve information.

Every variable, function, data structure, or debugging pattern must pass through the brain’s cognitive systems before it becomes usable knowledge.

If your learning process doesn't align with how the brain naturally acquires and organises information, your retention will collapse, no matter how determined you are.

Now imagine you’re trying to fill a bucket with water. You keep pouring and pouring, but the bucket has tiny holes at the bottom. No matter how much effort you put in, the water keeps leaking out. You might blame yourself for not pouring fast enough, or you might try switching to a bigger jug, but the real problem isn’t your effort — it’s the bucket.

The water is the information you’re trying to learn.

The bucket is your brain’s memory system.

The holes in the bucket are the natural forgetting mechanisms of the brain: cognitive overload, limited working memory, and other constraints that make retention difficult.

If you don’t understand these mechanisms, you can pour in as much information as you want, but most of it will leak out.

Not because you’re incapable, but because you’re learning in a way that contradicts how the brain actually retains knowledge.

The Role of Academic Learning Theories

Since learning ultimately takes place in the brain, an important question is: How does the human brain acquire, organize, and apply knowledge and why does the typical self‑taught learning process clash with these principles?

This is where academic learning theories become indispensable. These frameworks explain how the brain actually acquires, retains, and applies complex information and they offer a scientific roadmap for learning more effectively. Without understanding these principles, self‑taught developers unintentionally work against the brain’s natural architecture.

The purpose of this article is to unpack these essential learning theories and apply them directly to the beginner self‑taught developer’s journey.

By understanding how the brain processes information, beginners can structure their learning more intentionally, retain knowledge more reliably, and move toward becoming competent developers with far greater confidence and clarity.

Table of Contents

• Cognitive Load Theory (CLT)

  • Working Memory

  • Miller's Law

  • Chunking

  • Long-term memory

  • Schema

  • Intrinsic Load: The Natural Difficulty of the Task

  • Extraneous Load: The Mental Noise

  • Germane Load: The Construction Work

• Ebbinghaus Forgetting Curve.

• How the Theory of Spaced Repetition Works

• Theory of Deliberate Practice

• What is Bloom's Taxonomy?

  • Focused Mode vs Diffuse Mode

• Conclusion

• References

Cognitive Load Theory (CLT)

Learning a new concept often requires mental effort by the brain to process newly acquired information. This effort exerted by the brain is known as cognitive load, a term coined by Australian educational psychologist John Sweller in 1988 during his study on how the brain acquires and retains information (Sweller, 1988).

Since then, his work has been expanded upon by other researchers. Notably, Dylan Wiliam famously tweeted in 2017 that Cognitive Load Theory (CLT) is "the single most important thing for teachers to know" (Dylan William, 2017).

You might wonder again: What does this have to do with me? As a beginner self‑taught developer, the answer is simple: you're both the teacher and the student.

So this is the most important theory you should know. In this self-tutoring journey, you're tasked with designing your own curriculum, choosing your own resources, pace your own learning, and evaluating your own progress.

Without understanding how cognitive load affects your ability to absorb and retain information, you may unintentionally overload your brain and sabotage your own learning.

Before we get into the nitty-gritty of CLT, there are important concepts masterminded by David Geary that you'll need to grasp to sufficiently understand this concept : “that which can be learnt” (biologically primary knowledge), “that which can be taught”(biologically secondary knowledge) (Geary, 2007, 2008).

According Geary (2007, 2008), "biologically primary knowledge" consists of "instinctual" skills that the brain is evolved to pick up naturally without formal schooling.

Examples include learning a first language, recognizing faces, or basic social navigation.

"Biologically secondary knowledge", on the other hand, consists of cultural and technical skills, like reading and writing, that are necessary for society but don't come naturally to the brain.

This is because we aren't "wired" to pick these up automatically. Instead, they require formal instruction and schools to pass them down.

Therefore, coding is a prime example of biologically secondary knowledge. The human brain is remarkably plastic, but it didn't evolve to interpret syntax, manage memory allocation, or debug logical loops.

These are cultural inventions, not natural instincts. Unlike learning to walk or speak your native language (which are biologically primary skills) you can't learn to code simply by “being around” computers.

Recognising that the human brain is not instinctively prepared for coding allows you to change your strategy. Once you accept that coding concepts are not “natural,” you can finally approach them with the structured, deliberate effort they require.

The second set of concepts beginner self-taught developers should know and understand are working memory, Miller's Laws, chunking, long-term memory, and schemas.

Working Memory

Working memory is where thinking happens. It's the active mental workspace where you hold information while you process it. When you encounter concepts like syntax, loops, functions, or an if/elseif statement for the first time, all of that information sits inside your working memory. The problem is that working memory is extremely limited and fragile.

When you first learn to code, your working memory functions like a small mental desk where only a few items can be placed at once.

Imagine trying to assemble a piece of IKEA furniture on a tiny coffee table. If you spread out the instruction manual, the screws, the wooden panels, and the tools all at the same time, the table becomes cluttered instantly. You start losing track of which part goes where, not because you’re incapable, but because the surface you’re working on is too small to hold everything at once.

Working memory behaves the same way. When you’re learning new concepts – like arrays, loops, functions, or error handling – each idea takes up space on that mental desk. If you then overload it, the desk becomes overcrowded.

Once it exceeds its capacity, things begin to fall off, and your ability to retain collapses.

It’s not a lack of intelligence. It’s simply the natural limit of working memory.

Now this collapse happens because you went against the threshold your working memory can hold. This is backed up by research that shows that working memory can typically process only 5–9 pieces of information at any given time (Miller, 1956). This is known as Miller’s Law.

Miller's Law

In 1956, George Miller found that the average human can hold about seven items (plus or minus two) in working memory at once, even some recent research has stated the number is even lower about four item (Nelson Cowan, 2001).

So imagine you encounter a tutorial that introduces the following concepts all at the same time: a Route, a Controller, a Model, a Migration, a View, a Request, Helper files, Jobs and Queues, Middleware, Roles and Permissions, and a Service Provider. If you attempt to hold all of these in your mind simultaneously, you'll inevitably hit Miller’s Wall, as your working memory becomes overloaded, and you'll likely forget the first concept long before you reach the last.

So how do you handle complex tasks if the brain can only juggle 4–9 items at once?

You use chunking — the process of grouping small pieces of information into a single, meaningful unit.

Chunking

Chunking is the brain’s strategy for compressing complexity. Instead of forcing working memory to hold a dozen unrelated items, you reorganise them into a few coherent structures. This reduces cognitive load, prevents overload, and allows you to work with far more information than your raw working‑memory limits would normally allow.

Let's consider an example:

A beginner learning Laravel might see Route, Controller, Model, Migration, and View as five separate, overwhelming items. To a beginner, each one feels like a distinct cognitive burden. But an experienced developer doesn't treat them as isolated concepts. Instead, they're understood as a single meaningful unit: the MVC pattern. Instead of holding five items in working memory, the expert holds one.

This raises an important question: how does a beginner know that these five elements belong together when they have only just encountered them?

It's crucial to emphasise that chunking isn't automatic. It depends on recognising meaningful relationships between concepts, and beginners typically lack the prior knowledge needed to perceive those relationships early on.

But as learners repeatedly encounter the same sequence during the learning process, they begin to notice consistent patterns. Over time, the brain’s natural tendency to seek structure enables them to identify which components reliably operate together, allowing these elements to gradually fuse into a single, meaningful chunk.

For example, when I first followed a Laravel e-commerce tutorial, I noticed that for every new resource the tutor created – Payment, Cart, KYC, and Contact – the same pattern was repeated: a Controller, a Model, and a View were always created together.

After encountering this sequence several times, it became clear that these components consistently belonged together as a set. Over time, I began to perceive the Controller, Model, and View not as separate elements, but as a single, integrated unit.

So beginners may not be able to chunk effectively on day one because they lack the prior knowledge needed to recognise what belongs together. But with time, and repeated encounters across different contexts, these individual pieces fuse into stable mental units stored in long‑term memory.

What feels overwhelming at first eventually becomes effortless, not because the task became simpler, but because your internal representation became more organised.

This is the power of chunking: it transforms scattered pieces of information into organised units that fit comfortably within the limits of working memory.

Without chunking, beginners drown in details. With chunking, they gain the cognitive space needed to understand, retain, and apply what they learn.

Long-term memory

Unlike working memory, long‑term memory has virtually infinite capacity. The goal of all study is to move information from the cramped working memory into the vast long‑term memory.

Here is the real secret: you don’t learn in working memory – you only process there.

True learning is the permanent change that happens in long‑term memory.

Schema

Once stored in long-term memory, information becomes part of a schema — a mental map or filing system that organizes related ideas.

For example, when you finally learn that Laravel is an MVC framework, you aren’t just memorizing three letters. You're building a schema that tells your brain: Models handle data, Views handle presentation, and Controllers handle logic.

Once a schema is built, it can be pulled into working memory as a single chunk, effectively bypassing Miller’s Law.

This is how experts think effortlessly while beginners feel overwhelmed.

And this is why Garnett (2020) argues that "being competent or lacking competence in something depends entirely on how secure the retrieval of knowledge held in the schema is".

Now that the foundations of working memory, long‑term memory, schemas, and chunking are clear, we can turn to another set of concepts every self‑taught developer must understand: intrinsic load, extraneous load, and germane load. These three components make up the full structure of Cognitive Load Theory, and they determine whether learning feels manageable or overwhelming.

Intrinsic Load: The Natural Difficulty of the Task

Intrinsic load refers to the inherent complexity of the material itself. Some concepts are simply harder than others because they contain more interacting elements that must be processed at the same time.

In Laravel, understanding a simple Route has low intrinsic load.

But concepts like Dependency Injection or Polymorphic Relationships have high intrinsic load because they involve multiple layers of abstraction and interdependent ideas.

You can't change the intrinsic load of a concept, but you can manage it by breaking the idea into smaller, more digestible sub‑tasks. This is why good teaching — and good self‑teaching — always begins with simplification and sequencing.

Simplification means stripping a concept down to its essential parts so the learner isn't overwhelmed by unnecessary detail.

Sequencing means introducing parts in a logical order, where each step builds on the previous one. This helps reduce unnecessary cognitive load and allows learners to devote more mental effort (germane load) to building schemas.

It’s like meeting someone new, and they tell you their name and it happens to be your mother’s name. Instantly, your brain forms a connection. You associate this new person’s name with the strong, deeply stored memory of your mother.

Because that schema already exists in your long-term memory, the new information “attaches” to it. Later, when you try to recall the name, you don’t struggle, you simply think of your mother, and the name comes back easily.

While many believe self‑taught developers struggle because they lack immediate, reliable, personal guidance, there's actually a hidden advantage in this predicament. When a teacher explains a concept, even if they try their best to “chunk” the information, they can't truly know the student’s internal limits — how much intrinsic load the learner can handle, how quickly they can process new ideas, or how much prior knowledge they can activate.

This is where self‑taught developer quietly shines. Because you are both the teacher and the student, you know your own cognitive limits better than anyone else. You can slow down when something feels heavy, pause when working memory is overloaded, and chunk information in a way that perfectly matches your personal capacity.

You can simplify a concept to its bare essentials and sequence it at a pace that aligns with your own understanding.

Extraneous Load: The Mental Noise

Extraneous load is the enemy of the self‑taught developer. It's the mental effort wasted on tasks that don't contribute to actual learning. This is where a self-taught developer's strength must truly shine.

A teacher in a classroom is responsible for removing any distractions that might derail a child or slow down their assimilation of knowledge. As a self-taught developer, that responsibility falls entirely on you. You must identify these distractions and eliminate them.

As a self-taught developer myself, I use specific strategies to ensure I stay focused. Before starting any course, I spend time reading the comment section to see what others have experienced. If I see complaints about low audio quality, unclear explanations, or tutorials that move too fast, I immediately abandon that course and look for one with better reviews.

Anything that might derail my progress must be removed. If you spend half of your mental energy trying to figure out all of these, you only have the remaining half available for understanding the logic of the code. And remember: when learning new concepts, we use working memory, which is fragile.

As your own “inner teacher,” you must eliminate this noise so your limited working memory can focus entirely on the material that matters.

Germane Load: The Construction Work

Germane load is the productive mental effort used to build and refine schemas — the mental structures that make future learning easier.

This is the “Aha!” moment when new information connects meaningfully to what you already know.

For example, germane load appears when you realise that a Database Migration is essentially a version‑control system for your table structure.

That insight is schema construction in action.

Teachers are often advised to help manage a child's germane load. One way they do this is by connecting the new idea being taught to an existing concept.

By doing this, they help the student build schemas: mental frameworks that organise and interpret information.

For a self-taught developer, this means instead of memorizing a new syntax in isolation, you look for a 'hook' in something you already understand.

For example, if you already know how a physical filing cabinet works, understanding Arrays or Objects in code becomes much easier.

You aren't learning from scratch – you're simply "plugging" new data into an old socket. This reduces the mental strain and makes the new knowledge stick permanently.

But this can only happen when intrinsic load is properly managed and extraneous load is removed.

It's important to note that, unlike intrinsic and extraneous load, germane load isn't an independent type of cognitive load.

Instead, it represents the portion of your working memory that remains available to handle the element interactivity associated with intrinsic load.

In other words, germane load is the mental energy you have left for learning once the unnecessary noise is stripped away.

Understanding cognitive load explains why learning can feel overwhelming in the moment, but it doesn't explain why knowledge fades after the moment has passed. For that, we turn to another foundational principle in learning science: the Ebbinghaus Forgetting Curve.

Ebbinghaus Forgetting Curve

If you remember the bucket analogy, this curve represents one of the holes at the bottom — the brain’s natural tendency to let information leak away unless it's reinforced.

In the late 19th century, Hermann Ebbinghaus discovered that human memory follows a predictable pattern of decline. After learning something new, we forget most of it astonishingly quickly — often within hours — unless the information is revisited. The forgetting curve shows that memory retention drops sharply at first and then continues to decline more slowly over time.

Studies based on Ebbinghaus’ forgetting curve found that without a conscious effort to retain newly acquired information, we lose approximately 50% of new information within 24 hours, and up to 90% within a week (Clearwater, 2024).

In other words, the brain is designed to discard information that isn't reinforced.

For self‑taught developers, this has profound implications.

You may understand a Laravel controller today, spatial roles and permission concepts, and so on – but if you don't revisit it, practice it, or apply it within the next few hours, your brain will naturally let it fade.

This is not a sign of weakness or lack of talent. It's simply how human brain works.

The forgetting curve also explains why tutorials feel deceptively easy the moment you're going through them.

While watching, everything seems clear — but a week later, the same concepts feel unfamiliar.

The knowledge never made it into long‑term memory because you didn't revisit, practice, or connect it to existing schemas.

Since the human brain is designed to forget anything that isn't repeated, repetition becomes the signal that tells the brain, “This matters — keep it.”

This is why, when you meet someone for the first time and they tell you their name, you'll almost certainly forget it unless you consciously repeat it to yourself several times. If you don’t reinforce it, you end up asking — often with embarrassment — “Sorry, what was your name again?”

The same principle applies to learning code: without deliberate repetition, the brain simply lets the information fade. However, with a technique called spaced repetition, retention is significantly improved .

How the Theory of Spaced Repetition Works

Spaced repetition is a learning technique grounded in cognitive psychology that involves reviewing information at increasingly spaced intervals to strengthen long‑term memory retention.

It's based on the principle that memory decays predictably over time — as demonstrated by the Ebbinghaus Forgetting Curve — and that strategically timed reviews or repetition interrupt this decay, making the memory more durable with each repetition.

This idea is what gave birth to Anki-Flash cards.

Imagine you're trying to memorise the time complexity of different algorithms.

This is a classic "dry" academic topic that's easy to forget.

To understand why spaced repetition is so powerful, consider a familiar scenario. You spend Sunday night staring at a chart of Big‑O complexities for four hours. By Monday’s review, you can recall most of them. By Friday, only a few remain. Two weeks later, the entire chart has vanished from memory.

Spaced repetition reverses this process by reviewing information at the precise moment it's about to be forgotten. Instead of cramming Big‑O notation in a single session, you revisit it across expanding intervals:

1. Day 1 (Initial Learning): You study the Big‑O chart and understand each complexity class.

2. Day 2 (First Review): You test yourself. If you recall an item correctly, you schedule the next review three days later. If you miss it, you review it again the following day.

3. Day 5 (Second Review): You encounter the material again. Because you still remember it, the interval expands to ten days.

4. Day 15 (Third Review): Your memory has begun to fade, but the moment you see the prompt, the concept resurfaces. This slight struggle to retrieve the information is precisely what strengthens long‑term retention.

5. Day 45 (Fourth Review): By now, the memory is deeply consolidated. Concepts like O(log⁡n) feel as natural and accessible as your own phone number.

Through this process, spaced repetition transforms fragile, short‑term awareness into durable, long‑term knowledge. Each review interrupts the forgetting curve, reinforces the schema, and reduces the cognitive load required to recall the concept in the future.

For self-taught developers, spaced repetition can take many forms. You might rewrite code from memory, re‑implement a feature days later, build small variations of the same concept, or return to the concept after working on different tasks.

Every review strengthens the schema and reduces the cognitive load required to recall it. Over time, what once felt complex becomes automatic — not because the concept changed, but because your brain reorganised it into a stable, efficient structure.

As you can see, learning isn't a single event but a cycle of exposure, forgetting, and reinforcement.

Mastery comes not from seeing something once, but from returning to it until it becomes part of your cognitive architecture.

But we must be careful with repetition. Doing the same thing over and over again doesn't guarantee improvement. In fact, mindless repetition can trap you at the same level indefinitely.

This is where the theory of deliberate practice becomes essential, as it emphasises increasing the level of challenge, focusing on specific weaknesses, and actively seeking feedback so that each repetition leads to measurable improvement rather than just familiarity.

Theory of Deliberate Practice

Developed by psychologist K. Anders Ericsson, it argues that expertise is not the result of talent but of high‑quality, intentional practice (Ericsson, 1993). This type of practice is fundamentally different from simply doing something repeatedly.

He coined the term "deliberate practice" while researching how people become experts. Studying experts from several different fields, he dismantled the myth that expert performers have unusual innate talents.

Instead, he discovered that experts attain their high performance through how they practice: it's a deliberate effort to become an expert. This effort is characterized by breaking down required skills into smaller parts and practicing these parts repeatedly.

According to Anders Ericsson, Deliberate Practice requires:

1. Clear goals

2. Immediate feedback

3. Tasks that stretch your ability just beyond your comfort zone

4. Full concentration and effort

The main tenet of Deliberate Practice is that tasks must stretch your ability just beyond your comfort zone. This is paramount to the advancement of learning.

Imagine a child being taught 1+1 every day. That child will never grow beyond basic arithmetic. Anders Ericsson calls this "Arrested Development" (Ericsson, Nandagopal and Roring, 2005). For that child to grow to become a mathematician, their knowledge must be stretched.

The takeaway for developers is a play on the DRY principle (Don’t Repeat Yourself): If you are only repeating what you already know without stretching yourself, you aren't growing. This "stretch" is the extra edge that Deliberate Practice adds to Spaced Repetition.

Building a simple to-do list, a calculator, or a weather app over and over again won't take you anywhere. You already know how to do those.

To truly grow, you must stretch yourself. Instead, try a project that integrates new ideas, like building a mini-app where the weather data affects your to-do list. For example, if the API shows it's raining, the app automatically hides outdoor tasks and calculates the time you'll save or the indoor tasks you should prioritize instead.

This forces you to handle complex logic and state management, moving you beyond simple repetition into true mastery.

This ability to create brings me to the last theory: Bloom's Taxonomy.

What is Bloom's Taxonomy?

Bloom’s Taxonomy provides a hierarchy of cognitive skills that learners move through as they develop mastery. It begins with the simplest tasks and progresses toward the most complex:

1. Remember – recalling facts or syntax

2. Understand – explaining concepts in your own words

3. Apply – using knowledge in real situations

4. Analyze – breaking problems into parts

5. Evaluate – judging solutions or comparing approaches

6. Create – building original systems or applications

Most self‑taught developers get stuck in the first two levels. They memorize syntax and understand examples, but they struggle to apply, analyze, or create.

This isn't because they lack ability. Rather, it's because they haven't been taught that learning must progress through these stages.

Bloom’s Taxonomy gives structure to the learning journey.

It reminds self-taught developers that mastery isn't achieved by watching tutorials but by climbing the ladder from remembering → understanding → applying → analyzing → evaluating → creating (with an emphasis on Creation).

Creation is one of the most difficult yet most transformative experiences in your journey as a developer. It forces you to think abstractly, confront ambiguity, and notice dimensions of a problem that tutorials rarely reveal.

When you build something real, the neatness of the theory in your head collapses, and you begin to see its true complexity. You must then devise strategies to navigate these challenges, and through this process, you learn.

And as with anything worthwhile, the process isn't smooth. You'll encounter bugs — not just one or two, but hundreds. Yet this is precisely how real knowledge is built. Every bug you solve becomes a permanent entry in your long‑term memory.

The next time you see that error, you won’t panic. Instead, you’ll recognise it instantly and know exactly where it’s coming from and how to fix it.

Some self‑taught developers encounter a few bugs and never return to their projects again, concluding that “coding isn’t for me.”

After trying several fixes and seeing no progress, they abandon the work and look for something else. But this is the wrong conclusion. The problem is rarely a lack of talent — it's a misunderstanding of how the brain behaves under cognitive strain.

Focused Mode vs Diffuse Mode

When you spend a long time wrestling with a bug, you may be experiencing mental fixation or functional fixedness.

This is when your brain becomes locked into a single line of reasoning, repeating the same logic path over and over because it feels like the right direction. The longer you stare at the problem, the deeper the cognitive rut becomes. You develop tunnel vision, making it almost impossible to see alternative solutions.

This is where understanding how the brain operates becomes essential.

According to Oakley (2014), the brain works in two primary modes:

1. Focused Mode: Ideal for executing a known formula or following a clear procedure, terrible for discovering a new approach or breaking out of a mental rut.

2. Diffuse Mode: This is activated when you step away — walking, showering, relaxing, or sleeping.

In this second mode, the brain enters a “big‑picture” state where neural connections stretch across different regions.

The background processes continue working on the problem without the restrictive tunnel vision of conscious focus.

This phenomenon is known as incubation.

This is why solutions often appear when you’re not actively thinking about the problem. You step away, and suddenly the answer emerges, not because you stopped working, but because a different part of your brain started working for you.

The reality is that many developers never allow for incubation. While you step away from the problem, your brain performs subconscious synthesis: it clears out the noise (Extraneous Load) and lets the core logic (Germane Load) settle. When you return, the “wrong” paths you were obsessing over have faded, and the correct path which was there all along often finally becomes visible.

This is why developers must deliberately allow for incubation. We can take some lessons from great minds of the past:

Henri Poincaré famously struggled with Fuchsian functions for weeks. It was only during a geological excursion when he had completely forgotten about the mathematics that the solution appeared with “perfect certainty” the moment he stepped onto an omnibus. His breakthrough did not come from more effort, but from stepping away long enough for diffuse mode to take over.

Friedrich August Kekulé experienced something similar after years of wondering why benzene’s carbon atoms didn't fit a linear structure.

If some of the greatest minds in history stepped away from their problems and found solutions in diffuse mode, why should developers treat themselves any differently?

Now that you're familiar with some key learning strategies – Cognitive Load Theory, Spaced Repetition, and Bloom's Taxonomy – creating or building a project from the ground up should be your next task. It will help you curate, retrieve, organise, and seal in all that diverse knowledge you've gathered as a self-taught developer.

Conclusion

In this article, we explored why the human brain isn't instinctively wired to understand programming. Coding is a biologically secondary skill, which means it doesn't develop naturally through immersion but requires explicit instruction, structure, and patience.

We also talked about the limits of working memory, the importance of chunking, and the need to manage cognitive load so that learning remains possible rather than overwhelming.

We then analyzed the three components of Cognitive Load Theory – intrinsic, extraneous, and germane load – and discussed how each influences the learning process. Reducing extraneous load is especially crucial for self‑taught developers, as it frees up mental resources for meaningful understanding.

From there, we turned to the Ebbinghaus Forgetting Curve, which demonstrates how quickly newly learned information fades without reinforcement.

To counter this natural forgetting, we introduced Spaced Repetition, a method that strengthens memory by reviewing material at expanding intervals. We also examined Deliberate Practice, which pushes learners just beyond their comfort zone to promote genuine skill development, and Bloom’s Taxonomy, which outlines the stages of cognitive growth from remembering to creating.

Finally, we emphasized the importance of knowing when to step back. The brain operates in both focused and diffuse modes, and effective learning requires movement between the two. Breaks are not signs of weakness but essential components of consolidation and insight.

Together, these theories form a comprehensive framework for learning to code with scientific precision. When self‑taught developers understand how their brain learns, forgets, and grows, they can design a learning process that isn't only more efficient but far more sustainable.

With all this new knowledge, one truth is certain: focus, determination, and consistency are the forces that transform theory into mastery.

Learning science can guide the process, but only sustained effort turns knowledge into skill.

References

1. Clearwater, L. (2024). Understanding the Science Behind Learning Retention | Reports | What We Think | Indegene. [online] www.indegene.com. Available at: https://www.indegene.com/what-we-think/reports/understanding-science-behind-learning-retention.

2. Dylan Wiliam [@dylanwiliam]. (2017, January 25). I’ve come to the conclusion Sweller’s Cognitive Load Theory is the single most important thing for teachers to know [Tweet]. X. https://x.com/dylanwiliam/status/824682504602943489

3. Ericsson, K. A., Krampe, R. T., & Tesch-Römer, C. (1993).
   The role of deliberate practice in the acquisition of expert performance.
   Psychological Review, 100(3), 363–406.

4. Garnett, S. (2020.). Cognitive Load Theory A handbook for teachers. [online] Available at: https://www.crownhouse.co.uk/assets/look-inside/9781785835018.pdf.

5. Geary, D. C. (2007). An evolutionary perspective on learning disability in mathematics. Developmental Neuropsychology, 32(1), 471–519. https://doi.org/10.1080/87565640701360924

6. Geary, D. C. (2008). An evolutionarily informed education science. Educational Psychologist, 43(4), 179–195. https://doi.org/10.1080/00461520802392133

7. George A. Miller (1956). The magical number seven, plus or minus two: Some limits on our capacity for processing information. Psychological Review, 63(2), 81–97. https://doi.org/10.1037/h0043158

8. Nelson Cowan (2001). The magical number 4 in short-term memory: A reconsideration of mental storage capacity. Behavioral and Brain Sciences, 24(1), 87–114. https://doi.org/10.1017/S0140525X01003922

9. Oakley, B. (2014). A Mind for Numbers: How to Excel at Math and Science (Even If You Flunked Algebra). New York: TarcherPerigee.

10. Sweller, J. (1988). Cognitive Load during Problem Solving: Effects on Learning. Cognitive Science, [online] 12(2), pp.257–285. doi:https://doi.org/10.1207/s15516709cog1202_4.

‌

‌

The gap between "I know Python syntax" and "I can build a working web app" can feel enormous. But it does not have to be.

In this tutorial, you'll build a fitness tracker web application from scratch using Django, one of the most popular Python web frameworks. By the end, you'll have a fully functional app running live on the internet – something you can show to friends, add to your portfolio, or keep building on.

Here's what you'll learn:

• How Django projects and apps are structured

• How to define database models to store workout data

• How to create views that handle user requests

• How to build HTML templates that display your data

• How to connect URLs to views so users can navigate your app

• How to deploy your finished app to PythonAnywhere so anyone can access it

The app itself is straightforward: you can log a workout by entering an activity name, duration, and date. You can then view all your logged workouts on a separate page. It's simple, but it covers the core Django concepts you need to build much bigger things later.

Let's get started.

Table of Contents

• Prerequisites

• What You Are Going Build

• Step 1: How to Set Up Your Django Project

  • 1. 1 How to create a virtual environment

  • 1.2 How to install Django

  • 1.3 How to Create the Project

  • 1.4 How to run the development server

• Step 2: How to Create a Django App

  • 2.1 How to Generate the App

  • 2.2 How to Register the App

• Step 3: How to create a Workout Model

  • 3.1 How to Define the Model

• Step 4: How to Apply Migrations

  • 4.1 How to Generate the Migration

  • 4.2 How to Apply the Migration

• Step 5: How to Register the Model in the Admin Panel

  • 5.2 How to Create a Superuser

  • 5.3 How to Access the Admin Panel

• Step 6: How to Create Views for the App

  • 6.1 How to Create a Form Class

  • 6.2 How to Write Views

• Step 7: How to Create Templates

  • 7.1 How to Set Up the Template Directory

  • 7.2 How to Create the Workout List Template

  • 7.3 How to Create Add Workout Template

• Step 8: How to Connect URLs

  • 8.1 How to Create App Level URLs

  • 8.2 How to Link App URLs to project

• Step 9: How to Test the Application Locally

• Step 10: How to Prepare for Deployment

  • 10.1 How to Update Settings for Production

• Step 11: How to Deploy Your Django App on PythonAnywhere

  • 11.1 How to Create a PythonAnywhere Account

  • 11.2 How to Upload Your Project Files

  • 11.3 How to Set Up a Virtual Environment in PythonAnywhere

  • 11.4 How to Run Migrations and Create a SuperUser on PythonAnywhere

  • 11.4 How to Configure the Web App in Pythonanywhere

  • 11.5 How to Set the Virtual Environment Path

  • 11.6 How to Configure the WSGI file

  • 11.7 How to Set Up Static Files

  • 11.8 How to View Your Live Application

• Common Mistakes and How to Fix Them

• How You Can Improve This Project

• Conclusion

Prerequisites

Before you begin, make sure you are comfortable with the following:

Python fundamentals: You should understand variables, functions, lists, dictionaries, and basic control flow (if/else statements and loops).

Basic command line usage: You'll be running commands in your terminal throughout this tutorial. You should know how to open a terminal, navigate between folders, and run commands. If you're on Windows, you can use Command Prompt or PowerShell. On macOS or Linux, the default Terminal app works well.

Tools you'll need installed:

• Python 3.8 or higher. You can check your version by running python --version or python3 --version in your terminal.  If you don't have Python installed, download it from python.org

• pip. This is Python's package manager. It usually comes bundled with Python. You can verify by running pip --version or pip3 --version. Note the commands python3 and pip3 tell the terminal that you are explicitly using Python Version 3

• A code editor. Visual Studio Code is a great free option, but you can use any editor you're comfortable with.

That's everything. You don't need prior Django experience or web development knowledge. This tutorial will walk you through each step.

What You Are Going Build

The fitness tracker you will build has two main features:

1. A form to log workouts. You will enter the name of an activity (like "Running" or "Push-ups"), how long you did it (in minutes), and the date. When you submit the form, Django saves that workout to a database.

1. A page to view all your workouts. This page displays every workout you have logged, showing the activity, duration, and date in a clean list.

Here's how data flows through the app at a high level:

1. You fill out the workout form in your browser and click submit.

2. Your browser sends that data to Django.

3. Django's view function receives the data, validates it, and saves it to the database.

4. When you visit the workouts page, Django's view function pulls all saved workouts from the database.

5. Django passes that data to an HTML template, which renders it as a page your browser can display.

This request-response cycle is the foundation of how Django works. Once you understand it, you can build almost anything.

Step 1: How to Set Up Your Django Project

Every Django project starts with a few setup steps. You'll create an isolated Python environment, install Django, and generate the initial project structure.

1. 1 How to Create a Virtual Environment

A virtual environment is a self-contained folder that contains its own Python interpreter and installed packages for a specific project. This keeps your project's dependencies separate from other Python projects on your computer. This separation prevents version conflicts and keeps setups consistent.

For example, one project might require an older version of Django, while another needs the latest version, and a virtual environment allows both to work smoothly on the same system.

Without it, global installations can clash, break projects, and make setups hard to reproduce. Over time, the system environment becomes cluttered with unused or incompatible packages making debugging and maintenance more difficult.

Now let's set it up.

Open your terminal, and navigate to where you want your project to live and run the following command

mkdir fitness-tracker
cd fitness-tracker

The first command creates a new folder called fitness-tracker. The second command moves you into that folder.

You'll create the Python virutal environment here.

python3 -m venv venv

The above command creates a virtual environment inside a folder called venv. The first venv is the command and the second venv represents the name of the folder. You can name the folder anything though venv is usually preferred.

By using the ls command, you can see that we've created the virtual environment folder.

To activate the virtual environment, we need to use the following command:

On macOS/Linux:

source venv/bin/activate

On Windows:

venv\Scripts\activate

You'll know it worked when you see (venv) at the beginning of your terminal prompt. From this point on, any Python packages you install will only exist inside this virtual environment.

1.2 How to Install Django

With your virtual environment activated, install Django using pip:

pip install django

This downloads and installs the latest stable version of Django. You can verify the installation by running:

python3 -m django --version

After running both these commands, you should see Django being installed and the version number:

1.3 How to Create the Project

We have finished installing Django. Now let's create a Django project. Django provides a command line utility that generates the boilerplate files that you need. Type the following command:

django-admin startproject fitness_project .

The command creates a folder named fitness-project. Notice the dot at the end of the command. The dot at the end is important. It tells Django to create the project files in your current directory instead of creating an extra nested folder.

Now that we've created our Django project, let's open the project in your favourite text editor and look at folder structure.

You'll notice that the folder already comes with a bunch of files.

1.4 How to Run the Development Server

Now let's make sure everything is working. You'll need to run a server for this. Type the following command:

python manage.py runserver

You can type this command in the terminal with the virtual environment activated or you can use the integrated terminal if you're using VS Code. I'll be using the integrated terminal from this point on.

Open your browser and go to http://127.0.0.1:8000/. You should see Django's default welcome page with a rocket ship graphic confirming that your project is set up correctly.

Press Ctrl + C in your terminal to stop the server when you're ready to move on.

Step 2: How to Create a Django App

In Django, a project is the overall container for your entire web application, while an app is a smaller, self-contained module inside that project that focuses on a specific piece of functionality.

A useful way to picture this is to think of a house. The project is the whole house. Each app is like a room inside that house. One room might be a kitchen, another a bedroom, each designed with a clear purpose. In the same way, a Django app is built to handle one responsibility, such as authentication, payments, or in this case, workout tracking.

Now, here's the important part: why not just put everything into one big project instead of using apps? You technically could, especially for very small projects. But as your application grows, that approach quickly becomes difficult to manage.

By using apps, you naturally separate concerns. It also makes collaboration smoother, since different people can work on different apps without constantly stepping on each other’s code.

Another major benefit is reusability. Since apps are modular, you can take an app from one project and reuse it in another.

For example, if you build a workout tracking app once, you could plug it into a completely different Django project later without rebuilding it from scratch. Later, you might create a completely different project, say a fitness coaching platform or a health dashboard. Instead of rebuilding the tracking feature from scratch, you can reuse the same app.

For this project, you'll create a single app called tracker that handles everything related to logging and displaying workouts.

2.1 How to Generate the App

Make sure you're in the same directory as the manage.py file, then run the following code:

python manage.py startapp tracker

This create a new folder called tracker with the following following structure:

Each file has its own purpose. You'll work with models.py, views.py and admin.py throughout this project.

2.2 How to Register the App

Django doesn't automatically know about your new app. You need to tell it by adding the app to the INSTALLED_APPS list in settings.py file.

Open fitness_project/settings.py and find the INSTALLED_APPS list. Add the name of the app, that is tracker, to the end of the list:

You'll notice that a number of apps have already been installed automatically by Django. This is part of Django’s “batteries-included” philosophy, where many common features are ready to use out of the box.

Here is a short summary of what each of the apps does.

Now Django knows your tracker app exists and will include it when running the project.

Step 3: How to Create a Workout Model

A model in Django is a Python class that defines the structure of your data. Each model maps directly to a table in your database. Each attribute on the model becomes a column in that table.

Think of a model as a blueprint for a spreadsheet. The class name is the name of the spreadsheet, and each field is a column header. Every time you save a new workout, Django creates a new row in that spreadsheet.

3.1 How to Define the Model

Open tracker/models.py and replace its contents with this code:

from django.db import models

class Workout(models.Model):
    activity = models.CharField(max_length=200)
    duration = models.IntegerField(help_text="Duration in minutes")
    date = models.DateField()

    def __str__(self):
        return f"{self.activity} - {self.duration} min on {self.date}"

Let's discuss what each part does:

• activity = models.CharField(max_length=200) creates a text fields that can hold up to 200 characters. This is where you'll store the name of the exercise like "Running" or "Cycling".

• duration = models.IntegerField(help_text="Duration in minutes") creates a whole number field for storing how many minutes the workout lasted. The help_text parameter adds a hint that will appear in forms and the admin panel.

• date = models.DateField() creates a date field for recording when the workout happened.

The __str__() method defines how a Workout object appears when printed or displayed in the admin panel. Instead of seeing something unhelpful like "Workout object (1)," you will see "Running - 30 min on 2025-03-15."

Step 4: How to Apply Migrations

You've defined your model, but Django hasn't created the actual database table yet. To do that, you need to run migrations.

Migrations are Django's way of translating your Python model definitions into database instructions. Migrations are done in two steps.

When you change a model – maybe by adding a field, removing a field, or renaming one – you create a new migration that describes that change. You can do this using the makemigrations command.

Then you apply the migration using the migrate command and Django updates the database to match.

This two-step process of first detecting the change and then applying the change gives you a reliable record of every change to your database structure over time.

4.1 How to Generate the Migration

Run the following command in the integrated terminal:

python manage.py makemigrations

You should see output like this:

Migrations for 'tracker': tracker/migrations/0001_initial.py 
    + Create model Workout

Django inspected your Workout model and created a migration file that describes how to build the corresponding database table. You can find this file at tracker/migrations/0001_initial.py if you want to look at it, but you don't need to edit it.

4.2 How to Apply the Migration

Now tell Django to execute that migration and actually create the table in the database:

python manage.py migrate

You'll see several lines of output as Django applies not just your migration, but also the default migrations for Django's built-in apps (authentication, sessions, and so on).

When it finishes, your database has a table ready to store workouts.

When the migrate command runs, we can see the exact SQL commands that Django used to build and change the database. Though this isn't required for creating the application, it's always good to know what's happening under hood.

Run this command:

python manage.py sqlmigrate tracker 001

And you should get this output:

The 001 you added at the end is the migration number and represents first version of the database schema.

In practice, your workflow usually looks like this: you change your models, run makemigrations to generate the migration files, and then run the migrate command to apply those changes to the database.

Step 5: How to Register the Model in the Admin Panel

Django comes with a powerful admin interface built in. It gives you a graphical way to view, add, edit, and delete records in your database without writing any extra code. This is incredibly useful during development because you can quickly test your models and see your data.

But by default, it doesn’t know:

• Which models you want to manage

• How you want them displayed

So you register models in admin.py to tell Django to include the specific model in the admin interface.

5.1 How to Add Model to Admin

Open tracker/admin.py and add the following code:

from django.contrib import admin
from .models import Workout

admin.site.register(Workout)

This single line tells Django to include the Workout model in the admin interface.

5.2 How to Create a Superuser

To access the admin panel, you need an admin account. Create one by running:

python manage.py createsuperuser

Django will prompt you for a username, email address, and password. Choose something you will remember. The email is optional – you can press Enter to skip it.

5.3 How to Access the Admin Panel

Start the development server:

python manage.py runserver

Then navigate to http://127.0.0.1:8000/admin/ in your browser. Log in with the credentials you just created.

You should see the Django administration dashboard with a "Tracker" section containing your "Workouts" model.

Try clicking "Add" to create a couple of test workouts. This will confirm that your model is working correctly before you build the rest of the app.

Step 6: How to Create Views for the App

A view in Django is a Python function (or class) that receives a web request and returns a web response. That response could be an HTML page, a redirect, a 404 error, or anything else a browser can handle.

Views are where your application logic lives. They decide what data to fetch, what processing to do, and what to show the user.

For this app, you need two views: one to display the form where users add a workout, and one to display the list of all saved workouts.

6.1 How to Create a Form Class

Before writing the views, you need a Django form that handles the workout input.

Django forms are a built-in way to handle user input like login forms, contact forms, or anything that collects data from a user. Instead of manually writing HTML, validating inputs, and handling errors, Django gives you a structured way to do all of that in one place.

Most user inputs are based on the models you’ve created, and Django can automatically generate forms from those models using ModelForms, which speeds things up significantly.

Let's create a new file called forms.py in the tracker folder and add the following code:

from django import forms
from .models import Workout

class WorkoutForm(forms.ModelForm):

    class Meta:
        model = Workout
        fields = ['activity', 'duration', 'date']
        widgets = {
            'date': forms.DateInput(attrs={'type': 'date'}),
        }

In the above code, the ModelForm automatically generates form fields based on the Workout model. The widgets dictionary tells Django to render the date field as an HTML date picker instead of a plain text input.

We can actually see the forms being automatically created by Django. For this we need to enter the shell. In the terminal, type the following command:

python manage.py shell

Now lets import the WorkoutForm class that we just created.

Type the following code:

from tracker.forms import WorkoutForm

Notice that we've given the name of the app as well when we imported the form.

Then create an object of the WorkoutForm class and print it.

from tracker.forms import WorkoutForm
workoutform = WorkoutForm()
print(workoutform) 

You should get the following output:

You can see that all the model fields have been renderd as HTML forms and the date field has been created as a date type that is type="date" instead of plain text.

6.2 How to Write Views

As we've discussed above, our project has two views: one to add a workout and the other to display all the saved workouts.

First, let's create a view to add a workout. In the tracker/views.py file, type the following code:

from django.shortcuts import render, redirect
from .models import Workout

# view to list all workouts
def workout_list(request):
    workouts = Workout.objects.all().order_by('-date')
    return render(request, 'tracker/workout_list.html', {'workouts': workouts})

Let's walk through this view:

• The workout_list view handles the page that displays all workouts.

• It queries the database for every Workout object, orders them by date (most recent first, thanks to the - prefix), and passes that list to a template called workout_list.html.

• The render function combines the template with the data and returns the finished HTML page.

To create the logic to add a workout, first add the Workout form import at the end of the import section. Then add the following code after the workout_list view:

from django.shortcuts import render, redirect
from .models import Workout
from .forms import WorkoutForm

# view to list all the workouts
def workout_list(request):
    workouts = Workout.objects.all().order_by('-date')
    return render(request, 'tracker/workout_list.html', {'workouts': workouts})

# view to add a workout
def add_workout(request):
    if request.method == 'POST':
        form = WorkoutForm(request.POST)
        if form.is_valid():
            form.save()
            return redirect('workout_list')
    else:
        form = WorkoutForm()
    return render(request, 'tracker/add_workout.html', {'form': form})

• The add_workout view handles both displaying the empty form and processing submitted form data.

• When a user first visits the page, the request method is GET, so Django creates a blank form and renders it.

• When the user fills out the form and clicks submit, the request method is POST. Django then validates the submitted data, saves it to the database if everything is correct, and redirects the user to the workout list page.

• If the data isn't valid, Django re-renders the form with error messages.

Here is the complete views code:

from django.shortcuts import render, redirect
from .models import Workout
from .forms import WorkoutForm

# view to list all workouts
def workout_list(request):
    workouts = Workout.objects.all().order_by('-date')
    return render(request, 'tracker/workout_list.html', {'workouts': workouts})

# view to add a workout
def add_workout(request):
    if request.method == 'POST':
        form = WorkoutForm(request.POST)
        if form.is_valid():
            form.save()
            return redirect('workout_list')
    else:
        form = WorkoutForm()
    return render(request, 'tracker/add_workout.html', {'form': form})

Step 7: How to Create Templates

Templates are HTML files that Django fills in with dynamic data. They're the front end of your application: the part users actually see in their browser.

7.1 How to Set Up the Template Directory

Django looks for templates inside a templates folder within each app. Create the following folder structure inside your tracker app.

tracker/templates/tracker

The double tracker folder name might look redundant, but it's a Django convention called template namespacing. It prevents naming conflicts if you have multiple apps with templates that share the same filename.

7.2 How to Create the Workout List Template

Create a file called tracker/templates/tracker/workout_list.html and add the following code:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Workouts</title>
    <style>
        * {
            margin: 0;
            padding: 0;
            box-sizing: border-box;
        }

        body {
            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
            background-color: #f5f7fa;
            color: #333;
            line-height: 1.6;
            padding: 2rem;
        }

        .container {
            max-width: 700px;
            margin: 0 auto;
        }

        h1 {
            font-size: 1.8rem;
            margin-bottom: 1rem;
            color: #1a1a2e;
        }

        .add-link {
            display: inline-block;
            background-color: #4361ee;
            color: white;
            padding: 0.6rem 1.2rem;
            border-radius: 6px;
            text-decoration: none;
            margin-bottom: 1.5rem;
            font-size: 0.95rem;
        }

        .add-link:hover {
            background-color: #3a56d4;

        }

        .workout-card {
            background: white;
            border-radius: 8px;
            padding: 1rem 1.2rem;
            margin-bottom: 0.8rem;
            box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
            display: flex;
            justify-content: space-between;
            align-items: center;

        }

        .workout-activity {
            font-weight: 600;
            font-size: 1.05rem;

        }

        .workout-details {
            color: #666;
            font-size: 0.9rem;

        }

        .empty-state {
            text-align: center;
            padding: 3rem 1rem;
            color: #888;

        }

    </style>
</head>

<body>
    <div class="container">
        <h1>My Workouts</h1>
        <a href="{% url 'add_workout' %}" class="add-link">+ Log a Workout</a>
        {% if workouts %}
            {% for workout in workouts %}
                <div class="workout-card">
                    <div>
                        <div class="workout-activity">{{ workout.activity }}</div>
                        <div class="workout-details">{{ workout.duration }} minutes</div>
                    </div>
                    <div class="workout-details">{{ workout.date }}</div>
                </div>
            {% endfor %}

        {% else %}
            <div class="empty-state">
                <p>No workouts logged yet. Start by adding one!</p>
            </div>
        {% endif %}
    </div>
</body>
</html>

There are a few things worth noting here:

If you look closely at the HTML, you'll spot some weird-looking tags wrapped in curly braces ( {% %} and {{ }} ). Think of them as special instructions for Django.

You use the double curly braces ({{ }}) when you want to output or display a piece of data directly on the page.

On the other hand, you use the brace-and-percent-sign combo ( {% %} ) when you need Django to actually perform an action or apply logic, like running a loop or checking a condition.

They allow us to inject dynamic data straight from our Python backend right into our otherwise static HTML.

Lets look at this code snippet for the workout_list.html

<body>
    <div class="container">
        <h1>My Workouts</h1>
        <a href="{% url 'add_workout' %}" class="add-link">+ Log a Workout</a>
        {% if workouts %}
            {% for workout in workouts %}
                <div class="workout-card">
                    <div>
                        <div class="workout-activity">{{ workout.activity }}</div>
                        <div class="workout-details">{{ workout.duration }} minutes</div>
                    </div>
                    <div class="workout-details">{{ workout.date }}</div>
                </div>
            {% endfor %}

        {% else %}
            <div class="empty-state">
                <p>No workouts logged yet. Start by adding one!</p>
            </div>
        {% endif %}
    </div>
</body>

There are a few things worth noting here.

Right under the main heading, you'll see this line:
<a href="{% url 'add_workout' %}">

Instead of hardcoding a web link like href="/add-workout/", Django uses the {% url %} tag to generate the link dynamically. You pass it the name of the route (in this case, add_workout), and Django automatically figures out the correct URL path.

If you ever change the URL structure in your Python code later, Django updates this link automatically. You never have to hunt through HTML files to fix broken links!

The {% if workouts %} block checks whether there are any workouts to display. If the list is empty, it shows a friendly message instead of a blank page.

The {% for workout in workouts %} loop iterates over every workout in the list and renders a card for each one. The double curly braces {{ workout.activity }} insert the value of each field into the HTML

Inside the loop, you'll notice tags that look like this:

• {{ workout.activity }}

• {{ workout.duration }}

• {{ workout.date }}

As Django loops through each workout object, it uses dot notation to peek inside that specific object and grab its details. It grabs the activity type (like "Running"), the duration ("30"), and the date ("March 30"), and prints that exact text directly onto the webpage for the user to see.

7.3 How to Create Add Workout Template

Create a file called tracker/templates/tracker/add_workout.html and add the following code:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Log a Workout</title>
    <style>
        * {
            margin: 0;
            padding: 0;
            box-sizing: border-box;

        }

        body {
            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
            background-color: #f5f7fa;
            color: #333;
            line-height: 1.6;
            padding: 2rem;
        }

        .container {
            max-width: 500px;
            margin: 0 auto;

        }

        h1 {
            font-size: 1.8rem;
            margin-bottom: 1.5rem;
            color: #1a1a2e;
        }

        .form-group {
            margin-bottom: 1.2rem;
        }

        label {
            display: block;
            margin-bottom: 0.3rem;
            font-weight: 600;
            font-size: 0.95rem;

        }

        input[type="text"],
        input[type="number"],
        input[type="date"] {
            width: 100%;
            padding: 0.6rem 0.8rem;
            border: 1px solid #ddd;
            border-radius: 6px;
            font-size: 1rem;
            transition: border-color 0.2s;
        }

        input:focus {
            outline: none;
            border-color: #4361ee;

        }

        .btn {
            background-color: #4361ee;
            color: white;
            padding: 0.7rem 1.5rem;
            border: none;
            border-radius: 6px;
            font-size: 1rem;
            cursor: pointer;
            margin-right: 0.5rem;
        }

        .btn:hover {
            background-color: #3a56d4;
        }

        .back-link {
            color: #4361ee;
            text-decoration: none;
            font-size: 0.95rem;
        }

        .back-link:hover {
            text-decoration: underline;
        }

        .actions {
            display: flex;
            align-items: center;
            gap: 1rem;
            margin-top: 0.5rem;
        }

        .error-list {
            color: #e74c3c;
            font-size: 0.85rem;
            margin-top: 0.3rem;

        }

    </style>
</head>
<body>
    <div class="container">
       <h1>Log a Workout</h1>
        <form method="post">
            {% csrf_token %}
            <div class="form-group">
                <label for="id_activity">Activity</label>
                {{ form.activity }}
                {% if form.activity.errors %}
                    <div class="error-list">{{ form.activity.errors }}</div>
                {% endif %}
            </div>
            <div class="form-group">
                <label for="id_duration">Duration (minutes)</label>
                {{ form.duration }}
                {% if form.duration.errors %}
                    <div class="error-list">{{ form.duration.errors }}</div>
                {% endif %}
            </div>

            <div class="form-group">
                <label for="id_date">Date</label>
                {{ form.date }}
                {% if form.date.errors %}
                    <div class="error-list">{{ form.date.errors }}</div>
                {% endif %}
            </div>

            <div class="actions">
                <button type="submit" class="btn">Save Workout</button>
                <a href="{% url 'workout_list' %}" class="back-link">Cancel</a>
            </div>
        </form>
    </div>
</body>
</html>

In the previous template, we learned how to display data. Now, we're looking at a form that actually collects data. Handling forms manually in web development can get messy, but Django provides some powerful template tags to do the heavy lifting for us.

Let's look at the Django-specific logic powering this form:

First, right after opening the <form> tag, you'll spot a very important line: {% csrf_token %}. Whenever you submit data to a server using a "POST" method, malicious sites can potentially intercept or forge that request.

By including this {% csrf_token %}, you tell Django to generate a unique, hidden security key for the form. When the user clicks "Save Workout," Django checks this token to guarantee the request is legitimate. If you forget this tag, Django will simply reject your form!

<form method="post">
            {% csrf_token %}
            <div class="form-group">
                <label for="id_activity">Activity</label>
                {{ form.activity }}
                {% if form.activity.errors %}
                    <div class="error-list">{{ form.activity.errors }}</div>
                {% endif %}
            </div>
            <div class="form-group">
                <label for="id_duration">Duration (minutes)</label>
                {{ form.duration }}
                {% if form.duration.errors %}
                    <div class="error-list">{{ form.duration.errors }}</div>
                {% endif %}
            </div>

            <div class="form-group">
                <label for="id_date">Date</label>
                {{ form.date }}
                {% if form.date.errors %}
                    <div class="error-list">{{ form.date.errors }}</div>
                {% endif %}
            </div>

            <div class="actions">
                <button type="submit" class="btn">Save Workout</button>
                <a href="{% url 'workout_list' %}" class="back-link">Cancel</a>
            </div>
        </form>

Now let's talk about automatically generating the form fields. Instead of manually typing out all the HTML <input> tags for the activity, duration, and date, we let Django do it for us using display tags ({{ }}).

Each {{ form.activity }}, {{ form.duration }}, and {{ form.date }} tag renders the corresponding form input. Django handles the HTML attributes, input types, and validation for you based on the model and form definitions.

The error blocks below each field display validation messages if a user submits invalid data, like entering text in the duration field instead of a number. Users make mistakes. They might leave a required field blank or type text into a number field. Fortunately, Django validates the data for you and sends back errors if something goes wrong.

Underneath each input field, we use a logic block that looks like this:
{% if form.activity.errors %}

This code checks a simple condition: Did the user mess up this specific field? If Django found an error with the "activity" input, the code drops into the if block and uses{{ form.activity.errors }} block to print the exact error message (like "This field is required") right below the input box.

You may notice that both templates include inline CSS rather than a separate stylesheet. For a small project like this, inline styles keep things simple and self-contained. In a larger project, you would use Django's static files system to manage CSS separately.

Step 8: How to Connect URLs

You have views and templates, but Django doesn't know when to use them yet. You need to map URLs to views so that visiting a specific address in the browser triggers the right view function.

8.1 How to Create App Level URLs

Create a new file called tracker/urls.py and add the following code:

from django.urls import path
from . import views

urlpatterns = [ 
    path('', views.workout_list, name='workout_list'), 
    path('add/', views.add_workout, name='add_workout'), 
]

Each path function takes three arguments.

The first is the route string that represents a URL pattern (an empty string means the root of the app).

The second is the view function to call when that URL is visited.

The third is a name you can use to reference this URL elsewhere in your code, like in the {% url %} template tags you used earlier.

8.2 How to Link App URLs to project

Now that your app-level URLs are set up, the next step is to connect them to the main project so Django knows where to start routing requests. Think of it like linking a smaller map (your app) to a bigger map (your project), so everything works together smoothly.

Open fitness_project.urls.py and update it to include your app's URLs:

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('tracker.urls')),
]

The include() function tells Django to look at the URL patterns defined in the tracker/urls.py file whenever someone visits your site. The empty string prefix means your tracker app handles requests at the root of the site.

Here's the full picture of how a request flows through the URL system.

When someone visits http://127.0.0.1:8000/add/, Django first checks fitness_project/urls.py. It matches the empty prefix and delegates to tracker/urls.py. There, it matches add/ and calls the add_workout view.

Step 9: How to Test the Application Locally

At this point, your app has everything it needs to work. Let's test it.

Start the development server by running the command:

python manage.py runserver

Open your browser and visit http://127.0.0.1:8000/. You should see the workout list page with the heading "My Workouts" and a button that says "+ Log a Workout."

Click that button. You should see the workout form with fields for activity, duration, and date.

Fill in some test data:

• Activity: Skipping

• Duration: 25

• Date: Pick today's date from the date picker

Click "Save Workout" You should be redirected back to the workout list page, and your new workout should appear as a card.

Try adding a few more workouts with different activities and dates. Make sure they all show up on the list page in the correct order (most recent first).

This is also a good time to experiment. Try submitting the form with missing fields and see how Django handles validation.

Try accessing the admin panel at http://127.0.0.1:8000/admin/ to see your workouts there as well.

If everything works as expected, you're ready to put your app on the internet.

Step 10: How to Prepare for Deployment

Running your app on localhost is great for development, but nobody else can see it. Deployment means putting your app on a server that's accessible from anywhere on the internet.

Before you deploy, you'll need to make a few changes to your project's settings.

10.1 How to Update Settings for Production

Open fitness_project/settings.py and make the following changes.

First, set DEBUG to False.

During development, DEBUG = True shows detailed error pages that help you fix problems. In production, these error pages would expose sensitive information about your code and server to anyone who triggers an error.

Next, update ALLOWED_HOSTS to include PythonAnywhere's domain.

This setting tells Django which domain names are allowed to serve your app. Replace yourusername with the actual PythonAnywhere username you will create in the next step.

ALLOWED_HOSTS = ['yourusername.pythonanywhere.com']

Finally, add a STATIC_ROOT setting so Django knows where to collect your static files (CSS, JavaScript, images) for production:

import os
STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')

These are the minimum changes needed for a basic deployment.

💡 For a production app handling real user data, you would also want to set a secure SECRET_KEY, configure a proper database like PostgreSQL, and set up HTTPS. But for a learning project, these changes are enough.

Step 11: How to Deploy Your Django App on PythonAnywhere

PythonAnywhere is a hosting platform designed specifically for Python web applications. It offers a free tier that's perfect for beginner projects, and it handles much of the server configuration that would otherwise be complex to set up on your own.

11.1 How to Create a PythonAnywhere Account

Go to pythonanywhere.com and sign up for a free "Beginner" account. Remember the username you choose, because your app will be available at yourusername.pythonanywhere.com.

Now signup to the website. Fill in the username, email and password and click on the free tier or now.

11.2 How to Upload Your Project Files

After logging in, you have two options for getting your project files onto PythonAnywhere.

Option A: Upload using Git

If your project is in a Git repository, open a Bash console from the PythonAnywhere dashboard by clicking "Consoles" and then "Bash." Then clone your repository:

git clone https://github.com/yourusername/fitness-tracker.git

In this tutorial, we won't be using Git. Instead we'll follow the second option.

Option B: Upload files manually

First go your project folder in your computer and created a compressed version of the project.

IMPORTANT NOTE: When you create the compressed file, make sure to first create a copy of the project somewhere and remove the venv and pycache folder before you compress it.

Navigate to your home directory and click on upload file tab and upload the compressed file.

Now we need to unzip the compressed file. To do this, go to the Consoles tab and click on Bash console.

The bash console should open. Then type the following command in the console to unzip the folder:

unzip fitness-tracker.zip

11.3 How to Set Up a Virtual Environment in PythonAnywhere

Open a Bash console from the PythonAnywhere dashboard. Navigate to your project directory and create a fresh virtual environment:

cd fitness-tracker

Type the following command to install a virtual environment as we've done before and then activate the virtual environment:

python3 -m venv venv

source venv/bin/activate

Now install Django as before using pip install django command:

11.4 How to Run Migrations and Create a SuperUser on PythonAnywhere

While you're still in the Bash console with your virtual environment activated, run the migrations to create the database tables on the server:

python manage.py makemigrations

python manage.py migrate

python manage.py createsuperuser

11.4 How to Configure the Web App in Pythonanywhere

Go to the "Web" tab on the PythonAnywhere dashboard and click "Add a new web app." Follow the setup wizard:

Click "Next" on the domain name step (remember the free tier uses yourusername.pythonanywhere.com).

Select "Manual configuration" (not "Django" – the manual option gives you more control).

Then choose the Python version that matches what you installed. In my case it's 3.13, so I'll choose 3.13

Click on Next button and a WSGI (Web Server Gateway Interface) will be created.

With this we've created the web app:

After you've set up the web app, you have to do two more things:

• Set the virtual environment path

• Configure the WSGI file

11.5 How to Set the Virtual Environment Path

On the Web tab, scroll down to the "Virtualenv" section and enter the path to your virtual enviroment. The path to the file should be like this:

/home/yourusername/fitness-tracker/venv

11.6 How to Configure the WSGI file

Still on the Web tab, scroll to the code section and click on the WSGI configuration file link:

Delete all the contents and replace them with the content below and save the file:

import os
import sys
path = '/home/prabodhtuladhardev/fitness-tracker' #replace with your username
if path not in sys.path:
    sys.path.append(path)

os.environ['DJANGO_SETTINGS_MODULE'] = 'fitness_project.settings'

from django.core.wsgi import get_wsgi_application
application = get_wsgi_application()

11.7 How to Set Up Static Files

Still on the "Web" tab, scroll down to the "Static files" section. Add an entry:

• URL: /static/

• Directory: /home/yourusername/fitness-tracker/staticfiles

Then go back to your Bash console and run the following command:

python manage.py collectstatic

This copies all static files to the staticfiles directory so PythonAnywhere can serve them directly.

Go back to the "Web" tab and click the green "Reload" button at the top. This restarts your app with all the new configuration.

11.8 How to View Your Live Application

Open a new browser tab and visit https://yourusername.pythonanywhere.com. You should see your fitness tracker, live on the internet.

Try adding a workout.

Visit the admin panel at https://yourusername.pythonanywhere.com/admin/.

Everything should work just as it did on your local machine, but now anyone with the link can access it.

This is a meaningful milestone. You've gone from zero to a deployed Django application. Share the link with a friend or post it in a coding community. Seeing your work live on the internet is one of the most motivating experiences in learning to code.

Common Mistakes and How to Fix Them

Even when you follow each step carefully, things can go wrong. Here are the most common issues beginners run into and how to solve them.

"ModuleNotFoundError: No module named 'django'" – This usually means your virtual environment isn't activated. Run source venv/bin/activate (macOS/Linux) or venv\Scripts\activate (Windows) and try again. On PythonAnywhere, make sure the virtualenv path in the "Web" tab points to the correct location.

"DisallowedHost" error – You forgot to add your domain to ALLOWED_HOSTS in settings.py, or there's a typo. Double-check that it matches your PythonAnywhere URL exactly.

Static files not loading in production – Make sure you ran python manage.py collectstatic and that the static file mapping on PythonAnywhere points to the correct staticfiles directory. Also verify that STATIC_ROOT is set in settings.py.

"No such table" or migration errors – You probably forgot to run python manage.py migrate after cloning or uploading your project to PythonAnywhere. Run the migrate command in the Bash console.

Changes not showing up on PythonAnywhere – After making any code changes, you must click the "Reload" button on the "Web" tab. PythonAnywhere does not automatically detect file changes.

How You Can Improve This Project

The fitness tracker you built is intentionally simple. That's a feature, not a limitation. A working simple project is the perfect foundation for learning more.

Here are some ideas for expanding it.

1. Add user authentication: Right now, anyone who visits the site sees the same workout data. Django has a built-in authentication system that lets you add registration, login, and logout. Each user could then have their own private list of workouts.

2. Add the ability to edit and delete workouts. Currently, once a workout is saved, there's no way to change or remove it from the interface (you can do it through the admin panel, but not the main app). Try creating new views and templates for editing and deleting.

3. Add workout categories or tags. Let users categorize their workouts as "Cardio," "Strength," "Flexibility," and so on. This would involve adding a new field to the model or creating a separate Category model with a foreign key relationship.

4. Add charts and progress tracking. Use a JavaScript charting library like Chart.js to display workout trends over time. For example, you could show a bar chart of total minutes exercised per week.

5. Build an API with Django REST Framework. If you want to learn about building APIs, try installing Django REST Framework (DRF) and creating API endpoints for your workouts. This would let you build a mobile app or a separate front end that communicates with your Django back end.

Each of these improvements will teach you something new about Django while building on the foundation you already have.

Conclusion

You've built a fully functional fitness tracker web app with Django and deployed it to the internet. That's no small achievement.

Along the way, you learned how Django projects and apps are structured, how models define the shape of your data, how migrations translate those models into database tables, how views handle the logic of your application, how templates render dynamic HTML, and how URLs tie everything together. You also went through the entire deployment process on PythonAnywhere.

These are the core building blocks of Django development. The patterns you practiced here – defining a model, creating a form, writing a view, building a template, and connecting a URL – are the same patterns you will use in every Django project, no matter how complex.

The best way to solidify what you have learned is to keep building. Try one of the improvements mentioned above, or start a completely new project. A calorie tracker, a habit tracker, an expense tracker, or a personal journal would all use the same Django concepts with slightly different models and views.

Real world applications aren’t just about showing data on a screen. They solve real problems, work with real users, and handle situations that don’t always go as planned. This is where many developers struggle.

When I review junior developers’ résumés, I notice a common pattern: the projects section is often filled with beginner apps that look very similar. In today’s job market, this is usually not enough. Employers want to see that you can build something useful, something people would actually use.

The goal of this article is to help you move past simple Hello World projects like todo apps, calculators, and basic CRUD applications. By the end, you’ll understand how to approach building real applications that solve real problems and feel closer to what is built in the real world.

You might be wondering why you should listen to me.

Over the last 10 years, I’ve spent a lot of time building, breaking, and rebuilding software. I have experimented, failed many times, and eventually built applications that thousands of people use every day. A few weeks ago, I launched one of my own SaaS products and watched real users use it at scale, with over a thousand active users during peak hours, without the system crashing.

I’m sharing this because I’ve been where you are now.

If you continue reading, you will:

• Learn from real experience building applications used by real users

• Learn what not to do, based on years of mistakes and lessons

• Learn what actually works and what helps you stand out as a junior developer

• Clear up common misconceptions that slow people down

This article is not about theory. It’s about building real things.

To drive this point home, we’ll build a real world application that solves a real problem and is used by real people. Along the way, you’ll learn how to come up with real application ideas, how to build them with simple tools, and how to serve them to many users.

If this sounds like something you’re up for, then let’s get started.

Table of Contents

1. You Probably Think You Don’t Know Enough

2. How to Find Real World Application Ideas

3. What Are We Going to Build

4. Prerequisites

5. Step 1: Setting Up the Backend

6. Step 2: Adding Background Removal to the Backend

7. Step 3: Building the Frontend

   • Running and Testing the Application Locally

8. Step 4: Putting the Backend on the Internet

   • Deploying the Backend on Cloud Run

   • Updating the Frontend to Use the Live Backend

9. Step 5: Making the Backend and Frontend Work Together CORS

10. Step 6: Putting the Frontend on the Internet

11. Final Thoughts What You Just Built Matters

You Probably Think You Don't Know Enough

Before we begin, I want to clear up the most common misconception beginners have.

Many developers believe they don’t know enough to start building real world applications. They think they need to learn more JavaScript, more Python, or another framework before they are ready. Some even think learning React is the final step that will suddenly make everything click.

This belief is very common, but it’s not true.

If you know how to write HTML, CSS, and a simple loop or function in any programming language, you already have most of what it takes to build a real world application. This tutorial is proof of that.

That’s why I am writing this article. Not to tell you to learn more first, but to show you how far you can go with what you already know.

How to Find Real World Application Ideas

One question beginners ask a lot is, “What kind of apps should I build?”

This is rarely talked about, but it matters more than most people think.

A simple rule is this: build things that already exist.

Look at the apps you use every day, especially the simple ones. Tools that do one thing well. If you find yourself using an app often, that app is solving a real problem.

For example, people use background removers to clean up images. They use URL shorteners to share links. They use notes apps to save quick thoughts. None of these ideas are new, but they are real.

You don’t need to invent something original. You need to understand a problem and build a working solution for it.

When you replicate real tools, you naturally learn how real applications are structured. You also end up with projects that make sense on a résumé, because they solve problems people recognize.

That’s exactly what we are going to do in this tutorial.

What Are We Going to Build?

I’ll tell you now, it is not going to be another Hello World application. We’re going to be building a background remover web application.

This is the kind of tool people actually use. Designers use it for images, content creators use it for thumbnails, and developers build similar features into real products. It works with real files, real data, and real results.

If you want to see the final result before we start building, you can try the working app here: https://iamspruce.github.io/background-remover/

We’ll build this app using simple tools on purpose. Plain HTML, CSS, and JavaScript for the frontend, and Python for the backend. No heavy frameworks and no complicated setup.

Before we continue, let me clear up another common misconception.

Many developers believe that for an application to be taken seriously, it must be built with complex frameworks. In my experience building applications for clients around the world over the last 10 years, not a single client has ever asked me what framework I used.

They only cared about one thing: Did it work, and did it solve their problem?

Users won’t care how your app is built. They care that it works. If HTML, CSS, and JavaScript can solve the problem, there’s no reason to wait months just to learn a new framework.

Now that we understand why we’re building this app and what problem it solves, it’s time to start writing code.

Prerequisites

Before we start writing code, let’s quickly talk about what you need.

This tutorial is not for absolute beginners, but it’s also not super advanced. If you’ve built small things before and you want to build something that actually feels real, you’re in the right place.

What You Should Already Know

You should be comfortable with:

• Basic HTML: You know what inputs, buttons, images, and divs do.

• Basic CSS: You can style a page and make it look presentable.

• Basic JavaScript: You know how to listen for a button click and send a request using fetch.

That’s enough to follow along.

You don’t need React or any other frontend framework.

Backend Knowledge

For the backend, you don’t need to be a Python expert.

You just need to understand that:

• Python can run a server

• A server can receive requests

• A server can send back responses

Everything else will be explained as we go.

Tools You Need

Make sure you have these installed:

• Python 3.9 or newer

• Git

• A code editor like VS Code

• A browser

No Docker knowledge or cloud experience required.

GitHub Account (Important)

We’ll deploy the backend directly from GitHub, so you’ll need a GitHub account.

If you’ve never pushed a project to GitHub or hosted one before, I’ve already written a beginner-friendly guide you can follow first.

Read that article, then come back here.

A Quick Mindset Check

This is not a copy-paste tutorial. You will see real errors. Things may break. That’s normal. That’s how real applications are built.

Now that we’re clear on what you need, let’s start writing code.

We’ll begin with the backend. This is an important decision, so let’s explain it properly.

Step 1: Setting Up the Backend

What Is a Backend and Why Do We Need One?

A backend is a program that runs on a server and does the heavy work for an application.

In our case, the heavy work is image processing. Removing a background from an image requires libraries that can’t run inside the browser. Browsers are designed for safety and user interaction, not for this kind of processing.

That’s why we need a backend.

The backend will:

• Receive an image from the user

• Remove the background

• Send the processed image back

The frontend will simply talk to this backend later.

Keeping Things Simple on Purpose

Because this might be your first real project, we’re going to keep the backend as simple as possible.

• One programming language (Python)

• One backend file

• No complex folder structure

• No advanced concepts

This is intentional. Real world applications don’t have to start out complex. They typically start small and grow.

Project Structure

Create a new folder called:

background-remover

Inside it, create a folder for the backend:

background-remover/
  backend/

Move into the backend folder:

cd background-remover/backend

Now create a virtual environment:

python -m venv env

A virtual environment keeps this project’s dependencies separate from everything else on your computer. This is standard practice and something you’ll see in real projects.

Now activate it:

macOS or Linux:

source env/bin/activate

Windows:

env\Scripts\activate

Now create a folder for your application code:

mkdir api

Your structure should now look like this:

background-remover/
  backend/
    env/
    api/

At this stage, nothing looks impressive yet. That’s normal.

Installing FastAPI

We’ll use FastAPI to build the backend API.

Install it together with Uvicorn, which is the server that runs our app:

pip install fastapi uvicorn

FastAPI allows us to define endpoints clearly and with very little code, which is perfect for us.

Creating the First Backend File

Inside the api folder, create a file called main.py.

Add the following code:

from fastapi import FastAPI

app = FastAPI()

@app.get("/health")
def health():
    return {"status": "ok"}

Let’s pause and understand what this does.

• We created a FastAPI application

• We added a /health endpoint

• This endpoint simply returns a message

Before building real features, developers always confirm that their server actually runs. That is exactly what this endpoint is for.

Running the Server

From inside the backend folder, start the server:

uvicorn api.main:app --reload

Now open a new terminal and run:

curl http://localhost:8000/health

You should see:

{"status":"ok"}

This is an important moment.

You now have:

• A running backend server

• A real HTTP endpoint

• A response coming from your own code

This is how real backend services start.

Why We Did This First

At this point, you might wonder why we didn’t jump straight into background removal.

The reason is simple: if the server doesn’t run, nothing else matters.

By starting with a health endpoint, we removed uncertainty. We know the server works. Everything we add next is built on top of something we already know is working.

Now that the foundation is in place, we can move on to the real feature.

Step 2: Adding Background Removal to the Backend

Before we write any code here, we need to clear up an important misconception.

A Common Misconception About Machine Learning

When people hear “background removal,” they often think machine learning is too advanced for them.

In real world development, this is almost never how it works.

You aren’t expected to build machine learning models yourself. You use libraries created by others and focus on integrating them correctly.

That is exactly what we’re doing here.

Installing the Background Removal Library

Install the required packages:

pip install rembg pillow onnxruntime

• rembg handles the background removal

• pillow helps us work with images

For our purposes here, you don’t need to understand how these libraries work internally. You only need to know how to use them.

Adding the Background Removal Endpoint

Now update main.py so it looks like this:

from fastapi import FastAPI, UploadFile, File
from rembg import remove
from PIL import Image
import io

app = FastAPI()

@app.get("/health")
def health():
    return {"status": "ok"}

@app.post("/remove-bg")
async def remove_bg(file: UploadFile = File(...)):
    image_bytes = await file.read()
    image = Image.open(io.BytesIO(image_bytes))

    output = remove(image)

    buffer = io.BytesIO()
    output.save(buffer, format="PNG")
    buffer.seek(0)

    return buffer.getvalue()

Let’s explain this carefully.

• The endpoint accepts an uploaded image

• The image is read into memory

• The background is removed

• The result is saved as a PNG with transparency

• The image is returned to the client

This endpoint is the core of our application.

Testing the Endpoint With curl

Before building the frontend, we’ll test the backend directly.

Run this command:

curl -X POST \
  -F "file=@person.jpg" \
  http://localhost:8000/remove-bg \
  --output result.png

Open result.png. If you see the background removed, then the backend is complete.

At this point, you have built a backend that:

• Accepts real user input

• Processes real data

• Returns a meaningful result

This is a real backend.

Where We Are Now

Let’s pause and summarize:

• We set up a backend server

• We confirmed that it runs

• We added a real feature

• We tested it without a frontend

This is exactly how real developers work.

In the next section, we’ll build a simple frontend that talks to this backend and turns it into something users can interact with.

Step 3: Building the Frontend (What the User Actually Sees)

At this point, our backend is working.

It can receive an image, remove the background, and send the result back. But right now, only developers can use it, because it requires terminal commands.

To make this useful to actual (non-technical) people, we need a frontend.

The frontend is simply the part of the application users see and interact with in their browser.

Clearing a Common Misconception About Frontends

Many beginners think building a frontend means learning a framework first.

This is not true.

Frameworks help later, but they aren’t required to build real applications. Under the hood, every frontend still comes down to HTML, CSS, and JavaScript.

That’s why we are using plain HTML, CSS, and JavaScript here. No React, no build tools, no setup. Just the basics.

What Our Frontend Will Do

Our frontend has one job. It will:

• Let the user select an image

• Send that image to the backend

• Receive the processed image

• Show it on the screen

• Allow the user to download it

That’s all.

If it does these things correctly, it’s a real frontend.

Creating the Frontend

Go back to the root of your project and create three files:

index.html
styles.css
app.js

This simple setup is very common. Each file has a clear responsibility, which makes the code easier to understand.

Writing the HTML Page

Open index.html and add the following:

<!DOCTYPE html>
<html>
  <head>
    <title>Background Remover</title>
    <link rel="stylesheet" href="styles.css" />
  </head>
  <body>
    <h1>Background Remover</h1>

    <input type="file" id="imageInput" />
    <button id="removeBtn">Remove Background</button>

    <div class="result">
      <img id="resultImage" />
    </div>

    <a id="downloadLink" download>Download Image</a>

    <script src="app.js"></script>
  </body>
</html>

Right now, this page won’t do anything interesting. That’s expected.

HTML only describes what should be on the page. The behavior comes from JavaScript, which we’ll add after we add some styling.

Adding Some Basic Styling

Open styles.css and add this:

body {
  font-family: sans-serif;
  max-width: 600px;
  margin: 40px auto;
}

button {
  margin-top: 10px;
}

.result {
  margin-top: 20px;
}

img {
  max-width: 100%;
}

#downloadLink {
  display: none;
  margin-top: 10px;
}

This is not about making things look fancy.

The goal here is simply to make the page readable and pleasant to use. Many real internal tools look no better than this. (And you can always improve the styling later if you want.)

Connecting the Frontend to the Backend

Now we’ll write the JavaScript that makes everything work.

Open app.js and add the following code:

const imageInput = document.getElementById("imageInput");
const removeBtn = document.getElementById("removeBtn");
const resultImage = document.getElementById("resultImage");
const downloadLink = document.getElementById("downloadLink");

removeBtn.addEventListener("click", async () => {
  const file = imageInput.files[0];

  if (!file) {
    return;
  }

  const formData = new FormData();
  formData.append("file", file);

  const response = await fetch("http://localhost:8000/remove-bg", {
    method: "POST",
    body: formData,
  });

  const blob = await response.blob();
  const imageUrl = URL.createObjectURL(blob);

  resultImage.src = imageUrl;
  downloadLink.href = imageUrl;
  downloadLink.style.display = "inline";
});

Let’s slow down and explain what’s happening here:

• We read the image selected by the user

• We wrap it in FormData so it can be sent to the backend

• We send it to our /remove-bg endpoint

• We receive the processed image back

• We display it and prepare it for download

This is the moment where the frontend and backend finally talk to each other.

Running the Frontend With Live Server

Before testing, make sure your backend is still running.

Now, instead of opening index.html directly, use the Live Server extension in VS Code.

If you don’t have it installed, just open VS Code extensions, search for “Live Server”, and then install it. Then right click on index.html and click “Open with Live Server”.

This starts a small local server for the frontend.

Why does this matter?

Many browser features work better when files are served through a server instead of opened directly from the file system. Using Live Server also matches how real frontends are served.

Testing the Full Application Locally

Now choose an image and click the button.

If everything is working:

• The image is sent to the backend

• The background is removed

• The result appears on the page

• The download link shows up

Take a moment here. You have just built:

• A backend that processes real data

• A frontend that talks to it

• A complete application running locally

This is already more than a “Hello World” project.

Clearing One More Misconception

Some beginners look at this and think: “This feels too simple to be a real app.”

This is another misconception. Real applications aren’t defined by complexity. They’re defined by usefulness. If your app solves a real problem and people can use it, it’s a real application.

In the next section, we’ll take this exact app and put it on the internet so anyone can use it.

Step 4: Putting the Backend on the Internet

Right now, your backend is running on your computer.

That means:

• It works only for you

• If you close your laptop, it stops

• If someone opens your frontend, it cannot reach your backend

To fix this, we need to run the backend on a computer that is always online.

This process is called deployment.

A Simple Way to Think About Deployment

Deployment does not mean writing new code.

It simply means this: instead of running your backend on your laptop, you run it on another computer that never sleeps.

Everything we do next exists only to make that happen.

Why We Aren’t Using Netlify or Vercel

You might be wondering why we aren’t using Netlify or Vercel. Those platforms are great, but they’re mainly for frontends.

They work best when your app is:

• Static HTML, CSS, and JavaScript

• A frontend framework like React or Vue

• Small serverless functions

Our backend is different. It’s a Python server that:

• Stays running

• Accepts image uploads

• Processes images

• Uses heavy native libraries for background removal

This kind of backend needs a real server, not a lightweight serverless function.

That’s why Netlify and Vercel aren’t a good fit here.

Why We’re Using Cloud Run

Instead, we’re using Cloud Run.

Cloud Run lets us run real backend servers on Google’s infrastructure without managing servers ourselves.

We’re using it because:

• It supports full Python backends

• It deploys directly from GitHub

• It handles scaling and servers for us

• It works well with heavy workloads

• It’s beginner-friendly

Most importantly, it lets you deploy a real backend without learning cloud commands or CI/CD pipelines.

Preparing the Backend for Cloud Run

Before deploying, we need to make sure our backend is ready.

Creating requirements.txt

Inside the backend folder, create a file called requirements.txt.

Add this:

fastapi
uvicorn
rembg
pillow
onnxruntime

This file tells Cloud Run which Python libraries to install.

Creating a GitHub Repository

Cloud Run deploys directly from GitHub, so our code must live there.

From the project root, run:

git init
git add .
git commit -m "Initial background remover project"
git branch -M main
git remote add origin YOUR_REPO_URL
git push -u origin main

This single repository will be used for both backend and frontend.

Deploying the Backend on Cloud Run

Now open your browser and go to Google Cloud Console.

1. Create a New Project

Open Google Cloud Console and click New Project. Give it a name (for example: background-remover) and then click Create.

2. Open Cloud Run

Use the search bar at the top and search for Cloud Run. Then open it.

Cloud Run will automatically enable the required APIs.

You will be asked to set up billing. Google gives you $300 free credit, which is more than enough for this tutorial.

3. Start Creating the Service

Click Create Service and choose Deploy continuously from a repository.

4. Connect Your GitHub Account

Select GitHub as the repository provider and authenticate your GitHub account. Then install Google Cloud Build on your GitHub account. Choose only the repository you want to deploy.

This allows Google Cloud to build and deploy your code automatically.

5. Select the Repository

Then choose the repository you just installed Cloud Build on and select the main branch.

6. Configure the Build

Now comes the important part: building the context directory.

Set this to:

backend

This tells Cloud Run:

“My backend code lives inside the backend folder.”

For the entry command, enter:

uvicorn api.main:app --host 0.0.0.0 --port 8080

This is how Cloud Run starts your FastAPI server.

7. Configure Container Resources

Our backend runs a background-removal model, which is heavy.

So we must increase resources.

• Change memory from 512 MB → 2 GB

• Set CPU to 4

This ensures the model can load and run properly.

8. Deploy

Now click Create.

Cloud Run will:

• Build your app

• Install dependencies

• Create a container

• Deploy it to the internet

You’ll see logs showing the build and deployment process.

This can take a few minutes. That’s normal.

Checking That the Backend Is Live

Once deployment finishes, Cloud Run will show you a public URL.

Test it:

curl https://YOUR_CLOUD_RUN_URL/health

If you see:

{"status":"ok"}

Your backend is officially live on the internet.

Pause here for a second.

You just deployed a real backend. Congratulations.

Updating the Frontend to Use the Live Backend

Open app.js.

Replace:

http://localhost:8000/remove-bg

With:

https://YOUR_CLOUD_RUN_URL/remove-bg

Save the file and reload the frontend.

Step 5: Making the Backend and Frontend Work Together

At this point, we have two things:

• A backend running on the internet

• A frontend running in the browser

Now we want them to talk to each other.

Open your frontend, select an image, and click the button. You’ll notice that it still doesn’t work. This is expected.

What Is Happening Here?

Your frontend is running on one address, while your backend is running on another address.

Browsers are very strict about this. By default, a browser will block requests from one website to another unless the backend explicitly allows it. This is a security feature.

This rule is called CORS.

Clearing a Common Misconception About CORS

When beginners see a CORS error, they often think something is broken.

Nothing is broken. CORS is simply the browser saying: “I need the backend to confirm that this frontend is allowed to talk to it.”

So all we need to do is tell the backend: “It’s okay for requests to come from my frontend.”

Allowing Only Our Frontend (Not Everyone)

Instead of allowing requests from everywhere, we’ll allow requests only from our frontend. This is a good habit to learn early.

Open backend/api/main.py.

Add this import at the top:

from fastapi.middleware.cors import CORSMiddleware

Then, after creating the FastAPI app, add this:

app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://127.0.0.1:5500",
        "http://localhost:5500"
    ],
    allow_methods=["POST"],
    allow_headers=["*"],
)

Why these URLs?

If you’re using the Live Server extension, your frontend is usually served on port 5500. These are the addresses your browser is using locally.

We’re telling the backend: “Only accept requests from this frontend.”

That is exactly what we want.

Redeploying the Backend

Any time you change backend code, you need to redeploy it.

Since our backend is deployed on Cloud Run and set up with automatic deploy, redeploying is simple, all you need to do is push your changes.

From the project root, run:

git add .
git commit -m "Add CORS configuration"
git push

Cloud Run will automatically detect the change and redeploy your backend.

Wait for the deployment to finish. Once it’s done, your backend will now allow requests from your local frontend.

Testing Again

Reload your frontend in the browser.

Select an image and click the button. This time, it should work.

You just handled a real browser security rule that every production app runs into. That alone is a huge learning step.

Step 6: Putting the Frontend on the Internet (GitHub Pages)

Right now, your frontend works only on your computer.

Just like the backend earlier, this means no one else can use it.

Let’s fix that.

Why GitHub Pages?

Our frontend is:

• Just HTML, CSS, and JavaScript

• No backend code

• No build step

This makes it perfect for GitHub Pages. GitHub Pages can host static sites for free, and it’s very beginner friendly.

Preparing the Frontend for Deployment

Make sure all your frontend files are inside the frontend folder:

frontend/
  index.html
  styles.css
  app.js

Open app.js and make sure the backend URL is the Cloud Run URL, not localhost.

fetch("https://YOUR_CLOUD_RUN_URL/remove-bg", {
  method: "POST",
  body: formData,
});

Save the file.

Pushing the Frontend to GitHub

We already created a GitHub repository earlier, so we’ll reuse it.

From the project root, run:

git add .
git commit -m "Add frontend and prepare for GitHub Pages"
git push

Enabling GitHub Pages

1. Go to your repository on GitHub.

2. Open Settings.

3. Click Pages.

Under Source, select:

1. Branch: main

2. Folder: /(root)

Save everything. After a few seconds, GitHub will give you a URL. This URL is now your frontend on the internet.

Updating CORS for the Live Frontend

Now that the frontend is live, go back to backend/api/main.py.

Replace the local origins with your GitHub Pages URL:

allow_origins=[
    "https://YOUR_GITHUB_USERNAME.github.io"
]

Commit and push the change:

git add .
git commit -m "Update CORS for GitHub Pages"
git push

Cloud Run will redeploy the backend automatically.

Final Test

Open your GitHub Pages URL.

Upload an image, remove the background, and download the result.

Everything is now live.

Where You Are Now

Let’s be very clear about what you just did.

You:

• Built a real backend

• Deployed it to the internet

• Built a frontend

• Deployed it to the internet

• Fixed real production issues

• Connected everything properly

This is not a demo project. This is a real application.

In the final section, we’ll wrap things up, talk about what you learned, and where you can go next.

Final Thoughts: What You Just Built Matters

At this point, it is worth stopping and looking back at what you have actually done.

You didn’t just follow steps. You didn’t just copy code. You built a real application.

Let’s Be Clear About What You Accomplished

You started with nothing more than basic tools and ideas.

By the end of this tutorial, you:

• Built a backend that processes real data

• Used a machine learning tool without fear or overthinking

• Exposed a backend to the internet

• Built a frontend with plain HTML, CSS, and JavaScript

• Connected the frontend and backend properly

• Deployed both parts so real users can access them

This is exactly how real applications are built, just at a smaller and more manageable scale.

Why This Is No Longer a “Beginner Project”

Many projects are called beginner projects, but they stop at showing things on a screen.

This one does not.

Your app:

• Accepts real input

• Performs real work

• Runs on real servers

• Handles real browser rules

• Can be shared with anyone

That is the difference between learning syntax and building software.

The Most Important Lesson in This Tutorial

The most important thing you should take away from this is not the project you built.

It is this: You didn’t need to “know more” before you started.

You learned by building. You figured things out as they appeared. You fixed problems when they showed up.

That is how experience is gained. No one has experience before building real applications. No one lacks experience after building many of them.

What You Can Do Next

This project isn’t the end. It’s a starting point.

Here are a few ideas you can explore next, using what you already know:

• Improve the user interface

• Add loading states and better feedback

• Restrict image size or file types

• Add simple rate limiting

• Build another small tool that solves a real problem

You don’t need to jump to frameworks yet.

If you can build a few more projects like this, frameworks will make a lot more sense when you meet them.

One Last Thought

If this was your first real project, you should be proud of yourself.

You moved past tutorials, built something useful, and put it on the internet. That’s the line many developers never cross.

Now that you have crossed it, the next one will be easier.

So keep building!

Source Code and Live Demo

If you want to explore the full project or build on top of it, you can find everything here.

• Live application: https://iamspruce.github.io/background-remover/

• GitHub repository: https://github.com/iamspruce/background-remover

If you have questions, reach me on X at @sprucekhalifa. I write practical tech articles like this regularly.

In Flutter, one of the most popular packages to manage permissions is permission_handler. This article will guide you through how to:

1. Install and set up permission_handler and fluttertoast

2. Request and handle different permissions

3. Understand what each permission does and its use cases

4. Handling Android and iOS configurations

5. Implement best practices

6. Handle testing permissions

7. Provide expected outcomes and conclusions

Table of Contents:

• Table of Contents:

• 1. Prerequisites

• 2. Installing Dependencies

• 3. Understanding Permission States

• 4. Reusable Permission Handling Function

• 5. Permissions, Their Use Cases, and Examples

  • 5.1 Calendar Permissions

  • 5.2 Camera Permission

  • 5.3 Contacts Permission

  • 5.4 Location Permissions

  • 5.5 Media Library (iOS only)

  • 5.6 Microphone Permission

  • 5.7 Phone Permission

  • 5.8 Photos Permissions

  • 5.9 Reminders Permission

  • 5.10 Sensors Permissions

  • 5.11 SMS Permission

  • 5.12 Speech Recognition Permission

  • 5.13 Storage Permissions

  • 5.14 Ignore Battery Optimizations

  • 5.15 Notifications

  • 5.16 Bluetooth Permissions

  • 5.17 App Tracking Transparency (iOS only)

• 6. Android Manifest Configuration

• 7. iOS Info.plist Configuration

• 8. Expected Outcomes

• Best Practices for Handling Permissions in Flutter

  • 1. Request only necessary permissions

  • 2. Explain why permissions are needed

  • 3. Use runtime permission requests

  • 4. Handle denial gracefully

  • 5. Handle permanent denials

  • 6. Test on both platforms

  • 7. Follow platform guidelines

  • 8. Avoid over-permissioning

  • 9. Use a centralized permission manager

  • 10. Monitor permission changes

• Conclusion

• References

1. Prerequisites

Before starting, ensure you have the following:

1. Flutter SDK installed (version 3.0.0 or higher recommended)

2. A code editor such as Android Studio or VS Code

3. Basic understanding of Flutter widgets, async/await in Dart, and state management

4. A physical device (recommended) or emulator/simulator

5. Internet connection to install dependencies

2. Installing Dependencies

To get started, add the following to your pubspec.yaml file:

dependencies:
  permission_handler: ^11.3.1
  fluttertoast: ^8.2.4

Then run:

flutter pub get

• permission_handler is used to request and check permissions on Android and iOS.

• fluttertoast allows you to display messages to users when permissions are granted or denied.

3. Understanding Permission States

When requesting permissions with permission_handler, you can get the following states:

1. isGranted – The permission is granted.

2. isDenied – The permission is denied, but can be requested again.

3. isPermanentlyDenied – The permission is permanently denied, meaning the user must enable it from app settings.

4. isRestricted – The permission is restricted by the system (common on iOS).

5. isLimited – Partial access granted (mainly iOS photo library).

4. Reusable Permission Handling Function

Instead of writing multiple functions for each permission, we’ll create a reusable function:

import 'package:permission_handler/permission_handler.dart';
import 'package:fluttertoast/fluttertoast.dart';

Future<void> handlePermission(Permission permission, String name) async {
  var status = await permission.request();

  if (status.isGranted) {
    Fluttertoast.showToast(msg: '$name permission granted');
  } else if (status.isPermanentlyDenied) {
    Fluttertoast.showToast(msg: '$name permission permanently denied. Enable it in settings.');
    openAppSettings();
  } else if (status.isRestricted) {
    Fluttertoast.showToast(msg: '$name permission restricted by system.');
  } else if (status.isLimited) {
    Fluttertoast.showToast(msg: '$name permission limited access granted.');
  } else {
    Fluttertoast.showToast(msg: '$name permission denied');
  }
}

Usage example:

await handlePermission(Permission.camera, "Camera");
await handlePermission(Permission.location, "Location");

5. Permissions, Their Use Cases, and Examples

Let’s now look at a bunch of different types of permissions you might have to enable in your Flutter apps. I’ll explain what the permission does and its common use cases as well.

5.1 Calendar Permissions

• Permission: calendar, calendarReadOnly, calendarFullAccess

• What it does: Accesses the user’s calendar to read or write events.

• Use case: Event apps, scheduling apps.

await handlePermission(Permission.calendar, "Calendar");

5.2 Camera Permission

• Permission: camera

• What it does: Access device camera for capturing photos/videos.

• Use case: QR scanning, photo apps, video recording.

await handlePermission(Permission.camera, "Camera");

5.3 Contacts Permission

• Permission: contacts

• What it does: Read or modify user contacts.

• Use case: Messaging apps, social networking apps.

await handlePermission(Permission.contacts, "Contacts");

5.4 Location Permissions

• Permission: location, locationAlways, locationWhenInUse

• What it does: Access user’s location.

• Use case: Navigation apps, ride-hailing apps, geofencing.

await handlePermission(Permission.locationWhenInUse, "Location");

5.5 Media Library (iOS only)

• Permission: mediaLibrary

• What it does: Access media files on iOS devices.

• Use case: Photo sharing apps, media editors.

await handlePermission(Permission.mediaLibrary, "Media Library");

5.6 Microphone Permission

• Permission: microphone

• What it does: Record audio.

• Use case: Voice notes, video calls, voice commands.

await handlePermission(Permission.microphone, "Microphone");

5.7 Phone Permission

• Permission: phone

• What it does: Access phone state, make calls, read call logs.

• Use case: Telephony apps, call management apps.

await handlePermission(Permission.phone, "Phone");

5.8 Photos Permissions

• Permission: photos, photosAddOnly

• What it does: Access or add photos to user library.

• Use case: Media apps, social apps.

await handlePermission(Permission.photos, "Photos");

5.9 Reminders Permission

• Permission: reminders

• What it does: Access and manage device reminders.

• Use case: To-do apps, productivity apps.

await handlePermission(Permission.reminders, "Reminders");

5.10 Sensors Permissions

• Permission: sensors, sensorsAlways

• What it does: Access device sensors like accelerometer or gyroscope.

• Use case: Fitness apps, motion tracking apps.

await handlePermission(Permission.sensors, "Sensors");

5.11 SMS Permission

• Permission: sms

• What it does: Read or send SMS messages.

• Use case: OTP verification, messaging apps.

await handlePermission(Permission.sms, "SMS");

5.12 Speech Recognition Permission

• Permission: speech

• What it does: Use speech-to-text features.

• Use case: Voice commands, dictation apps.

await handlePermission(Permission.speech, "Speech Recognition");

5.13 Storage Permissions

• Permission: storage, manageExternalStorage

• What it does: Access internal/external storage to read/write files.

• Use case: File managers, download managers.

await handlePermission(Permission.storage, "Storage");

5.14 Ignore Battery Optimizations

• Permission: ignoreBatteryOptimizations

• What it does: Request to exclude app from battery optimizations.

• Use case: Alarm apps, background services.

await handlePermission(Permission.ignoreBatteryOptimizations, "Battery Optimizations");

5.15 Notifications

• Permission: notification

• What it does: Allow sending notifications.

• Use case: Messaging, reminders, alerts.

await handlePermission(Permission.notification, "Notifications");

5.16 Bluetooth Permissions

• Permission: bluetooth, bluetoothScan, bluetoothAdvertise, bluetoothConnect

• What it does: Manage or connect to Bluetooth devices.

• Use case: Wearables, IoT devices, headphones.

await handlePermission(Permission.bluetooth, "Bluetooth");

5.17 App Tracking Transparency (iOS only)

• Permission: appTrackingTransparency

• What it does: Request tracking permission for personalized ads.

• Use case: Analytics, advertising, user tracking.

await handlePermission(Permission.appTrackingTransparency, "App Tracking");

6. Android Manifest Configuration

On Android, all apps must declare the permissions they intend to use in the AndroidManifest.xml file. This acts as the app’s “contract” with the system, letting Android know what sensitive resources (like internet, location, camera) the app might request.

Without declaring these in the manifest, runtime permission requests will fail, even if you’ve added the permission_handler package.

For example, if you try to access the camera without first declaring the camera permission here, your app will crash or fail when requesting it at runtime.

Below is a comprehensive list of common permissions:

<!-- Camera access for taking pictures or recording videos -->
<uses-permission android:name="android.permission.CAMERA" />

<!-- Read user contacts (e.g., for social features, friend finder) -->
<uses-permission android:name="android.permission.READ_CONTACTS" />

<!-- Fine-grained location (GPS) for maps, navigation, geofencing -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!-- Coarse location (network-based, less accurate, uses WiFi/Cell) -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

<!-- Record audio from the microphone (e.g., voice notes, calls) -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />

<!-- Read external storage (access user’s files like images, docs) -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

<!-- Write to external storage (save downloaded files, photos) -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

<!-- Send SMS directly from the app -->
<uses-permission android:name="android.permission.SEND_SMS" />

<!-- Receive SMS (read OTP messages for login/verification) -->
<uses-permission android:name="android.permission.RECEIVE_SMS" />

<!-- Read SMS messages (OTP autofill, chat backup restore) -->
<uses-permission android:name="android.permission.READ_SMS" />

<!-- Bluetooth usage (connect to Bluetooth devices like headsets, printers) -->
<uses-permission android:name="android.permission.BLUETOOTH" />

<!-- Bluetooth Admin (manage paired devices, discover nearby devices) -->
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

<!-- Bluetooth Scan (needed from Android 12+) -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />

<!-- Bluetooth Connect (needed from Android 12+) -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

<!-- Bluetooth Advertise (for beacon-style apps, Android 12+) -->
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />

<!-- Ignore battery optimizations (keep app alive in background tasks) -->
<uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />

<!-- Internet access (needed for network requests, APIs, file uploads) -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- Check if a network connection exists (WiFi/Mobile data) -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Access WiFi state (check SSID, connection info, used for network control) -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

<!-- Change WiFi state (enable/disable WiFi programmatically) -->
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />

<!-- Access phone state (read device ID, SIM details, call status) -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

<!-- Make phone calls directly from the app -->
<uses-permission android:name="android.permission.CALL_PHONE" />

<!-- Use fingerprint authentication (for biometric login) -->
<uses-permission android:name="android.permission.USE_FINGERPRINT" />

<!-- Use Biometric authentication (newer than fingerprint, includes face) -->
<uses-permission android:name="android.permission.USE_BIOMETRIC" />

7. iOS Info.plist Configuration

For iOS, you must provide descriptive keys in the Info.plist file to inform users why your app needs specific permissions. Below are the configurations for each permission example:

1. Camera Permission

    <key>NSCameraUsageDescription</key>
    <string>We need access to your camera for taking pictures.</string>
   

2. Contacts Permission

    <key>NSContactsUsageDescription</key>
    <string>We need access to your contacts for better communication.</string>
   

3. Location Permissions

    <key>NSLocationWhenInUseUsageDescription</key>
    <string>We need access to your location to provide location-based services.</string>
    <key>NSLocationAlwaysUsageDescription</key>
    <string>We need access to your location to track your movement even when the app is not active.</string>
   

4. Media Library/Storage Permission

    <key>NSPhotoLibraryUsageDescription</key>
    <string>We need access to your photos for sharing or uploading media.</string>
   

5. Microphone Permission

    <key>NSMicrophoneUsageDescription</key>
    <string>We need access to your microphone for voice recording.</string>
   

6. Phone Permission

    <key>NSPhoneUsageDescription</key>
    <string>We need access to phone services to enable calls.</string>
   

7. Photos Permission

    <key>NSPhotoLibraryAddUsageDescription</key>
    <string>We need permission to add photos to your library.</string>
   

8. Reminders Permission

    <key>NSRemindersUsageDescription</key>
    <string>We need access to your reminders for task management.</string>
   

9. Sensors Permission

    <key>NSSensorsUsageDescription</key>
    <string>We need access to your sensors for fitness tracking.</string>
   

10. SMS Permission (Handled automatically by iOS if SMS services are requested)

11. Speech Recognition Permission

<key>NSSpeechRecognitionUsageDescription</key>
<string>We need access to speech recognition for voice commands.</string>

12. Ignore Battery Optimizations (Not applicable on iOS)

13. Notifications Permission

<key>NSUserNotificationUsageDescription</key>
<string>We need permission to send notifications.</string>

14. Access Media Location Permission (Handled automatically on iOS)

15. Activity Recognition Permission

<key>NSMotionUsageDescription</key>
<string>We need access to motion data for fitness tracking.</string>

16. Bluetooth Permissions

<key>NSBluetoothPeripheralUsageDescription</key>
<string>We need access to Bluetooth for device connectivity.</string>

17. App Tracking Transparency

<key>NSUserTrackingUsageDescription</key>
<string>We need permission to track your activity across apps and websites for personalized ads.</st

8. Expected Outcomes

By implementing permissions and connectivity checks this way, your Flutter app will:

1. Request permissions dynamically at runtime in a user-friendly way.

2. Handle all possible states gracefully, including granted, denied, permanently denied, restricted, and limited.

3. Provide users with meaningful feedback, guiding them to settings if necessary.

4. Maintain compliance with Android and iOS permission policies while ensuring security and transparency.

5. Listen continuously to network connectivity changes via the global BLoC listener.

6. Notify users instantly with a toast/snackbar whenever internet status changes (connected/disconnected).

7. Reduce redundant API calls and improve UX by avoiding “fake” offline or cached-only states.

Best Practices for Handling Permissions in Flutter

There are some common best practices you should follow when handling permissions in Flutter.

1. Request only necessary permissions

Ask only for the permissions your app truly needs. For example, if your app just uploads images, you probably only need storage/photos access, not location, contacts, or SMS.

final status = await Permission.photos.request();
if (status.isGranted) {
  // Proceed with photo upload
}

2. Explain why permissions are needed

Always tell the user why you’re asking for a sensitive permission before the system dialog appears. This helps build trust.

Example of a custom dialog before requesting:

Future<void> _showPermissionRationale(BuildContext context) async {
  showDialog(
    context: context,
    builder: (context) => AlertDialog(
      title: Text("Camera Access Needed"),
      content: Text("We need access to your camera so you can take profile photos."),
      actions: [
        TextButton(
          onPressed: () {
            Navigator.pop(context);
            Permission.camera.request();
          },
          child: Text("Allow"),
        ),
        TextButton(
          onPressed: () => Navigator.pop(context),
          child: Text("Cancel"),
        ),
      ],
    ),
  );
}

3. Use runtime permission requests

On Android 6.0+ and iOS, permissions must be requested at runtime (not just declared in AndroidManifest.xml or Info.plist).

final status = await Permission.location.request();
if (status.isGranted) {
  // Use location
}

4. Handle denial gracefully

Don’t block the entire app when permissions are denied. Provide alternative flows.

For example, instead of forcing camera access:

if (await Permission.camera.isDenied) {
  // Offer file upload as fallback
  _pickImageFromGallery();
}

This way, users can still use your app without being forced.

5. Handle permanent denials

When a user selects “Don’t ask again” (Android) or disables a permission in Settings (iOS), you should guide them to Settings.

if (await Permission.camera.isPermanentlyDenied) {
  openAppSettings(); // Takes user to app settings
}

UX Example:

• Show a snackbar: “Camera access is required. Enable it in Settings.” with a Go to Settings button.

6. Test on both platforms

Permissions behave differently across Android and iOS. Example:

• iOS may return limited photo library access.

• Android 13+ has new granular media permissions (READ_MEDIA_IMAGES, READ_MEDIA_VIDEO).

Always test all scenarios:

• Granted

• Denied once

• Denied permanently

• Limited (iOS only)

7. Follow platform guidelines

Make sure your manifest and Info.plist contain clear explanations.

Info.plist example (iOS):

<key>NSCameraUsageDescription</key>
<string>This app requires camera access to let you take profile pictures.</string>

This is required for App Store approval.

8. Avoid over-permissioning

Example: Don’t request SMS if you only need phone number autofill. Users will abandon your app if they see irrelevant requests.

Bad:

<uses-permission android:name="android.permission.SEND_SMS" />

Just use READ_PHONE_NUMBERS if that’s the actual need.

9. Use a centralized permission manager

Instead of scattering requests across the app, create a PermissionService that handles all requests consistently.

class PermissionService {
  Future<bool> requestCamera() async {
    final status = await Permission.camera.request();
    return status.isGranted;
  }

  Future<bool> requestLocation() async {
    final status = await Permission.location.request();
    return status.isGranted;
  }
}

This keeps permission handling uniform.

10. Monitor permission changes

Permissions can change while the app is open (user goes to Settings and disables it). Always check before use.

@override
void initState() {
  super.initState();
  Timer.periodic(Duration(seconds: 5), (timer) async {
    final cameraStatus = await Permission.camera.status;
    if (!cameraStatus.isGranted) {
      // Disable camera UI
    }
  });
}

Conclusion

Permissions are fundamental for building fully functional and secure mobile applications. Using permission_handler in Flutter allows you to manage permissions across Android and iOS efficiently.

And just remember: always request only necessary permissions, provide clear explanations, and handle all possible states to maintain trust with users.

By combining correct permission logic with proper AndroidManifest and Info.plist setup, you ensure a seamless user experience while staying compliant with platform guidelines.

References

1. permission_handler Flutter Package Documentation

2. Flutter Official Documentation: Handling Permissions

3. Android Developer Guide: Permissions

4. iOS Developer Guide: App Permissions

5. Fluttertoast Package Documentation

By the end, you'll have a fully functional MCP server integrated with Claude Desktop in about 10 minutes. This solution applies to any MCP setup facing this standard error after Python upgrades.

Table of Contents

1. What Causes the ENOENT Error?

2. Prerequisites

3. How to Diagnose Your Broken Virtual Environment

4. How to Completely Rebuild Your Virtual Environment

5. How to Install MCP Server Dependencies

6. How to Locate Your Server Files

7. How to Test Your Server Setup

8. How to Configure Claude Desktop

9. How to Restart Claude Desktop and Test Integration

10. Understanding MCP Server Capabilities

11. Alternative Installation Methods

    • Method 1: Direct Package Installation

    • Method 2: Using UV Package Manager

12. How to Prevent Future ENOENT Errors

13. Troubleshooting Common Issues

14. Conclusion

What Causes the ENOENT Error?

The ENOENT (Error NO ENTry) error means your system can’t locate the Python executable at the specified path. This occurs when the file is missing or inaccessible.

On macOS, this typically happens when:

• You've upgraded Python through Homebrew

• The brew cleanup command removed old Python versions

• Your virtual environment's symlinks now point to non-existent files

What makes this particularly challenging is that your virtual environment folder still exists – it looks fine from the outside, but the Python executable inside is completely broken.

When MCP servers try to spawn Python processes using these broken paths, you get the dreaded ENOENT error. This affects any Python-based MCP server, whether you're building custom tools, connecting to APIs, or working with file systems.

Prerequisites

To follow this tutorial, you'll need:

• macOS with Homebrew installed

• Python 3.10 or higher

• An MCP server repository cloned locally

• Claude Desktop installed

• Basic familiarity with terminal commands and Python virtual environments

If you haven't cloned an MCP server repository yet, you can start with any open-source MCP server. For this tutorial, I'll use generic examples that work with any MCP setup:

git clone https://github.com/your-username/your-mcp-server.git
cd your-mcp-server

How to Diagnose Your Broken Virtual Environment

First, you need to confirm that your virtual environment is actually the problem. Open your terminal and navigate to your MCP directory:

cd /path/to/your/mcp-server

Now check if your Python executable exists:

ls -la venv/bin/python*

If you see broken symlinks or get "No such file or directory" errors, you've found your problem. You might see output like:

lrwxr-xr-x  1 username  staff  16 Jan  1 12:00 python -> /usr/local/bin/python3.11
lrwxr-xr-x  1 username  staff  16 Jan  1 12:00 python3 -> /usr/local/bin/python3.11

But when you try to run these Python executables:

./venv/bin/python --version

You'll get an error because the target files no longer exist. This confirms your virtual environment is broken and needs rebuilding.

How to Completely Rebuild Your Virtual Environment

The most reliable solution is to rebuild your virtual environment from scratch. This ensures all paths and dependencies are correctly configured for your current Python installation.

Here's your step-by-step rebuild process:

# Make sure you're in the MCP server directory
cd /path/to/your/mcp-server

# Remove the corrupted virtual environment
rm -rf venv

# Create a fresh virtual environment
python3 -m venv venv

# Activate the new environment
source venv/bin/activate

You should now see (venv) in your terminal prompt, indicating the virtual environment is active. This prefix confirms you're working within the isolated Python environment.

How to Install MCP Server Dependencies

With your fresh virtual environment active, install the MCP server and its dependencies. The exact installation command depends on your specific MCP server, but typically follows one of these patterns:

# For package-based installation
pip install -e .

# Or for requirements file
pip install -r requirements.txt

# Or for specific MCP frameworks
pip install fastmcp

Common MCP server dependencies include:

• FastMCP for the server framework

• JSON-RPC libraries for communication protocols

• HTTP clients for API integrations

• File system utilities for local operations

The installation process displays all packages as they install. Don't worry if you see deprecation warnings – they're normal and won't affect functionality.

How to Locate Your Server Files

After installation, identify where your main server file lives. Run this command to find all server.py files:

find . -name "server.py" -type f

You may see results like:

• ./server.py (in the root directory)

• ./src/server.py (in a source directory)

• ./mcp_server/server.py (in a package directory)

Check your current directory structure:

ls -la

Look for the main server entry point. Most MCP servers follow standard Python project structures with either a root-level server file or one nested in a package directory.

How to Test Your Server Setup

Now you’ll want to test your server to ensure it's working correctly. Start with the main server file you identified:

python server.py

If this is the correct server and everything is configured correctly, you'll see output similar to:

╭─ MCP Server ───────────────────────────────────────────────────────────────╮
│ 🖥️  Server name: Example-MCP                                              │
│ 📦 Transport: STDIO                                                        │
│ 🤝 Protocol: JSON-RPC                                                      │
╰────────────────────────────────────────────────────────────────────────────╯
[INFO] Starting MCP server with transport 'stdio'
[INFO] Server ready for connections

This output confirms your MCP server is working correctly. The server uses standard input/output (STDIO) for communication, which is perfect for Claude Desktop integration. You can stop the server with Ctrl+C.

How to Configure Claude Desktop

Now that your server runs properly, configure Claude Desktop to connect to it. The configuration file location depends on your operating system:

For macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

For Windows:

%APPDATA%\Claude\claude_desktop_config.json

For Linux:

~/.config/Claude/claude_desktop_config.json

Create or edit this file with your exact paths. Your configuration should look like this:

{
  "mcpServers": {
    "example-mcp": {
      "command": "/Users/yourusername/path/to/mcp-server/venv/bin/python",
      "args": ["/Users/yourusername/path/to/mcp-server/server.py"],
      "cwd": "/Users/yourusername/path/to/mcp-server"
    }
  }
}

Replace /Users/yourusername/path/to/mcp-server/ with your actual path. You can get your precise path by running pwd in your MCP server directory.

The configuration tells Claude Desktop:

• Which Python interpreter to use (from your virtual environment)

• Where to find the server script

• Which directory to run the server from

How to Restart Claude Desktop and Test Integration

After saving your configuration file, altogether quit Claude Desktop (not just close the window). On macOS, use Cmd+Q or right-click the dock icon and select Quit. Then restart Claude Desktop.

Once Claude Desktop is running again, test your MCP integration. You can verify the connection by:

1. Looking for your MCP server name in Claude's interface

2. Testing basic MCP functionality with prompts like:

   • "What MCP tools are available?"

   • "Can you check the MCP server status?"

   • "Show me the available MCP commands"

If everything is working correctly, Claude will respond using the MCP server tools, confirming successful integration.

Understanding MCP Server Capabilities

MCP servers extend Claude's capabilities by providing structured access to external tools and data sources. Common MCP server implementations include:

1. File system operations: MCP servers can provide controlled access to local files, allowing Claude to read, analyze, and process documents while maintaining security boundaries.

2. API integrations: Connect Claude to external services through MCP servers that handle authentication, rate limiting, and data formatting for various APIs.

3. Database connections: Query databases safely through MCP servers that manage connections, handle credentials securely, and format results for Claude's consumption.

4. Custom tools: Build specialized tools for your workflow, from code analysis to data processing, all accessible through the standardized MCP interface.

The beauty of MCP is its flexibility – you can create servers for virtually any tool or service you need Claude to interact with.

Alternative Installation Methods

If you want more streamlined approaches for future setups, here are two excellent alternatives:

Method 1: Direct Package Installation

For MCP servers available as packages, you can install directly:

pip install mcp-server-package

Then use this simpler configuration:

{
  "mcpServers": {
    "example-mcp": {
      "command": "mcp-server-command"
    }
  }
}

This method works when the MCP server provides a command-line entry point through its setup configuration.

Method 2: Using UV Package Manager

UV provides more robust dependency management – perfect if you're tired of Python version conflicts:

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Use UV in your configuration
{
  "mcpServers": {
    "example-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--with", "fastmcp",
        "python",
        "/path/to/mcp-server/server.py"
      ],
      "cwd": "/path/to/mcp-server"
    }
  }
}

UV automatically manages Python versions and dependencies, reducing the likelihood of environment-related errors.

How to Prevent Future ENOENT Errors

To avoid this issue in the future, follow these best practices:

1. Use Virtual Environment Copies Instead of Symlinks

When creating virtual environments, use the --copies flag:

python3 -m venv venv --copies

This creates actual copies of files instead of symlinks, making your environment more resilient to Python upgrades.

2. Pin Your Homebrew Python Version

Prevent automatic Python upgrades that break environments:

brew pin python@3.11

Remember to unpin when you're ready to upgrade intentionally.

3. Create a Health Check Script

Save this script as health_check.sh in your MCP server directory:

#!/bin/bash
# health_check.sh
echo "Checking Python virtual environment..."
source venv/bin/activate

python -c "import sys; print(f'Python: {sys.executable}')"
python -c "print('✓ Python is working')"

# Check for common MCP dependencies
python -c "import json; print('✓ JSON module available')"
python -c "import asyncio; print('✓ Asyncio available')"

echo "Health check complete!"

Make it executable and run it periodically:

chmod +x health_check.sh
./health_check.sh

4. Document Your Python Version

Create a .python-version file in your project:

python --version > .python-version

This helps you remember which Python version the project was built with.

Troubleshooting Common Issues

Even with the fix applied, you might encounter these challenges:

Import Errors

If you see import-related errors, ensure all dependencies are installed:

source venv/bin/activate
pip list  # Check installed packages
pip install -r requirements.txt  # Reinstall if needed

Permission Denied Errors

Make sure your server file is executable:

chmod +x server.py

Claude Desktop Not Finding the Server

Double-check your configuration paths are absolute, not relative:

# Good - absolute path
"/Users/username/projects/mcp-server/server.py"

# Bad - relative path
"./server.py"

Server Starts, But Claude Can't Connect

Verify that the transport method matches between your server and the configuration. Most MCP servers use STDIO, but some might use HTTP or WebSocket transports.

Multiple Python Installations

If you have multiple Python versions, be explicit about which one to use:

# Check available Python versions
ls -la /usr/local/bin/python*

# Use a specific version
/usr/local/bin/python3.11 -m venv venv

Conclusion

You've successfully fixed the "spawn python ENOENT" error by rebuilding your Python virtual environment and properly configuring your MCP server for Claude Desktop. You've also learned how to prevent future mistakes and troubleshoot common issues.

With your MCP server running smoothly, you can now:

• Build custom tools that extend Claude's capabilities

• Create integrations with your favorite services

• Develop specialized workflows for your specific needs

• Share your MCP servers with the community

The MCP ecosystem is growing rapidly, with new servers and tools being developed constantly. Whether you're building file system tools, API integrations, or custom utilities, you now have the foundation to create and maintain robust MCP servers.

Happy building, and enjoy your error-free development journey! For more tutorials, follow my work on GitHub.

Then I joined a real team.

Suddenly, I was introduced to this thing called Kanban – and I realized I’d been treating software like a solo art project, not a process.

If that sounds familiar, you’re in the right place.

This guide will walk you through how Kanban actually works, how developers use it to track and prioritize work, and how it can help you stay sane when juggling bugs, features, and real-world deadlines.

Without further delay, lets get into it.

Here’s what we’ll cover:

• So… What Is Kanban?

• The Classic Kanban Board: Three Simple Columns

• How Developers Use Kanban in Real Life

• Kanban vs Scrum: What’s the Difference?

• So which one should you use Scrum or Kanban?

• What Tools Do Teams Use for Kanban?

• How to Use Kanban to Manage Your Own Coding Projects

• Final Thoughts: Why Kanban Isn’t Just a Board

So… What Is Kanban?

At its core, Kanban is a visual way to manage work. It helps teams (or team members) see:

• What needs to get done

• What’s in progress

• What’s finished

• Where things are getting stuck

The concept comes from lean manufacturing, but in tech, it’s often used in Agile teams that need flexibility without the structure of Scrum sprints.

Think of Kanban like a whiteboard that tells a story. Not just what’s done, but how work flows.

The Classic Kanban Board: Three Simple Columns

So what exactly is a Kanban board? At its core, it’s a visual representation of your workflow – a board that shows all the work your team (or you, solo warrior) are juggling, and where each task stands.

It can be physical, like an actual whiteboard with sticky notes that move from one column to the next. Or digital, using tools like Trello, Jira, GitHub Projects, or Notion. The key is that it’s visual and up-to-date. You can walk into a room or open a tab and instantly understand: What’s being worked on? What’s ready to go? Where are things stuck?

It’s like having your brain on a wall, but organized. And slightly less chaotic.

The beauty of Kanban is how dead simple it is to get started. At minimum, your board has three columns:

Each task – or card – moves from left to right as it gets worked on.

Let’s say your team is building a blog platform. Your Kanban board might have cards like:

• “Create signup form”

• “Fix image upload bug”

• “Deploy staging build”

Now, while Kanban is flexible, it can absolutely be taken too far.

I’ve seen boards with more columns than a Greek temple: “Needs Review,” “Pending Client Feedback,” “QA Rework Round 2,” “Blocked but Still Hopeful,” “In Existential Limbo,” and so on. Every card had six tags, three owners, two checklists, and one migraine.

The lesson? Don’t turn your board into a bureaucratic jungle.

You don’t need to account for every edge case. Start simple: “To Do,” “In Progress,” “Review,” “Done.” These basic stages cover most workflows. If you discover a real need for something more – like a dedicated “QA” column or “Blocked” column – add it intentionally, not because you feel like your board needs to look fancy.

Remember: A Kanban board should be helpful, not overwhelming. If you spend more time managing the board than doing the work on it… it’s doing the opposite of what it’s meant to do.

How Developers Use Kanban in Real Life

Here’s how you might interact with a Kanban board on a dev team:

1. You pick up a card from “To Do” – let’s say, “Add dark mode toggle.”

2. You move it to “In Progress.”

3. When it’s ready for review, you might move it to a temporary “Review” or “Testing” column.

4. Once it’s merged, tested, and deployed, you move it to “Done.”

5. You smile, drink some coffee, and grab the next card.

That’s it. But over time, this process helps the whole team:

• Spot bottlenecks

• Prevent duplicate work

• Reduce context switching

• Keep everyone aligned

What’s a WIP Limit — And Why Should You Care?

WIP = Work In Progress. This is the most important concept to keep us in check.

One of Kanban’s key principles is limiting how many things you’re working on at once. Because guess what? Multitasking kills momentum.

A typical WIP limit might look like:

• No more than 2–3 cards per person in “In Progress” Again this is best practice, but folks do pick up a lot and then they end up being the bottleneck.

• No more than 5 tasks waiting on QA.

Why? Because when everything’s urgent, nothing gets done. WIP limits force you to finish one thing before you start more – and that’s how real velocity happens.

If there are more than 5 tasks in the “To Do” column, the team doesn’t take up new ones. Instead, everyone chips in to see how they can help unclog the bottleneck. A bottleneck is your worst enemy in Kanban, and you want to resolve it so items move smoothly on time and on target.

Here’s a video recapping key concepts.

Kanban vs Scrum: What’s the Difference?

You’ve probably heard Scrum and Kanban mentioned in the same breath – and both are popular Agile frameworks. But they’re not interchangeable.

Scrum is structured, with roles like Product Owner and Scrum Master, and work gets organized into time-boxed sprints. It’s perfect for teams that benefit from rhythm and rituals – like sprint planning, daily standups, and retrospectives.

Kanban, on the other hand, is a little looser. No official roles, no set sprint timelines. Work flows continuously, and change can happen anytime. It’s perfect for teams who need more flexibility and fewer ceremonies.

So how do they compare in practice? Let’s break it down:

Bottom line:

• Scrum is a scheduled loop. Kanban is a living flow.

• One’s a playbook. The other’s a status window.

Here’s a video on the main differences between Scrum and Kanban you can watch if you want more detail.

So which one should you use Scrum or Kanban?

So… which one should you use?

It really depends on your team, your product, and your pain points.

✔️ If you’re working on a brand-new product where requirements shift a lot, and your team thrives with structure and routines – Scrum is likely the better fit. Sprints give you a sense of pacing, and ceremonies help ensure alignment.

✔️ If you’re managing ongoing work like bug triage, tech debt, infrastructure tasks, or anything that’s more “whenever it comes in” than “we need to ship this in two weeks” – Kanban gives you flexibility and visibility without the overhead.

And yes, there’s such a thing as Scrumban – a hybrid approach where teams use visual boards and WIP limits from Kanban, but keep some of Scrum’s structure like standups and retros. It’s like Agile tapas: you get the flavors that work best for your appetite.

Here is a detailed video that’'ll teach you more about how Scrumban works in practice.

Watch the Scrumban video only when you are familiar and comfortable with both Scrum and Kanban – otherwise, you might get confused from the cross-pollination of ideas and frameworks.

I personally have never seen a Scrumban implementation thats scaled well – too many folks trying too many things and none of them work. But thats just based on my experience – it may work for you and your team. I’ll let you be the judge.

What Tools Do Teams Use for Kanban?

You’ve probably seen (or used) one already:

• Trello – Simple and great for solo or small teams

• Jira – Enterprise-level, customizable workflows

• GitHub Projects – Lightweight but powerful for devs

• ClickUp / Asana / Notion – Integrated with docs/tasks

Kanban isn’t tied to any one tool – you can use an app, a browser tab, or a whiteboard and a pack of sticky notes from the office supply closet. What matters is how you use it. But let’s walk through some of the most common tools and what they offer in a Kanban context:

🟩 Trello

Trello is probably the easiest way to start with Kanban. It gives you a simple digital board with columns and cards you can drag and drop. It’s great for devs or small teams who don’t need tons of automation – just a clean place to track work visually.

🟨 Jira

Jira is a heavyweight – and while it’s built for Scrum, it also supports robust Kanban boards. You can define custom workflows, use built-in reports like cumulative flow diagrams, enforce WIP limits, and manage team velocity. Ideal for large teams that need traceability, integrations, and permissions.

🟦 GitHub Projects

If your code lives in GitHub, GitHub Projects is a clean way to stay close to your codebase. It lets you create Kanban-style boards with issues and pull requests as cards, so you’re never toggling between tools just to track what’s in progress.

🟧 ClickUp / Asana / Notion

These are all-in-one productivity platforms. They combine Kanban boards with documentation, team chat, calendars, and reporting. If your team needs more than just “move card left to right,” these tools let you manage projects, meetings, notes, and workflows in one place.

🟪 Whiteboard + Sticky Notes

Don’t underestimate the analog approach. It’s fast. It’s visible. It’s tactile. Physically moving a task from “Doing” to “Done” gives you a sense of progress no digital tool can match. And when something’s blocked? Slap a red sticky on it and call it a day.

Bottom line: The best tool is the one your team will actually use. Fancy doesn’t beat consistent. And the actual tool doesn’t matter as much as the discipline your team has to actually use it.

How to Use Kanban to Manage Your Own Coding Projects

Even if you're not on a team yet, Kanban is great for your own workflow. Here’s how you can use it to help yourself out:

1. Create a basic 3-column board (To Do, In Progress, Done)

2. Write out every task, big or small

3. Set a WIP limit (for example, no more than 2 tasks at once)

4. Update it daily. Make it a ritual.

5. Review your flow weekly – What got stuck? What moved fast?

Example:

You’ll be shocked how much clearer your thinking gets when you can see your work. It’s simple but super powerful to visualize your work it in this way.

Final Thoughts: Why Kanban Isn’t Just a Board

Kanban isn’t just a tool – it’s a mindset.

It helps you focus. It helps your team collaborate. And it gives everyone – even non-technical folks – visibility into what’s going on.

If you’re learning to code and want to feel more confident working with others, learning Kanban is low-effort, high-impact.

So don’t wait until your first job. Start using it now – and show up to that standup with confidence.

I hope this small 101 Guide to Kanban was helpful to you all. My sole purpose to write this was to help beginner developers understand Kanban as a practical workflow system – especially for those transitioning from solo coding to collaborative, real-world development environments. It aims to demystify the methodology in a casual, beginner-friendly tone while still offering actionable guidance.

I hope you enjoyed my beginners guide to Kanban.

Until next time, keep Learning, Unlearning and Relearning, folks….

This is where constructors come into play. Constructors are special types of methods with no return type. They are basically used to initialise the object, to set up its internal state, or to assign default values to its attributes.

In this tutorial, we will go deep into the topic of constructors in Java. You’ll learn how they work and why they are essential in object creation and Java programming. By the end, I hope you’ll understand why they’re one of the core concepts of OOP.

Let’s start…

Prerequisites

You don’t need to know anything too advanced to start learning about constructors in Java. Just a basic understanding of Java syntax, classes, objects, methods, parameters, arguments, and access modifiers is enough to get started.

What we’ll cover:

• What are Constructors in Java?

  • Constructor syntax:

• Types of Constructors

  • Default Constructor

  • No Argument constructor

  • Parameterised Constructor

  • Copy Constructor

• What Happens Behind the Scenes When a Constructor Is Called in Java?

• How to Use the return Keyword in Constructors

  • Sample Code:

  • Example:

• Conclusion

• Frequently Asked Questions

What are Constructors in Java?

As mentioned above, constructors are special types of methods that:

1. do not have a return type (not even void),

2. have the same name as the class

3. are called automatically when an object is created using the new keyword.

A constructor’s main purpose is to initialise a newly created object, to set up its internal state, or to assign default values to its attributes.

Constructors can also be understood as a special block of code which is called when an object is created – either automatically or manually by hard-coding it – with the values we want to initialise the object with.

If we’re okay with the object using default values (like 0 for numbers or null for objects), Java will handle that for us automatically. But if we want to give the object specific values when it's created, we need to write a constructor that takes those values as parameters and uses them to set up the object.

Constructor syntax:

class ClassName {

    // Default constructor with access modifier
    [access_modifier] ClassName(parameters...) {
        // constructor body
    }

}

Examples

When the constructor is not defined explicitly

class Car {

    String brand;
    int year;

    // No constructor is defined, so Java provides a default one
}

public class Main {

    public static void main(String[] args) {

        Car car1 = new Car();  // Java calls the default constructor

        // Default values: brand = null, year = 0
        System.out.println("Brand: " + car1.brand);
        System.out.println("Year: " + car1.year);
    }
}

Output:

In the above code, we have a Car class with two variables:

1. brand of type String

2. year of type int

Since a class is just a blueprint, we need to create an object to actually use it. This is done in the Main class. When we create a Car object using new Car(), Java looks for a constructor. Because we didn’t define one, the compiler automatically provides a default constructor (one with no arguments).

This allows us to create the object and print its variables without any errors. The values printed will be the default ones — null for the String, and 0 for the int.

We'll dive deeper into how this works behind the scenes later, step by step, so it becomes easier to understand.

When we have defined a constructor

public class Car {

    String brand;
    int year;

    // Constructor with parameters to initialize custom values
    public Car(String brandName, int modelYear) {
        brand = brandName;
        year = modelYear;
    }
}

public class Main {

    public static void main(String[] args) {

        Car car2 = new Car("Toyota", 2022);  // Custom values

        System.out.println("Brand: " + car2.brand);
        System.out.println("Year: " + car2.year);
    }
}

Output

This is the same code as before, with one key difference: this time, we’ve explicitly defined a constructor. Because of this, the output we see isn’t the default values (null for String, 0 for int), but the custom values we provided.

How does that happen? Simple – we pass values as arguments when creating the object:

Car car2 = new Car("Toyota", 2022);

These values are received by the constructor as parameters and are then used to initialize the object’s variables. As a result, instead of default values, we get the brand and year we specified.

Types of Constructors

There are mainly four types of constructors:

1. Default Constructors

2. No-Arguments Constructor

3. Parameterised Constructor

4. Copy Constructor

Default Constructor

A type of no-argument constructor that is added by the compiler during the compilation process so that the values of the object can be initialised. It’s only added by the compiler if you don’t add one explicitly.

Syntax:

public class MyClass {

    public MyClass() {
        // Constructor body
    }

}

Example

public class Bike {

    // No constructor defined here
    // Compiler will automatically add a default constructor

    public static void main(String[] args) {
        Bike myBike = new Bike();  // Calls the compiler-provided default constructor
        System.out.println("Bike object created!");
    }

}

The code becomes the following after the compiler adds a default constructor during the compilation process:

public class Bike {

    // Compiler-added default constructor
    public Bike() {
        super();  // Calls Object class constructor
    }

    public static void main(String[] args) {
        Bike myBike = new Bike();  // Now calls this explicit default constructor
        System.out.println("Bike object created!");
    }

}

Output

Bike object created!

No Argument constructor

No-argument constructor is a type of constructor that you explicitly write in your code and that does not contain any parameters.

Now, you may be wondering…Isn't it the same as the default constructor? The answer is both yes and no.

There isn’t much difference between the default constructor and the no-argument constructor, as both do not take any parameters. But there is one key difference.

The default constructor, as we have already discussed, is a type of no-argument constructor that is automatically added by the compiler when it doesn’t find one in our code. In contrast, a no-argument constructor is a type of constructor that we write in our code.

In short, if the compiler is the one that is adding a constructor during the compilation process, it's called a default constructor. But if we are the ones adding the constructor, it’s called a no-argument constructor.

The main difference between a default constructor and a user-defined constructor is how they are created and what they do.

• A default constructor is automatically added by the compiler if we don’t add one ourselves. It doesn’t do much – it just calls the parent class (usually the Object class) and sets all variables to their default values. For example, int becomes 0and objects become null.

• A user-defined constructor is one that we write ourselves. We can add custom logic inside it, set custom values to variables, and use access modifiers like public, private, or protected. This means we can decide how the object should be set up when it is created.

Note that even if we don’t write super() in our constructor, Java still adds it automatically unless we call another constructor with this() or call a different super(...) with parameters.

We will understand this deeply in the next section.

Syntax:

class ClassName {

    public ClassName() {
        // Body (optional)
    }

}

Example

Let's use the same Bike example we used to explain the default constructor.

public class Bike {

    public Bike() {
        System.out.println("Bike object created!");
    }

    public static void main(String[] args) {
        Bike myBike = new Bike();
    }
}

Output:

Bike object created!

In the above code, we have defined a constructor in our code while writing it. This means that it is an example of a no-argument constructor.

We know that both types of constructors are defined without any parameters, but what about the body? We haven’t said anything about it. Let’s see what happens if we write code with a no-argument constructor without a body:

public class Bike {

    Bike() {
        // No body
    }

    public static void main(String[] args) {
        Bike myBike = new Bike(); // Calls the user-defined no-argument constructor
        System.out.println("Bike object created!");
    }
}

Output:

Bike object created!

The code still gets compiled because the compiler adds the super() keyword during the compilation process, which initialises the object using the object class.

Parameterised Constructor

A constructor that accepts parameters is called a parameterised constructor and is only used when we have to initialise an object’s attributes with custom values.

• Parameter refers to the variable listed in the constructor or method definition.

• Argument is the actual value passed when calling the constructor or method.

It gives us the flexibility of initiating our object with custom values given at the time of object creation.

Syntax

Below is the syntax for a parameterised constructor that takes one parameter:

class ClassName {

    // Data members (instance variables)
    DataType variable1;

    // Parameterized constructor
    ClassName(DataType param1) {
        variable1 = param1;
    }

    // Main method to create objects
    public static void main(String[] args) {
        // Creating object using parameterized constructor
        ClassName obj = new ClassName(value1);
    }
}

Example

We will again use the Bike example for this.

public class Bike {

    String modelName;  // instance variable

    // Parameterized constructor
    Bike(String model) {
        modelName = model;
    }

    public static void main(String[] args) {
        // Pass parameter while creating the Bike object
        Bike myBike = new Bike("Mountain Bike");
        System.out.println("Bike object created! Model: " + myBike.modelName);
    }
}

Output:

Bike object created! Model: Mountain Bike

In this example, we’re working with a Bike class that has an instance variable of String data type called modelName, and a constructor to set the value of that variable.

The constructor takes a parameter called model and assigns it to modelName. So, when we create a new Bike object and pass in the string "Mountain Bike", the constructor stores that value in the modelName variable.

Because of this, when we print out the model name, we see "Mountain Bike" instead of null, which is the default value of the String data type, as now the value of the modelName has been updated.

Copy Constructor

A copy constructor is used to create a new object as a copy of the existing object. Unlike C++, Java doesn’t have a default copy constructor. Instead, we have to create our own by creating a constructor that takes an object of the same class as a parameter and copies its fields.

Syntax

class ClassName {

    // Fields
    DataType1 field1;
    DataType2 field2;
    // ... other fields

    // Normal constructor
    ClassName(DataType1 f1, DataType2 f2) {
        field1 = f1;
        field2 = f2;
        // ... initialize other fields
    }

    // Copy constructor 
    ClassName(ClassName other) {
        field1 = other.field1;
        field2 = other.field2;
        // ... copy other fields
    }
}

Example

public class Bike {

    String modelName;  // instance variable

    // Parameterized constructor
    Bike(String model) {
        modelName = model;
    }

    // Copy constructor
    Bike(Bike otherBike) {
        modelName = otherBike.modelName;
    }

    public static void main(String[] args) {
        // Create a Bike object using the parameterized constructor
        Bike myBike = new Bike("Mountain Bike");
        System.out.println("Bike object created! Model: " + myBike.modelName);

        // Create a copy of the existing Bike object using the copy constructor
        Bike copiedBike = new Bike(myBike);
        System.out.println("Copied Bike object created! Model: " + copiedBike.modelName);
    }
}

Output:

Bike object created! Model: Mountain Bike

Copied Bike object created! Model: Mountain Bike

In the above code, we have created a copy constructor to copy the values of the object (myBike) into a new object (copiedBike), which we have defined in the main class.

But the way the new object is called is a little different. Instead of passing arguments for the constructor, we have passed the original object.

Why Copy Constructors?

A copy constructor is used to make a copy of the object, but you can also make a copy using the clone() method or the object.clone() method. So why do we use a copy constructor?

The copy constructor makes a deep copy, while the clone method makes a shallow copy of the object. There are various things that you should know before using cloning techniques, like CloneNotSupportedException.

On the other hand, copy constructors are clear and easy to understand, and work well with final fields. We can control how the copy happens (deep vs. shallow) and especially when we are dealing with mutable objects.

What Happens Behind the Scenes When a Constructor Is Called in Java?

So, just to recap: when we create an object using the new keyword, a constructor is automatically called. If we haven't defined any constructors in our class, Java automatically defines a constructor for us.

But while writing and running our code, we mostly focus on what’s visible in our editor, as in what we can see. Let’s dive a little deeper and explore what happens behind the scenes – at the compiler and JVM level – when an object is created and executed.

• Step 1: Memory Allocation – When we create an object using a new keyword, Java allocates memory for that object in the heap. This memory is where the object’s fields (also called attributes) will be placed.

• Step 2: Reference Creation – A reference to this object is stored on the stack, which lets our program interact with the object that lives in the heap.

• Step 3: Constructor Creation – Java then determines which constructor to call. If no constructor is explicitly defined in our class, the compiler automatically inserts a constructor with no parameters.

• Step 4: Superclass Constructor Call – Before executing the constructor’s body, Java first calls the constructor of the superclass using the super() keyword. This ensures that the fields inherited from the parent class are properly initialised. If you don’t explicitly write super(), the compiler adds it automatically in the first line of the code, but only if the superclass has a no-argument constructor, unless we're already calling another constructor via this().

But don’t use both the super() and this() keywords in the same constructor (you can use them in separate constructors.

Let’s say that it doesn’t have a super class – then what?

The answer is simple: Java has an in-built Object class that has a no-argument constructor by default. This is why our classes run smoothly even if we don’t write super() ourselves, as Java calls it in the background.

That means every class we create is a subclass of the object class:

Attribute Initialisation:

At this point, fields get initialised:

• First, with default values (for example, 0 for int, null for objects),

• Then, with any explicit initialisations we've written (for example, int x = 10), the default values will get replaced by them.

Constructor Execution:

And finally, the logic runs. This is where all or some of the attributes defined in the class for object creation are initialised by the parameters used during object creation, with the help of constructors.

But not every field may get initialised. Fields that are not updated by the constructor will keep the values they already have (either the default value or the explicitly initialised values).

In short, the constructor gives us the flexibility to customise our object at the time of creation, but it doesn't automatically set every field unless we explicitly write the logic for it.

Check the code below to understand better:

class Example {

    int a;           // default 0
    int b = 10;      // explicitly initialized to 10
    String name;     // default null

    Example(int x) {
        a = x;       // only 'a' is set through constructor
        // 'b' is not changed, stays 10
        // 'name' is not changed, stays null
    }

    void display() {
        System.out.println("a = " + a);
        System.out.println("b = " + b);
        System.out.println("name = " + name);
    }

    public static void main(String[] args) {
        Example obj = new Example(5);
        obj.display();
    }
}

Output:

In the above example, we have three data members – a, b, and name. We have already done the declaration and initialisation of the variable b at the beginning and given a value to a at the time of object creation.

So we can see that:

1. ‘a’, whose value has been updated by the constructor with the value given at the time of object creation, has the same value

2. ‘b’, which already had a value and does not get updated by the constructor, prints the same value

3. the string ‘name’ didn’t have a value, so null was printed instead, as it is the default value of the String data type.

How to Use the return Keyword in Constructors

We know that constructors are defined without a return type, but we can use the return keyword in the constructor only to exit the constructor early, not to return a value. Check out the code below.

Sample Code:

public class Bike {

    String modelName;  // instance variable
    int speed;

    // Parameterized constructor
    Bike(String model, int sp) {
        modelName = model;
        return;
        speed = sp;
    }

    public static void main(String[] args) {
        // Pass parameter while creating the Bike object
        Bike myBike = new Bike("Mountain Bike", 20);
        System.out.println("Bike object created! Model: " + myBike.modelName);
        System.out.println("Speed of the Bike is " + myBike.speed);
    }
}

Let’s try to understand the above code and the use of the return keyword along with it. We will start with what would happen if the return keyword wasn’t here. The code would have executed without any errors and would have received an output.

Now, what will happen if we add the return keyword? As we have discussed above, the return keyword will tell the compiler not to go beyond this point in the constructor.

So whatever we have written in the constructor after the return keyword will not be compiled, and if that had any value and was necessary for the proper execution of our code, the compiler will throw an error.

The error says it clearly ‘unreachable statement’, which means that the compiler was not allowed to go beyond the return keyword.

Now that you understand the return keyword, let’s see when you can use it.

Example:

public class Bike {

    // Constructor with a condition to exit early
    Bike(boolean skip) {
        if (skip) {
            System.out.println("Constructor exited early");
            return; // Ends constructor execution here
        }

        System.out.println("Constructor continues...");
        // More initialization logic can go here
        System.out.println("Bike object initialized successfully");
    }

    public static void main(String[] args) {
        System.out.println("Creating first bike (skip = true):");
        Bike bike1 = new Bike(true);  // Constructor will exit early

        System.out.println("\nCreating second bike (skip = false):");
        Bike bike2 = new Bike(false); // Constructor will continue
    }
}

We’ve defined a Bike class that has a constructor with one boolean parameter called skip. Inside the constructor, there's an if statement that checks if skip is true. If it is, the constructor prints a message and uses the return keyword to exit early. This means the rest of the constructor won’t run.

But there is no else block. So what happens when skip is false? In that case, the if condition is not true, then the code inside the if statement is not executed (including the return keyword) and the constructor simply continues to the next lines of code. That’s where we do the actual bike initialisation and print a success message.

In short:

1. If skip is true, the constructor exits early.

2. If skip is false, the constructor continues and finishes the setup.

This is a simple way to control how much of the constructor runs, based on a condition.

Conclusion

In this blog, we have understood many different topics, what a constructor is, its different types, like default constructor, no argument constructor, parameterised constructor and copy constructor, not only with theory but with code examples as well.

Understanding them will not only enhance our understanding but also help us write modular and well-maintained code in Java. While this concept is also important in OOP, as it is centred around the concept of objects and constructors are the ones that are used to initialise them.

Frequently Asked Questions

Q1. Why do we use constructors?

A: We use constructors because:

1. They are created automatically by the compiler and initialise the object with default values.

2. We can initialise all the attributes of the objects in one go.

3. They prevent incomplete or incorrect object initialisation by ensuring that important data is provided during object creation.

4. Code maintainability and modularity increase.

5. We can use objects as soon as they are created.

Q2. What is the basic difference between Method Overloading and Constructor Overloading?

A:

You can check out some of my other beginner-friendly articles on my blog:

1. Understanding abstraction in Java

2. How to build a Movie App in React using TMDB API?

3. How to merge two sorted arrays

Python's popularity stems from its versatility and ease of use, making it an excellent choice for a broad range of applications. Its extensive standard library provides tools for numerous tasks, from web development and data analysis to artificial intelligence and scientific computing.

The language's clear syntax and active, supportive community also contribute to its widespread adoption among both beginners and experienced developers.

Python is employed across a wide array of domains, including:

• Data Analysis and Visualization: Processing, analyzing, and visualizing large datasets using libraries such as Pandas, NumPy, and Matplotlib.

• Artificial Intelligence and Machine Learning: Developing AI models, machine learning algorithms, and deep learning applications with frameworks like TensorFlow and PyTorch.

• Scientific and Numeric Computing: Performing complex calculations and simulations in fields like physics, engineering, and mathematics.

• Web Development: Building server-side web applications with frameworks like Django and Flask.

• Automation and Scripting: Automating repetitive tasks, system administration, and network configuration.

• Software Testing and Quality Assurance: Writing scripts for automated testing.

• Education: Widely used as a first language for teaching programming concepts due to its simplicity and readability.

An Animated Introduction to Programming with Python

To make learning about Python programming more accessible, I developed an interactive tutorial called "An Animated Introduction to Programming with Python." This resource utilizes annotated code playbacks to demonstrate key language features step-by-step. From fundamental syntax to media manipulation, each concept is presented through executable code and accompanying visual explanations.

You can access the free 'book' of code playbacks here: https://playbackpress.com/books/pybook.

For more information about code playbacks, you can watch a short demo.

A Focus on Media Computation with JES

A portion of this book utilizes Mark Guzdial's pioneering "Media Computation" approach, which teaches programming concepts through the manipulation of digital media (images, sounds, and videos). Some of the examples in the book use the Jython Environment for Students (JES).

A Note on JES:

JES was developed at Georgia Tech and has been a highly effective pedagogical tool for many years. The main idea is to manipulate pixels in images for understanding fundamental programming concepts like iteration, conditionals, and functions in a visual and tangible way.

Even if JES isn't as widely used today, the lessons learned from manipulating pixels transfers to almost all other areas of computing. In other words, even if you don’t use JES it is still worth going through the playbacks marked with JES.**

Table of Contents

1. Flow of Control and Simple Data

   1. Printing and flow

   2. Arithmetic and comparing numbers

   3. Programming with Data

   4. Distance Between Two Points

   5. More with Strings

   6. JES: Prompting the User for Some Information

   7. JES: Showing a Picture

   8. JES: Accessing Pixels

   9. JES: Adding a Caption to a Picture

2. Iterating Over Data

   1. Iterating Through a String

   2. Lists and Iteration

   3. Splitting Strings

   4. Ranges

   5. Reading from a File

   6. Writing to a File

   7. JES: Iterating Through Pixels

   8. JES: Graying an Image

   9. JES: Copying an Image

   10. JES: Enlarging a Picture

3. Conditions with if and while

   1. Comparisons by the Computer

   2. if, if/else, and if/else if/else Statements

   3. Logical Operators

   4. Loops

   5. JES: Adding a Border to a Picture

   6. JES: Finding the Predominant Color in a Row

4. Data Containers

   1. Python Lists

   2. Python Dictionaries

   3. Python Sets

   4. JES: Storing User Supplied Data in a Dictionary

5. Functions

   1. A First Function

   2. Function Return Values

   3. Parameters

   4. Scope of Variables

   5. Pass by Reference or Pass by Value

   6. Sorting with Functions

   7. JES: Adding Text (Again) and Saving a File Using Functions

   8. JES: Shrinking a Picture

   9. JES: Making a Movie with Moving Text

6. Classes

   1. Classes

   2. Class with Data and Methods

   3. Classes that Interact with Each Other

   4. Inheritance

   5. JES: Photo Resizing/Rotating Class

I hope this animated introduction helps you grasp the fundamental concepts of Python and empowers you to start building your own applications. Dive in, experiment, and let me know what you think! If you have any questions or feedback, I'd love to hear it. Comments and feedback are welcome anytime: mark@playbackpress.com

If you'd like to support my work and help keep Playback Press free for all, consider donating using GitHub Sponsors. I use all of the donations for hosting costs. Your support helps me continue creating educational content like this. Thank you!

That's exactly what LLM agents bring to the table. They're changing how we automate complex tasks, and they can help bring our AI ideas to life in a whole new way.

In this article, we'll explore what LLM agents are, how they work, and how you can build your very own using awesome open-source frameworks.

What we’ll cover:

1. The Current State of LLM Agents

   • From Chatbots to Autonomous Agents

   • What Can Agents Do Today?

   • What's Available to Build With?

   • Why Now Is the Best Time to Learn

2. What Are LLM Agents and Why Are They a Big Deal?

   • What Is an LLM?

   • So, What’s an LLM Agent?

   • Why Does This Matter?

3. The Rise of Open-Source Agent Frameworks

   • Popular Open-Source Agent Frameworks

   • What These Tools Enable

   • Why Use a Framework Instead of Building from Scratch?

4. Core Concepts Behind Agent Design

   • The Agent Loop

   • Key Components of an Agent

   • Multi-Agent Collaboration

5. Project: Automate Your Daily Schedule from Emails

   • What We’re Automating

   • Step 1: Install the Required Tools

   • Step 2: Define the Task

   • Step 3: Build the Workflow with LangGraph

6. Multi-Agent Collaboration with CrewAI

   • What Is CrewAI?

   • Sample Roles for the Email Summary Task

   • Sample CrewAI Code

7. What Actually Happens During Execution?

8. Are LLM Agents Safe? What to Know About Security and Privacy

9. Troubleshooting & Tips

10. Explore More Daily Automations

11. What’s Next in Agent Technology?

12. Final Summary

The Current State of LLM Agents

LLM agents are one of the most exciting developments in AI right now. They’re already helping automate real tasks but they’re also still evolving. So where are we today?

From Chatbots to Autonomous Agents

Large Language Models (LLMs) like GPT-4, Claude, Gemini, and LLaMA have evolved from simple chatbots into surprisingly capable reasoning engines. They've gone from answering trivia questions and generating essays to performing complex reasoning, following multi-step instructions, and interacting with tools like web search and code interpreters.

But here’s the catch: these models are reactive. They wait for input and give output. They don't retain memory between tasks, plan ahead, or pursue goals on their own. That’s where LLM agents come in – they bridge this gap by adding structure, memory, and autonomy.

What Can Agents Do Today?

Right now, LLM agents are already being used for:

• Summarizing emails or documents

• Planning daily schedules

• Running DevOps scripts

• Searching APIs or tools for answers

• Collaborating in small “teams” to complete complex tasks

But they’re not perfect yet. Agents can still:

• Get stuck in loops

• Misunderstand goals

• Require detailed prompts and guardrails

That’s because this technology is still early-stage. Frameworks are getting better fast, but reliability and memory are still works in progress. So just keep that in mind as you experiment.

Why Now Is the Best Time to Learn

The truth is: we’re still early. But not too early.

This is the perfect time to start experimenting with agents:

• The tooling is mature enough to build real projects

• The community is growing rapidly

• And you don’t need to be an AI expert just comfortable with Python

What Are LLM Agents and Why Are They a Big Deal?

Before we dive into the exciting world of agents, let's quickly chat a bit more about the basics.

What Is an LLM?

An LLM, or Large Language Model, is basically an AI that's learned from a massive amount of text from the internet – think books, articles, code, and tons more. You can picture it as a super-smart autocomplete engine. But it does way more than just finish your sentences. It can also:

• Answer tricky questions

• Summarize long articles or documents

• Write code, emails, or creative stories

• Translate languages instantly

• Even solve logic puzzles and have engaging conversations

Chances are you've heard of ChatGPT, which is powered by OpenAI's GPT models. Other popular LLMs you might come across include Claude (from Anthropic), LLaMA (by Meta), Mistral, and Gemini (from Google).

These models work by simply predicting the next word in a sentence based on the context. While that sounds straightforward, when trained on billions of words, LLMs become capable of surprisingly intelligent behavior, understanding your instructions, following step-by-step reasoning, and producing coherent responses across almost any topic you can imagine.

So, What’s an LLM Agent?

While LLMs are super powerful, they usually just react – they only respond when you ask them something. An LLM agent, on the other hand, is proactive.

LLM agents can:

• Break down big, complex tasks into smaller, manageable steps

• Make smart decisions and figure out what to do next

• Use "tools" like web search, calculators, or even other apps

• Work towards a goal, even if it takes multiple steps or tries

• Team up with other agents to accomplish shared objectives

In short, LLM agents can think, plan, act, and adapt.

Think of an LLM agent like your super-efficient new assistant: you give it a goal, and it figures out how to achieve it all on its own.

Why Does This Matter?

This shift from just responding to actively pursuing goals opens a ton of exciting possibilities:

• Automating boring IT or DevOps tasks

• Generating detailed reports from raw data

• Helping you with multi-step research projects

• Reading through your daily emails and highlighting key info

• Running your internal tools to take real-world actions

Unlike older, rule-based bots, LLM agents can reason, reflect, and learn from their attempts. This makes them a much better fit for real-world tasks that are messy, require flexibility, and depend on understanding context.

The Rise of Open-Source Agent Frameworks

Not too long ago, if you wanted to build an AI system that could act autonomously, it meant writing a ton of custom code, painstakingly managing memory, and trying to stitch together dozens of components. It was a complex, delicate, and highly specialized job.

But guess what? That's not the case anymore.

In 2024, a wave of fantastic open-source frameworks hit the scene. These tools have made it dramatically easier to build powerful LLM agents without you having to reinvent the wheel every time.

Popular Open-Source Agent Frameworks

What These Tools Enable

These frameworks give you ready-made building blocks to handle the trickier parts of creating agents:

• Planning – Letting agents decide their next move

• Tool Use – Easily connecting agents to things like file systems, web browsers, APIs, or databases

• Memory – Storing and retrieving past information or intermediate results for long-term context

• Multi-Agent Collaboration – Setting up teams of agents that work together on shared goals

Why Use a Framework Instead of Building from Scratch?

While you could build a custom agent from the ground up, using a framework will save you a huge amount of time and effort. Open-source agent libraries come packed with:

• Built-in support for orchestrating LLMs

• Proven patterns for task planning, keeping track of where you are, and getting feedback

• Easy integration with popular models like OpenAI, or even models you run locally

• The flexibility to grow from a single helpful agent to entire teams of agents

Basically, these frameworks let you focus on what your agent should do, rather than getting bogged down in how to build all the internal workings. Plus, choosing open source means you benefit from community contributions, transparency in how they work, and the freedom to tweak them to your exact needs, without getting locked into a single vendor.

Core Concepts Behind Agent Design

To really grasp how LLM agents operate, it helps to think of them as goal-driven systems that constantly cycle through observing, reasoning, and acting. This continuous loop allows them to tackle tasks that go beyond simple questions and answers, moving into true automation, tool usage, and adapting on the fly.

The Agent Loop

Most LLM agents function based on a mental model called the Agent Loop a step-by-step cycle that repeats until the job is done. Here’s how it typically works:

• Perceive: The agent starts by noticing something in its environment or receiving new information. This could be your prompt, a piece of data, or the current state of a system.

• Plan: Based on what it perceives and its overall goal, the agent decides what to do next. It might break the task into smaller sub-goals or figure out the best tool for the job.

• Act: The agent then acts. This could mean running a function, calling an API, searching the web, interacting with a database, or even asking another agent for help.

• Reflect: After acting, the agent looks at the outcome: Did it work? Was the result useful? Should it try a different approach? Based on this, it updates its plan and keeps going until the task is complete.

This loop is what makes agents so dynamic. It allows them to handle ever-changing tasks, learn from partial results, and correct their course qualities that are vital for building truly useful AI assistants.

Key Components of an Agent

To do their job effectively, agents are built around several crucial parts:

• Tools are how an agent interacts with the real (or digital) world. These can be anything from search engines, code execution environments, file readers, or API clients, to simple calculators or command-line scripts.

• Memory lets agents remember what they've done or seen across different steps. This might include previous things you've said, temporary results, or key decisions. Some frameworks offer short-term memory (just for one session), while others support long-term memory that can span multiple sessions or goals.

• Environment refers to the external data or system context the agent operates within think APIs, documents, databases, files, or sensor inputs. The more information and access an agent have to its environment, the more meaningful actions it can take.

• Goal is the agent's ultimate objective: what it's trying to achieve. Goals should be specific and clear for instance, “generate a daily schedule,” “summarize this document,” or “extract tasks from emails.”

Multi-Agent Collaboration

For more advanced systems, you can even have multiple agents working together to hit a shared target. Each agent can be given a specific role that highlights its specialty just like people working on a team.

For example:

• A researcher agent might be tasked with gathering information.

• A coder agent could write Python scripts or automation routines.

• A reviewer agent might check the results and ensure everything is up to snuff.

These agents can chat with each other, share information, and even debate or vote on decisions. This kind of teamwork allows AI systems to tackle bigger, more complex tasks while keeping things organized and modular.

Project: Automate Your Daily Schedule from Emails

What We’re Automating

Think about your typical morning routine:

• You open your inbox.

• You quickly scan through a bunch of emails.

• You try to spot meetings, tasks, and important reminders.

• Then, you manually write a to-do list or add things to your calendar.

Let's use an LLM agent to make that process effortless. Our agent will:

• Read a list of your email messages

• Pull out time-sensitive items like meetings or deadlines

• Summarize everything into a nice, clean daily schedule

Step 1: Install the Required Tools

To get started, you'll need three main tools: Python, VSCode, and an OpenAI API key.

1. Install Python 3.9 or Higher

Grab the latest version of Python 3.9+ from the official website: https://www.python.org/downloads/

Once it's installed, double-check it by running python --version in your terminal.

This command simply asks your system to report the Python version currently installed. You'll want to see Python 3.9.x or something higher to ensure compatibility with our project.

2. Install VSCode (Optional but Recommended)

VSCode is a fantastic, user-friendly code editor that works perfectly with Python. You can download it right here: https://code.visualstudio.com/.

3. Get Your OpenAI API Key

Head over to: https://platform.openai.com

Sign in or create a new account. Navigate to your API Keys page. Click “Create new secret key” and make sure to copy that key somewhere safe for later.

4. Install Python Libraries

Open your terminal or command prompt and install these essential packages:

pip install langgraph langchain openai

This command uses pip, Python's package manager, to download and install three crucial libraries for our agent:

• langgraph: The core framework we'll use to build our agent's workflow.

• langchain: A foundational library for working with large language models, upon which LangGraph is built.

• openai: The official Python library for connecting to OpenAI's powerful AI models.

If you're excited to try out multi-agent setups (which we'll cover in Step 5), also install CrewAI:

pip install crewai

This command installs CrewAI, a specialized framework that makes it easy to orchestrate multiple AI agents working together as a team.

5. Set Your OpenAI API Key

You need to make sure your Python code can find and use your OpenAI API key. This is typically done by setting it as an environment variable.

On macOS/Linux, run this in your terminal (replace "your-api-key" with your actual key):

export OPENAI_API_KEY="your-api-key"

This command sets an environment variable named OPENAI_API_KEY. Environment variables are a secure way for applications (like your Python script) to access sensitive information without hardcoding it directly into the code itself.

On Windows (using Command Prompt), do this:

set OPENAI_API_KEY="your-api-key"

This is the Windows equivalent command to set the OPENAI_API_KEY environment variable.

Now, your Python code will be all set to talk to the OpenAI model!

Step 2: Define the Task

We discussed this briefly in the beginning of this section. But to reiterate, this is what we’ll want our agent to do:

• Scan for meetings, events, and important tasks.

• Jot them down quickly in a notebook or an app.

• Create a rough mental plan for your day.

This routine takes time and mental energy. So having an agent do it for us will be super helpful.

Step 3: Build the Workflow with LangGraph

What Is LangGraph?

LangGraph is a cool framework that helps you build agents using a "graph-based" workflow, kind of like drawing a flowchart. It's powered by LangChain and gives you a lot more control over exactly how each step in your agent's process unfolds.

Each "node" in this graph represents a decision point or a function that:

• Takes some input (its current "state").

• Does some reasoning or takes an action (often involving the LLM and its tools).

• Returns an updated output (a new "state").

You draw the connections between these nodes, and LangGraph then executes it like a smart, automated state machine.

Why Use LangGraph?

• You get to control the precise order of execution.

• It's fantastic for building workflows that have multiple steps or even branch off into different paths.

• It plays nicely with both cloud-based models (like OpenAI) and models you run locally.

Alright – now let’s write the code.

1. Simulate Email Input

In a real application, your agent would probably connect to Gmail or Outlook to fetch your actual emails. For this example, though, we’ll just hardcode some sample messages to keep things simple:

Python

emails = """
1. Subject: Standup Call at 10 AM
2. Subject: Client Review due by 5 PM
3. Subject: Lunch with Sarah at noon
4. Subject: AWS Budget Warning – 80% usage
5. Subject: Dentist Appointment - 4 PM
"""

This multiline Python string, emails, acts as our stand-in for real email content. We're providing a simple, structured list of email subjects to demonstrate how the agent will process text.

2. Define the Agent Logic

Now, we'll tell OpenAI’s GPT model how to process this email text and turn it into a summary.

from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, END
from typing import TypedDict, Annotated, List
import operator

# Define the state for our graph
class AgentState(TypedDict):
    emails: str
    result: str

llm = ChatOpenAI(temperature=0, model="gpt-4o") # Using gpt-4o for better performance

def calendar_summary_agent(state: AgentState) -> AgentState:
    emails = state["emails"]
    prompt = f"Summarize today's schedule based on these emails, listing time-sensitive items first and then other important notes. Be concise and use bullet points:\n{emails}"
    summary = llm.invoke(prompt).content
    return {"result": summary, "emails": emails} # Ensure emails is also returned

Here’s what’s going on:

• Imports: We bring in necessary components:

  • ChatOpenAI to connect to the LLM,

  • StateGraph and END from langgraph.graph to build our agent workflow,

  • TypedDict, Annotated, and List from typing for type checking and structure,

  • operator (though not used in this snippet, it can help with comparisons or logic).

• AgentState: This TypedDict defines the shape of the data our agent will work with. It includes:

  • emails: the raw input messages.

  • result: the final output (the daily summary).

• llm = ChatOpenAI(...): Initializes the language model. We're using GPT-4o with temperature=0 to ensure consistent, predictable output perfect for structured summarization tasks.

• calendar_summary_agent(state: AgentState): This function is the "brain" of our agent. It:

  • Takes in the current state, which includes a list of emails.

  • Extracts the emails from that state.

  • Constructs a prompt that tells the model to generate a concise daily schedule summary using bullet points, prioritizing time-sensitive items.

  • Sends this prompt to the model with llm.invoke(prompt).content, which returns the LLM’s response as plain text.

  • Returns a new AgentState dictionary containing:

    • result: the generated summary,

    • emails: preserved in case we need it downstream.

3. Build and Run the Graph

Now, let's use LangGraph to map out the flow of our single-agent task and then run it.

builder = StateGraph(AgentState)
builder.add_node("calendar", calendar_summary_agent)
builder.set_entry_point("calendar")
builder.set_finish_point("calendar") # END is implicit if not set explicitly

graph = builder.compile()

# Run the graph using your simulated email data
result = graph.invoke({"emails": emails})
print(result["result"])

Here’s what’s going on:

• builder = StateGraph(AgentState): We're initiating a StateGraph object. By passing AgentState, we're telling LangGraph the expected data structure for its internal state.

• builder.add_node("calendar", calendar_summary_agent): This line adds a named "node" to our graph. We're calling it "calendar", and we're linking it to our calendar_summary_agent function, meaning that function will be executed when this node is active.

• builder.set_entry_point("calendar"): This sets "calendar" as the very first step in our workflow. When we start the graph, execution will begin here.

• builder.set_finish_point("calendar"): This tells LangGraph that once the "calendar" node finishes its job, the entire graph process is complete.

• graph = builder.compile(): This command takes our defined graph blueprint and "compiles" it into an executable workflow.

• result = graph.invoke({"emails": emails}): This is where the magic happens! We're telling our graph to start running. We pass it an initial state that contains our emails data. The graph will then process this data through its nodes until it reaches an end point, returning the final state.

• print(result["result"]): Finally, we grab the summarized schedule from the result (the final state of our graph) and print it to the console.

Example Output

Your Schedule:
- 10:00 AM – Standup Call
- 12:00 PM – Lunch with Sarah
- 4:00 PM – Dentist Appointment
- Submit client report by 5:00 PM
- AWS Budget Warning – check usage

Boom! You've just built an AI agent that can read your emails and whip up your daily schedule. Pretty cool, right? This is a simple yet powerful peek into what LLM agents can do with just a few lines of code.

Multi-Agent Collaboration with CrewAI

What Is CrewAI?

CrewAI is an exciting open-source framework that lets you build teams of agents that work together seamlessly just like a real-world project team! Each agent in a CrewAI setup:

• Has a specific, specialized role.

• Can communicate and share information with its teammates.

• Collaborates to achieve a shared goal.

This multi-agent approach is super useful when your task is too big or too complex for just one agent, or when breaking it down into specialized parts makes it clearer and more efficient.

Sample Roles for the Email Summary Task

Let's imagine our email summary task being handled by a small team of agents:

Sample CrewAI Code

from crewai import Agent, Crew, Task, Process
from langchain_openai import ChatOpenAI
import os

# Set your OpenAI API key from environment variables
# os.environ["OPENAI_API_KEY"] = "YOUR_API_KEY" # Make sure this is set, or defined directly

# Initialize the LLM (using gpt-4o for better performance)
llm = ChatOpenAI(temperature=0, model="gpt-4o")

# Define the agents with specific roles and goals
extractor = Agent(
    role="Email Scanner",
    goal="Find all meetings, reminders, and tasks from the given emails, accurately extracting details like time, date, and subject.",
    backstory="You are an expert at scanning emails for key information. You meticulously extract every relevant detail.",
    verbose=True,
    allow_delegation=False,
    llm=llm
)

prioritizer = Agent(
    role="Schedule Optimizer",
    goal="Sort extracted items by urgency and time, preparing them for a daily agenda.",
    backstory="You are a master of time management, always knowing what needs to be done first. You organize tasks logically.",
    verbose=True,
    allow_delegation=False,
    llm=llm
)

formatter = Agent(
    role="Output Generator",
    goal="Generate a clean, polished, and concise daily agenda in bullet-point format, clearly listing all schedule items.",
    backstory="You are a professional secretary, ensuring all outputs are perfectly formatted and easy to read. You prioritize clarity.",
    verbose=True,
    allow_delegation=False,
    llm=llm
)

# Simulate email input
emails = """
1. Subject: Standup Call at 10 AM
2. Subject: Client Review due by 5 PM
3. Subject: Lunch with Sarah at noon
4. Subject: AWS Budget Warning – 80% usage
5. Subject: Dentist Appointment - 4 PM
"""

# Define the tasks for each agent
extract_task = Task(
    description=f"Extract all relevant events, meetings, and tasks from these emails: {emails}. Focus on precise details.",
    agent=extractor,
    expected_output="A list of extracted items with their details (e.g., '- Standup Call at 10 AM', '- Client Review due by 5 PM')."
)

prioritize_task = Task(
    description="Prioritize the extracted items by time and urgency. Meetings first, then deadlines, then other notes.",
    agent=prioritizer,
    context=[extract_task], # The output of extract_task is the input here
    expected_output="A prioritized list of schedule items."
)

format_task = Task(
    description="Format the prioritized schedule into a clean, easy-to-read daily agenda using bullet points. Ensure concise language.",
    agent=formatter,
    context=[prioritize_task], # The output of prioritize_task is the input here
    expected_output="A well-formatted daily agenda with bullet points."
)

# Instantiate the crew
crew = Crew(
    agents=[extractor, prioritizer, formatter],
    tasks=[extract_task, prioritize_task, format_task],
    process=Process.sequential, # Tasks are executed sequentially
    verbose=2 # Outputs more details during execution
)

# Run the crew
result = crew.kickoff()
print("\n########################")
print("## Final Daily Agenda ##")
print("########################\n")
print(result)

Here’s what’s going on:

• Imports: We bring in key classes from CrewAI: Agent, Crew, Task, and Process. We also import ChatOpenAI for our language model and os to handle environment variables.

• llm = ChatOpenAI(...): Just like in the LangGraph example, this sets up our OpenAI language model, making sure its responses are direct (temperature=0) and using the gpt-4o model.

• Agent Definitions (extractor, prioritizer, formatter):

  • Each of these variables creates an Agent instance. An agent is defined by its role (what it does), a specific goal it's trying to achieve, and a backstory (a sort of personality or expertise that helps the LLM understand its purpose better).

  • verbose=True is super helpful for debugging, as it makes the agents print out their "thoughts" as they work.

  • allow_delegation=False means these agents won't pass their assigned tasks to other agents (though this can be set to True for more complex delegation scenarios).

  • llm=llm connects each agent to our OpenAI language model.

• Simulated emails: We reuse the same sample email data for this example.

• Task Definitions (extract_task, prioritize_task, format_task):

  • Each Task defines a specific piece of work that an agent needs to perform.

  • description clearly tells the agent what the task involves.

  • agent assigns this task to one of our defined agents (e.g., extractor for extract_task).

  • context=[...] is a critical part of CrewAI's collaboration. It tells a task to use the output of a previous task as its input. For instance, prioritize_task takes the extract_task's output as its context.

  • expected_output gives the agent an idea of what its result should look like, helping guide the LLM.

• crew = Crew(...):

  • This is where we assemble our team! We create a Crew instance, giving it our list of agents and tasks.

  • process=Process.sequential tells the crew to execute tasks one after another in the order they're defined in the tasks list. CrewAI also supports more advanced processes like hierarchical ones.

  • verbose=2 will show you a very detailed log of the crew's internal workings and communication.

• result = crew.kickoff(): This command officially starts the entire multi-agent workflow. The agents will begin collaborating, passing information, and working through their assigned tasks in sequence.

• fprint(result): Finally, the consolidated output from the entire crew's collaborative effort is printed to your console.

CrewAI cleverly handles all the communication between agents, figures out who needs to work on what and when, and passes the output smoothly from one agent to the next it's like having a mini AI assembly line!

What Actually Happens During Execution?

So, whether you're using LangGraph or CrewAI, what's really going on behind the scenes when an agent runs? Let's break down the execution process:

• The system gets an input state (for example, your emails).

• The first agent or graph node reads this input and uses a Large Language Model (LLM) to make sense of it.

• Based on its understanding, the agent decides on an action like pulling out key events or calling a specific tool.

• If needed, the agent might invoke tools (like a web search or a file reader) to get more context or perform external operations.

• The result of that action is then passed to the next agent in the team (if it's a multi-agent setup) or returned directly to you.

Execution keeps going until:

• The task is fully completed.

• All agents have finished their assigned roles.

• A stopping condition or a designated "END" point in the workflow is reached.

Think of this as a super-smart workflow engine where every single step involves reasoning, making decisions, and remembering previous interactions.

Are LLM Agents Safe? What to Know About Security and Privacy

As cool as LLM agents are, they raise an important question: can you really trust an AI to run parts of your workflow or interact with your data? It depends. If you’re using services like OpenAI or Anthropic, your data is encrypted in transit and (as of now) isn’t used for training.

But some data might still be temporarily logged to prevent abuse. That’s usually fine for testing and personal projects, but if you’re working with sensitive business info, customer data, or anything private, you’ll want to be careful.

Use anonymized inputs, avoid exposing full datasets, and consider running agents locally using open-source models like LLaMA or Mistral if full control matters to you.

You can also set clear boundaries for your agents so they don’t overstep. Think of it like onboarding a new intern: you wouldn’t give them access to everything on day one.

Give agents only the tools and files they need, keep logs of what they do, and always review the results before letting them make real changes.

As this tech grows, more safety features are coming like better sandboxing, memory limits, and role-based access. But for now, it’s smart to treat your agents like powerful helpers that still need some human supervision.

Troubleshooting & Tips

Sometimes, agents can be a bit quirky! Here are some common issues you might run into and how to fix them:

A handy tip: You can also add print() statements or logging messages inside your agent functions to see what's happening at each stage and debug state transitions.

Explore More Daily Automations

Once you've built one agent-based task, you'll find it incredibly easy to adapt the pattern for other automations. Here are some cool ideas to get your creative juices flowing:

Each of these can be built using the very same principles and frameworks we discussed whether that's LangGraph or CrewAI.

What’s Next in Agent Technology?

LLM agents are evolving at lightning speed, and the next wave of innovation is already here:

• Smarter memory systems: Expect agents to have better long-term memory, allowing them to learn over extended periods and remember past conversations and actions.

• Multi-modal agents: Agents won't just handle text anymore! They'll be able to process and understand images, audio, and video, making them much more versatile.

• Advanced planning frameworks: Techniques like ReAct, Toolformer, and AutoGen are constantly improving agents' ability to reason, plan, and reduce those pesky "hallucinations."

• Edge deployment: Imagine agents running entirely offline on your local computer or device using lightweight models like LLaMA 3 or Mistral.

In the very near future, you'll see agents seamlessly integrated into:

• Your DevOps pipelines

• Big enterprise workflows

• Everyday productivity tools

• Mobile apps and smart devices

• Games, simulations, and educational platforms

Final Summary

Alright, let's quickly recap all the cool stuff you've just learned and accomplished:

• You've gotten a solid grasp of what LLM agents are and why they're so powerful.

• You've seen how open-source frameworks like LangGraph and CrewAI make building agents much easier.

• You've built a real LLM agent using LangGraph to automate a common daily task: summarizing your inbox!

• You've explored the world of multi-agent collaboration with CrewAI, understanding how teams of AIs can work together.

• You've learned how to take these principles and scale them to automate countless other tasks.

So, next time you find yourself stuck doing something repetitive, just ask yourself: "Hey, can I build an agent for that?" The answer is probably yes!

Resources Recap

Here are some helpful resources if you want to dive deeper into building LLM agents:

docs.page is an open-source documentation tool that helps you create instant, fast, beautiful, and responsive documentation websites with minimal configuration. It is an open-source project developed by Invertase, a company known for creating developer tools and SDKs.

docs.page is designed to streamline the process of publishing documentation by sourcing content directly from public GitHub repositories.

Key Features:

• Zero configuration: you create a 'docs.json' file and a 'docs' directory. Inside the docs directory, you can create files using the .mdx extension, and docs.page will generate your documentation site.

• Customizable: docs.page allows you to add your logo, social links, theme, analytics, navigation, and more through a simple configuration file.

• Live previews: enables viewing of documentation for any branch, pull request, or specific commit, facilitating real-time collaboration and review.

• Hot reload: the Hot Reload feature provides real-time previews of documentation changes while editing Markdown (.mdx) files. This feature enhances the local development workflow, enabling instant updates without manual refreshes or rebuilds.

• GitHub bot integration: provides a GitHub bot that automatically generates URLs for pull request documentation previews.

• MDX support: you can write documentation in Markdown to utilize MDX, which enables you to use React components, such as tabs, Cards, Tweets, and Steps, directly within your Markdown file.

• Search functionality: integrates with DocSearch to offer full-text search capabilities within your documentation.

• Responsive resign: ensures that your documentation is accessible and visually appealing across a range of devices and screen sizes.

• Dark/light mode: offers theme customization to switch between dark and light modes.

• Code block highlighting: provides syntax highlighting and content copying features for code blocks.

Check out the code available in my GitHub repository.

Table of Contents:

• How Does docs.page Work?

• How to Enable Live Preview in docs.page

• How to Configure docs.page

• How to Use Pre-built Components in docs.page

• How to Diagnose Errors in docs.page

• How to Use Frontmatter

• How to Add Assets to Your Docs

• How to Publish Your Documentation Website

• How can you live preview your upcoming changes to your documentation website?

• Conclusion

How Does docs.page Work?

You can easily start creating your documentation page using the docs.page CLI. It helps you set up a local documentation project by running the following command:

pnpm dlx @docs.page/cli init docs.page

The command output appears as follows:

pnpm dlx @docs.page/cli init docs.page
? Are you sure you want to setup and install docs.page in /home/officialrajdeepsingh/medium/docs.page? yes
Files created:
 - docs.json: Configuration file for your documentation site
 - docs/index.mdx: The home page of your documentation site
 - docs/next-steps.mdx: A page to help you get started with docs.page

Initialization complete. To preview your documentation site, vist https://docs.page/preview in your browser.

After creating your project with the docs.page CLI, your project structure should appear as follows:

.
├── docs
│   ├── index.mdx
│   └── next-steps.mdx
└── docs.json

2 directories, 3 files

The docs folder contains the Markdown file for your documentation, and the docs.json file includes the configuration for your website, such as the header, sidebar, logo, theme, and other settings.

How to Enable Live Preview in docs.page

You can set up live preview of your local documentation in real-time in the browser – but it's a little different: you don't need to run any development commands on your laptop or machine.

To open the live preview of your local documentation, first visit https://docs.page and click the Local Preview button.

Next, select the documentation project on your laptop or machine and click the "Select Directory" button.

After clicking the "Select Directory" button, a new window will open depending on your operating system. Its UI may appear different. Then you need to select the project.

After selecting the folder, you will see the following alert message in the browser (“Let site view files?”). To view the live preview of your documentation website, click the "View files" button.

Now you can see a local live preview of the documentation website in the browser, and any changes you make locally will instantly reflect in the browser. By default, your documentation website should appear as follows:

Next, you’ll learn about configuring the Logo, Theme, Header, Social Links, Sidebar, SEO, search, and more on your docs. You’ll also learn how to use the pre-built components, Front Matter, and assets on docs.page, and finally, how to deploy your documentation website.

How to Configure docs.page

The docs.json file is the primary file for configuring your documentation. Below is a list of all available configuration options, which you can use to modify the logos, theme, analytics, and more on your docs.

Properties

• Basic properties

• Logo

• Theme

• Header

• Anchors

• Social Links

• SEO

• Variables

• Search

• Scripts

• Content

• Tabs

• Sidebar

There’s so much you can configure using docs.page – but in this tutorial, we’ll focus on some of the most important options:

• Properties

• Basic Properties

• Logo

• Theme

• Header

• Social Links

• SEO

• Search

• Tabs

• Sidebar

Basic Properties

docs.page includes basic common properties, such as name, description, and favicon, which is very important for SEO.

• name (string): The name of your project. It appears in the header and is used for things like SEO metadata.

• description (string): A summary of your project. This is used in meta tags and social preview images.

• favicon (string | Favicon object): Specifies the favicon shown in the browser tab. You can provide either a single string URL or use a Favicon object to define different icons for light and dark modes:

  • light (string): URL for the favicon in light mode.

  • dark (string): URL for the favicon in dark mode.

// docs.json
{
  "name": "Docs.page",
  "description": "Ship documentation, like you ship code",
  "favicon": "https://static.invertase.io/assets/docs.page/docs-page-logo.png",
   # or
  "favicon": {
    "light": "https://cdn-icons-png.flaticon.com/24/9664/9664027.png",
    "dark": "https://cdn-icons-png.flaticon.com/24/9643/9643115.png"
  }
}

Logo

Now it’s time to configure the logo for your documentation, which will appear in the header and be used for social preview images.

The minimum height of the logo must be 24px. You can provide URLS for both a light and a dark logo. If you only provide a light or dark logo, and it doesn't work, you may experience issues where your logo doesn't appear on the website when toggling the theme.

You can add the logo to the documentation in two ways:

• First way:

// docs.json
{
  "name": "My Docs",
  "logo": "https://cdn-icons-png.flaticon.com/24/2702/2702154.png",
}

• Second way:

// docs.json
{
  "name": "My Docs",
  "logo": {
    "light": "https://cdn-icons-png.flaticon.com/24/2702/2702154.png",
    "dark": "https://cdn-icons-png.flaticon.com/24/2702/2702172.png"
  }
}

Theme

Configuring the theme in your documentation is easy. If you don’t provide a theme, the default theme will be used in your documentation.

docs.page includes a theme property in docs.json, which holds a Theme object as its value with the properties defaultTheme, primary, primaryLight, backgroundLight, and backgroundDark.

• defaultTheme: You can select a theme, dark or light.

• primary: The primary colour is used for links, buttons, and other interactive elements.

• primaryLight: The primaryLight colour option is used in light mode. If your primary light option is not specified in the docs.json file, then the primary colour will be used.

• primaryDark: The primaryDark colour option is used in dark mode. If your primaryDark option is not specified in the docs.json file, then the primary color will be used.

• backgroundLight: The backgroundLight option is used to specify the background color of your documentation in light mode.

• backgroundDark: The backgroundDark option is used to specify the background color of your documentation in dark mode.

// docs.json
{
  "theme": {
    "defaultTheme": "dark",
    "primary": "#de40eb",
    "primaryLight": "#BFA213",
    "backgroundLight": "#e0cfff",
    "backgroundDark": "#00101f"
  },
}

Header

Configuring the header in your documentation includes the following properties: showName, showThemeToggle, showGitHubCard, and links.

• showName: The showName option displays the documentation name next to the logo in the header and defaults it is true.

• showThemeToggle: The showThemeToggle option displays the theme toggle button in the header (and defaults to true).

• showGitHubCard: The showGitHubCard option displays the GitHub card in the header and defaults to true.

• Links: The links option contains an array of Link objects to display a navigation in the header of your documentation.

// docs.json
{
  "header": {
    "showName": false,
    "showGitHubCard": false,
    "links": [
      {
        "title": "GitHub",
        "href": "https://github.com/officialrajdeepsingh/docs-page-demo"
      },
      {
        "title": "X",
        "href": "https://x.com/Official_R_deep"
      },
      {
        "title": "Linkedin",
        "href": "https://www.linkedin.com/in/officalrajdeepsingh"
      }
    ]
  }
}

Social Links

The social option contains an object of key-value pairs where the key represents the social platform and the value corresponds to the username or ID. Here’s how you can add them:

// docs.json
{
  "social": {
    "github": "officialrajdeepsingh/docs-page-demo",
    "x": "@Official_R_deep",
    "linkedin": "officalrajdeepsingh"
  }
}

SEO

The SEO option configures the SEO settings for your documentation. The noindex option tells search engines not to index your documentation, and it defaults to false.

// docs.json
{
  noindex: true
}

Search

To enable search functionality on your documentation site, you can integrate Algolia DocSearch by configuring the docsearch object in your docs.json file like this:

// docs.json
{
 "search": {
    "docsearch": {
      "appId": "YOUR_APP_ID",
      "apiKey": "YOUR_API_KEY",
      "indexName": "YOUR_INDEX_NAME"
    }
  }
}

Tabs

Tabs are an array of objects displayed at the top of your documentation website.

Properties

Each Tab object includes the following properties:

• id (string, required): A unique identifier for the tab.

• title (string, required): The text label displayed on the tab.

• href (string, required): The URL to navigate to when the tab is clicked.

• locale (string, optional): If set, this tab is displayed only when viewing documentation for the specified locale.

Here’s an example of a couple tabs:

{
  "tabs": [
    {
      "id": "root",
      "title": "Documentation",
      "href": "/"
    },
    {
      "id": "components",
      "title": "Components",
      "href": "/components"
    }
  ],
}

Sidebar

To display the sidebar on your website, you can configure or define it in the docs.json file your documentation, which will appear in the sidebar of your site.

Essentially, a sidebar is a list of links that appears on the side of your documentation. You can organize links using groups and pages by providing an array of sidebar objects.

Options:

• pages: The pages option takes a list of page links to display in the sidebar. It accepts the following options:

  • title (required): The title of the sidebar item.

  • href (required): The URL to link to when the sidebar item is clicked.

  • icon (optional): The icon to display next to the sidebar item.

• group (string): The title of the group under which the sidebar item will be displayed. If not provided, the item will appear at the top level of the sidebar.

• href (string): The URL the sidebar item will link to when clicked.

• icon (string): The name of the icon to display next to the sidebar item.

• tab (string): If set, the sidebar item will only be shown when a specific tab (matching the provided tab ID) is active.

// docs.json
{
"sidebar": [
    {
      "pages": [
        {
          "title": "Overview",
          "href": "/",
          "icon": "book"
        },
        {
          "title": "Configuration",
          "href": "/configuration",
          "icon": "gear"
        }
      ]
    },
    {
      "group": "Components",
      "icon": "grip",
      "pages": [
        {
          "title": "Getting Started",
          "href": "/components",
          "icon": "rocket"
        },
        {
          "title": "Accordion",
          "href": "/components/accordion",
          "icon": "square-caret-down"
        },
        {
          "title": "Callouts",
          "href": "/components/callouts",
          "icon": "bullhorn"
        },
        {
          "title": "Cards",
          "href": "/components/cards",
          "icon": "square-full"
        }
      ]
    }
  ]
}

If you want to learn more about this, check out the documentation here.

How to Use Pre-built Components in docs.page

docs.page comes with 15 pre-built components, so you don't need to import components into your MDX file. You can use them directly in your MDX file.

In the following example, I’m using the Info Callout component directly within the MDX file, without importing it.

// index.mdx
---
title: Welcome to docs.page!
description: Get started with docs.page
---

Welcome to docs.page! The init command you just ran has created a basic file struture in your project to help you get started.

## Walkthrough

### Configuration

In the root of your directory a new `docs.json` file has been created. This file is used to configure your documentation site. You can customize the name, description, and sidebar, theme, logos and more using this file.


<Info>Here's a basic example of what the file looks like: </Info>

How to Diagnose Errors in docs.page

If you encounter any errors on your documentation website, you can view all the errors by clicking the diagnostics button.

How to Use Frontmatter

Front matter is a block of YAML placed at the beginning of a Markdown file, enclosed between triple-dash (---) lines.

Frontmatter is a way to customise the metadata page directly within your Markdown files, and most importantly, frontmatter is used for SEO.

# docs/getting-started.mdx
---
title: Welcome to Awesome Project
description: Some awesome docs!
---

# Welcome!

Below is a list of some of the important frontmatter properties in docs.page, including their type and default values:

• title (string): The page’s title used in metadata, social cards, and displayed as the main heading.

• description (string): A summary of the page appears in metadata for SEO and link previews.

• image (string): URL of an asset used in social cards and (if enabled) shown at the top of the page.

• redirect (string): A URL to forward visitors to. When set, the page’s content is bypassed.

• showPageTitle (boolean): Toggle whether the page title appears as a heading at the top.

• showPageImage (boolean): Toggle whether the front-matter image is rendered at the top.

• noindex (boolean): If true, instructs search engines not to index the page.

Refer to the documentation for more detail and other frontmatter property information.

How to Add Assets to Your Docs

You can include assets, such as images and videos, in your documentation. You can add both remote and local assets.

Remote Assets

To add remote assets to your documentation, you can reference them directly in your markdown files.

For example, to include an image from a URL:

# getting-started.mdx
---
title: Welcome to get started
description: Some awesome docs!
---

# Welcome!

![Natural](https://cdn.pixabay.com/photo/2023/04/19/19/11/lake-7938396_960_720.jpg)

Local Assets

To use local assets in your documentation, create an assets folder inside the docs/ directory. Then, add images and videos to the assets folder and reference them in your Markdown files.

Check out the following to better understand:

docs/
  assets/
    natural.png
  index.mdx

Within your markdown file, you can reference the image using a relative path:

![Description](/assets/natural.png)

Different between Local vs Remote Assets

Local assets (PNG, JPG, PDF, and so on) are files stored within your project's public folder, while remote assets are files hosted on an external server. You can access your local assets using your domain URL.

![Natural](./assets/logo.png)

On the other hand, remote assets are stored on a different server (image hosting), as I mentioned. You can access remote assets with a full URL.

The best examples of remote assets include images from Unsplash, Pixabay, and Pexels that can be used directly in your MDX file.

![Natural](https://images.unsplash.com/photo-1728044849236-5e8a061e1895)

You can use remote and local assets based on your requirements – both have advantages and disadvantages. With remote assets, you can add an image directly in your mdx file. When using local assets, you add an image to the public folder and then reference it in your mdx file.

How to Publish Your Documentation Website

With docs.page, you can easily publish your documentation website. No configuration is required – once your documentation website is ready, you can just push your local code to a GitHub repository.

You can now access your documentation website immediately via the docs.page domain.

For example, if your GitHub repository is officialrajdeepsingh/docs-page-demo, your documentation will be available at https://docs.page/officialrajdeepsingh/docs-page-demo.

How to Live Preview Upcoming Changes to Your Docs Website

You can view previews of upcoming changes to your documentation before going public. As your documentation website grows, use the docs.page Github app – any pull request you create in your Github repository automatically generates a unique live preview URL.

To configure the docs page of the GitHub application in your repository, follow these steps:

1. Go to https://github.com/apps/docs-page

2. Click on the install button.

3. Select the GitHub account

4. Select All and single repository.

5. Click on the install button

6. Next, enter the password and OTP.

7. Now if your application is successful, install it in your repository.

Whenever you or another developer create a pull request in your repository, the docs page application creates live previews for you.

Conclusion

docs.page is a free, open-source project that allows you to create instant, fast, and beautiful documentation without requiring any configuration.

I think docs.page offers the best solution for documentation. You can easily set up and deploy your documentation website with the help of docs.page cloud service.

For now, it’s completely free to deploy a documentation website with a docs.page, and I hope it stays that way.

If docs.page ever decides to charge for their services, that could be troublesome. Hopefully, in that case, they’ll provide a clear guide on how to deploy your website on another cloud platform.

If DevOps feels out of reach because you’re also concerned about the cost, don't worry. I’ll guide you step-by-step through creating a production-ready pipeline without spending a dime. Let's get started!

Table of Contents

1. Prerequisites

2. Introduction

3. How to Set Up Your Source Control and Project Structure

4. How to Build Your CI Pipeline with GitHub Actions

5. How to Optimize Docker Builds for CI

6. Infrastructure as Code Using Terraform and Free Cloud Providers

7. How to Set Up Container Orchestration on Minimal Resources

8. How to Create a Free Deployment Pipeline

9. How to Build a Comprehensive Monitoring System

10. How to Implement Security Testing and Scanning

11. Performance Optimization and Scaling

12. Putting it All Together

13. Conclusion

🛠 Prerequisites

• Basic Git knowledge: Cloning repos, creating branches, committing code, and creating PRs

• Familiarity with command line: For Docker, Terraform, and Kubernetes

• Basic understanding of CI/CD: Continuous integration/delivery concepts and pipelines

Accounts needed:

• GitHub account

• At least one cloud provider: AWS Free Tier (recommended), Oracle Cloud Free Tier, or Google Cloud/Azure with free credits

• Terraform Cloud (free tier) for infrastructure state management

• Grafana Cloud (free tier) for monitoring

• UptimeRobot (free tier) for external availability checks

Tools to Install Locally

Optional but Helpful:

• VS Code or any good code editor

• Postman for testing APIs

• Understanding of YAML and Dockerfiles

Introduction

When people hear "DevOps," they often picture complex enterprise systems powered by pricey tools and premium cloud services. But the truth is, you don't actually need a massive budget to build a solid, professional-grade DevOps pipeline. The foundations of good DevOps – automation, consistency, security, and visibility – can be built entirely with free tools.

In this guide, you will learn how to build a production-ready DevOps pipeline using zero-cost resources. We will use a simple CRUD (Create, Read, Update, Delete) app with frontend, backend API, and database as our example project to demonstrate every step of the process.

How to Set Up Your Source Control and Project Structure

1. Create a Well-Structured Repository

A clean repo is the foundation of your pipeline. We will set up:

• Separate folders for frontend, backend, and infrastructure

• A .github folder to hold workflow configurations

• Clear naming conventions and a well-written README.md

🛠 Tip: Use semantic commit messages and consider adopting Conventional Commits for clarity in versioning and changelogs.

2. Set Up Branch Protection Without Paid Features

While GitHub's more advanced rules require Pro, you can still:

• Require pull requests before merging

• Enable status checks to prevent broken code from landing in main

• Enforce linear history for cleaner version control

💡 This makes your project safer and more collaborative, without needing GitHub Enterprise.

3. Implement PR Templates and Automated Checks

Make your reviews smoother:

• Add a PULL_REQUEST_TEMPLATE.md to guide contributors

• Use GitHub Actions (which we'll set up in the next part) for linting, tests, and formatting checks

✨ These tiny improvements add polish and professionalism.

4. Configure GitHub Issue Templates and Project Boards

Even solo developers benefit from issue tracking:

• Add issue templates for bugs and features

• Use GitHub Projects to manage work with a Kanban board, all free and native to GitHub

📌 Bonus: This setup lays the groundwork for GitOps practices later on.

5. Advanced Technique: Set Up Custom Validation Scripts as Pre-Commit Hooks

Before code ever hits GitHub, you can catch issues locally with Git hooks. Using a tool like Husky or pre-commit, you can:

• Lint code before it's committed

• Run tests or formatters automatically

• Prevent secrets from being accidentally committed

// Initialize Husky and install needed dependencies
// Then add a pre-commit hook that runs tests before allowing the commit
npx husky-init && npm install
npx husky add .husky/pre-commit "npm test"

6. Sample CRUD App Setup:

Our CRUD app manages users (create, read, update, delete). Below is the minimal code with comments to explain each part:

Backend (backend/):

// backend/package.json
{
  "name": "crud-backend", // Name of the backend project
  "version": "1.0.0", // Version for tracking changes
  "scripts": {
    "start": "node index.js", // Runs the server
    "test": "echo 'Add tests here'", // Placeholder for tests (update with Jest later)
    "lint": "eslint ." // Checks code style with ESLint
  },
  "dependencies": {
    "express": "^4.17.1", // Web framework for API endpoints
    "pg": "^8.7.3" // PostgreSQL client to connect to the database
  },
  "devDependencies": {
    "eslint": "^8.0.0" // Linting tool for code quality
  }
}

// backend/index.js
const express = require('express'); // Import Express for building the API
const { Pool } = require('pg'); // Import PostgreSQL client
const app = express(); // Create an Express app
app.use(express.json()); // Parse JSON request bodies

// Connect to PostgreSQL using DATABASE_URL from environment variables
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

// Health check endpoint for Kubernetes probes and monitoring
app.get('/healthz', (req, res) => res.json({ status: 'ok' }));

// Get all users from the database
app.get('/users', async (req, res) => {
  const { rows } = await pool.query('SELECT * FROM users'); // Query the users table
  res.json(rows); // Send users as JSON
});

// Add a new user to the database
app.post('/users', async (req, res) => {
  const { name } = req.body; // Get name from request body
  // Insert user and return the new record
  const { rows } = await pool.query('INSERT INTO users(name) VALUES($1) RETURNING *', [name]);
  res.json(rows[0]); // Send the new user as JSON
});

// Start the server on port 3000
app.listen(3000, () => console.log('Backend running on port 3000'));

Frontend (frontend/):

// frontend/package.json
{
  "name": "crud-frontend", // Name of the frontend project
  "version": "1.0.0", // Version for tracking changes
  "scripts": {
    "start": "react-scripts start", // Runs the dev server
    "build": "react-scripts build", // Builds for production
    "test": "react-scripts test", // Runs tests (placeholder for Jest)
    "lint": "eslint ." // Checks code style with ESLint
  },
  "dependencies": {
    "react": "^17.0.2", // Core React library
    "react-dom": "^17.0.2", // Renders React to the DOM
    "react-scripts": "^4.0.3", // Scripts for React development
    "axios": "^0.24.0" // HTTP client for API calls
  },
  "devDependencies": {
    "eslint": "^8.0.0" // Linting tool for code quality
  }
}

// frontend/src/App.js
import React, { useState, useEffect } from 'react'; // Import React and hooks
import axios from 'axios'; // Import Axios for API requests

function App() {
  // State for storing users fetched from the backend
  const [users, setUsers] = useState([]);
  // State for the input field to add a new user
  const [name, setName] = useState('');

  // Fetch users when the component mounts
  useEffect(() => {
    axios.get('http://localhost:3000/users').then(res => setUsers(res.data));
  }, []); // Empty array means run once on mount

  // Add a new user via the API
  const addUser = async () => {
    const res = await axios.post('http://localhost:3000/users', { name }); // Post new user
    setUsers([...users, res.data]); // Update users list
    setName(''); // Clear input field
  };

  return (
    <div>
      <h1>Users</h1>
      {/* Input for new user name */}
      <input value={name} onChange={e => setName(e.target.value)} />
      {/* Button to add user */}
      <button onClick={addUser}>Add User</button>
      {/* List all users */}
      <ul>{users.map(user => <li key={user.id}>{user.name}</li>)}</ul>
    </div>
  );
}

export default App; // Export the component

Database Setup:

-- infra/db.sql
-- Create a table to store users
CREATE TABLE users (
  id SERIAL PRIMARY KEY, -- Auto-incrementing ID
  name VARCHAR(100) NOT NULL -- User name, required
);

crud-app/
├── backend/
│   ├── package.json
│   └── index.js
├── frontend/
│   ├── package.json
│   └── src/App.js
├── infra/
│   └── db.sql
├── .github/
│   └── workflows/
└── README.md

This app provides a /users endpoint (GET/POST) and a frontend to list/add users, stored in PostgreSQL. The /healthz endpoint supports monitoring. Save this code in your repo to follow the pipeline steps.

How to Build Your CI Pipeline with GitHub Actions

1. Set Up Your First GitHub Actions Workflow

First, let’s create a basic workflow that automatically builds, tests, and lints your app every time you push code or open a pull request. This ensures your app stays healthy and any issues are caught early.

Create a file at .github/workflows/ci.yml and add the following:

# CI workflow to build, test, and lint the CRUD app on push or pull request
name: CI Pipeline
on:
  push:
    branches: [main] # Trigger on pushes to main branch
  pull_request:
    branches: [main] # Trigger on PRs to main branch
jobs:
  build:
    runs-on: ubuntu-latest # Use GitHub's free Linux runner
    steps:
      - uses: actions/checkout@v3 # Check out the repository code
      - name: Set up Node.js # Install Node.js environment
        uses: actions/setup-node@v3
        with:
          node-version: '18' # Use Node.js 18 for consistency
      - name: Cache dependencies # Cache node_modules to speed up builds
        uses: actions/cache@v3
        with:
          path: ~/.npm # Cache npm’s global cache
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} # Key based on OS and package-lock.json
      - run: npm ci # Install dependencies reliably using package-lock.json
      - run: npm test # Run tests defined in package.json
      - run: npm run lint # Run ESLint to ensure code quality

This workflow automatically runs on every push and pull request to the main branch. It installs dependencies, runs tests, and performs code linting, with dependency caching to make builds faster over time.

Common Issues and Fixes:

• “Secret not found”: Ensure AWS_ACCESS_KEY_ID is in repository secrets (Settings → Secrets).

• Tests fail: Check test/users.test.js for database connectivity.

Understanding GitHub Actions' Free Tier Limits

Before building more workflows, it is important to know what GitHub offers for free.

If you are working on private repositories, you get 2,000 free minutes per month. For public repositories, you get unlimited minutes.

To avoid hitting limits quickly:

• Cache your dependencies to cut down install times.

• Only trigger workflows on meaningful branches (like main or release).

• Skip unnecessary steps when you can.

2. Creating a Multi-Stage Build Pipeline

As your app grows, it is better to split your CI pipeline into clear stages like install, test, and lint. This structure makes workflows easier to maintain and speeds things up, because some jobs can run in parallel.

Here’s how you can split the work into multiple jobs for better clarity:

jobs:
  install:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm ci  # Clean install of dependencies

  test:
    needs: install  # This job depends on the install job finishing
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm test  # Run test suite

  lint:
    needs: install  # This job also depends on install but runs in parallel with test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm run lint  # Run linting checks

By breaking the pipeline into stages, you can quickly spot which step fails, and your test and lint jobs can run at the same time after dependencies are installed.

3. Implement Matrix Builds for Cross-Environment Testing

When you want your app to work across different Node.js versions or databases, matrix builds are your best bet. They let you test across multiple environments in parallel, without duplicating code.

Here’s how you can set up a matrix strategy, to test across multiple environments simultaneously:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [14.x, 16.x, 18.x]  # Test on multiple Node versions
        database: [postgres, mysql]        # Test against different databases
    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm install
      - run: npm test  # This will run 6 different test combinations (3 Node versions × 2 databases)