What is this thing?

FPT Cloud BSS is the cloud portal that lets FPT's customers spin up virtual machines, networks, Kubernetes clusters, S3-style storage, and backups — without ever touching the underlying hardware.

The folder you're looking at, portal-api-dev, is the brain of the backend. It's not one program — it's a whole town of cooperating Python services.

The numbers, in one glance

If that sounds intimidating — relax. You don't read every street to know a city. You learn the shape of it. That's what this course does.

A click is the start of a long journey

Imagine a customer logs into the portal, fills out a form to make a new VPC, and clicks Create. Their browser sends one HTTP request. Look what's actually waiting on the other end:

That single click triggered five different processes in three different machines. None of them know about all the others — and yet, somehow, a working network appears two minutes later. The rest of this course explains how.

Why you should care

It's a relay race, not a marathon

This codebase isn't one giant program. It's a relay team. Each runner carries the baton for their leg of the race, then passes it on. If you yell at the wrong runner, nothing improves.

Here's the team. Memorize these five names — half of all your debugging will be "which one of these is the problem?"

A peek at the brain booting up

Here is the actual code that starts the User service in development. This is the literal entry point — what runs when a developer presses Run in PyCharm.

import os, sys
from dotenv import load_dotenv
load_dotenv()
sys.path.append("../portal-api-core")
sys.path.append("../fptcloud-api")
env = os.environ
env["FLASK_DEBUG"] = "1"
import service
svc = service.Service()
app = svc.app
if __name__ == "__main__":
    svc.run(port=5001, threaded=True)

Who reports to whom?

None of these services know about all the others. The relationships are deliberately one-directional — that's what keeps the town from collapsing into chaos.

Quiz: which runner gets the baton?

Two channels, very different rules

Services need to coordinate — but not all coordination is the same. Some things must happen now ("is this user logged in?"). Some things can happen eventually ("provision this VM, it'll take 90 seconds").

This codebase uses two distinct channels for those two situations:

A real conversation, group-chat style

Here's what the services actually "say" to each other when a customer creates a VPC. Tap through the messages:

The shared whiteboard: the database

Notice how nobody in that conversation says "here's the VPC data, please pass it along". Instead, everyone reads and writes the same database row. The DB is the shared whiteboard the whole team works on.

vpc = md.VPC(
    id=self.create_uuid(),
    created_at=date_util.utc_now(),
)
ctx.args["_vpc"] = vpc
data_util.assign_model_data(
    vpc,
    dict(
        status=md.VPCStatus.INIT,
        type=type, name=name,
        project_id=project_id,
        cidr=cidr,
    ),
)

Quiz: spot the right channel

The portal owns nothing — it just orchestrates

This is the secret most people miss when they first see a cloud portal: nearly all the hard work is done by other systems. The portal is a conductor in front of an orchestra — it doesn't play any instruments itself.

Why "calls an outside system" is a big deal

Every time the portal calls something it doesn't own, three new failure modes appear at once. As an AI-coding-tool driver, you need to feel these in your gut:

A scheduled job, in the wild

Here's how the cron service decides when to run a recurring job. Real code from portal-celery/index.py:

def init_crontab_from_expression(expression: str) -> crontab:
    fields = expression.split(" ")
    return crontab(
        minute=fields[0],
        hour=fields[1],
        day_of_month=fields[2],
        month_of_year=fields[3],
        day_of_week=fields[4],
    )

A true story: the duplicate VPC bug

Customers reported that sometimes, after clicking Create VPC, they ended up with two identical VPCs in their account — same name, same network range, same created-at timestamp down to the second.

This actually happened in this codebase. The fingerprints in the database were unmistakable: identical timestamps. Two things had been created at the exact same instant. Why?

The two suspects

Two patterns in this codebase, working together, made the bug possible:

Either suspect alone is annoying. Together, they're a duplicate factory. And neither piece of code was "wrong" in isolation — that's what makes these bugs hard.

The fix has a name: idempotency

The cure for "the same operation accidentally ran twice" is to make sure that running it twice produces the same result as running it once. Engineers call this idempotency — and it's one of the most important concepts in this whole course.

The most common ways to make an operation idempotent:

Spot the bug

Here's a simplified version of the kind of Celery task that caused the duplicates. Click the line that's the root problem.

Hint: it's not any single line being "wrong" — it's what the function signature is missing that makes the retries dangerous.

Quiz: debugging instincts

You made it through the town

You now know the five services, the two channels they talk on, the outside systems they orchestrate, and the most common way they fail. That's already more architectural literacy than most developers who've worked on a codebase like this for a month.

Next time you tell an AI agent to "add a feature to the portal", you can be specific: which service, which channel, what idempotency key. That specificity is the difference between AI that builds the right thing and AI that confidently builds the wrong thing.