Vlahx: A Modular Web Platform

Vlahx is a modular web platform built with Python and FastAPI. It provides the core infrastructure needed to run a web application while keeping additional functionality and presentation separate from the core itself.

The idea is simple: the Core provides the engine, plugins extend what the platform can do, and themes control how that functionality is presented.

What is under the hood?

Vlahx is built around a small and deliberately focused set of technologies:

  • Python is the programming language behind the platform.
  • FastAPI provides the web application framework and ASGI application layer.
  • SQLite provides the relational database used by the platform.
  • Jinja is used to render HTML templates.
  • Bootstrap provides the main front-end UI foundation.
  • JavaScript handles client-side behavior where needed.

These technologies are not the architecture by themselves. They are the components from which the architecture is built. The interesting part begins when Python starts executing the application and these components begin working together.

SQLite is not the database it used to be

SQLite is sometimes still described as a small or development-only database, mostly because many developers remember how it was commonly used years ago.

That description is too simplistic today.

SQLite is a full relational database engine designed to run embedded inside the application rather than as a separate database server. It provides transactions, indexes, constraints, SQL queries and many other features expected from a serious relational database.

For Vlahx, this is a deliberate choice. The platform does not need a separate database server simply because it is a web application. Keeping the database embedded makes installation and deployment considerably simpler while remaining perfectly appropriate for the workloads Vlahx is designed to handle.

That does not mean SQLite is the right answer for every application. Larger deployments, heavy concurrent write workloads, or applications requiring database-server features may be better served by PostgreSQL or another server-based database. The important point is that using SQLite in Vlahx is a design decision, not a shortcut.

How can Vlahx be run?

Vlahx does not depend on Docker.

The application can run directly on a host machine as long as the required Python environment and dependencies are available. A Python virtual environment is a convenient way to isolate those dependencies:

python -m venv .venv python run.py

It can also run inside Docker. In that case, Python and the application dependencies live inside the container instead of directly on the host.

The important distinction is that Docker and a Python virtual environment solve different parts of the deployment problem. Neither changes the Vlahx application itself. They provide different environments in which the same application can run.

Vlahx can therefore be thought of as:

Host machine └── Python environment └── Vlahx or Docker └── Python environment └── Vlahx

The current project environment uses Python 3.14, while the application code was previously developed and tested on Python 3.11. The important requirement for the platform is that the Python version is compatible with the application's dependencies and code.

Starting the application

There is a small but important distinction between the files that start Vlahx and the application itself.

On a Linux or macOS system, run.sh can prepare the Python environment and start the application. A developer can also invoke run.py directly.

Docker follows the same general path: the container prepares the Python environment and eventually starts run.py.

This means that different ways of launching Vlahx eventually converge on the same Python application.

run.sh ───────┐ β”‚ Docker ───────┼──→ run.py ──→ main.py ──→ Vlahx β”‚ direct Python β”˜

This is where the filesystem view of the project starts to become less useful.

Once run.py starts the application, Python begins importing and executing the code that makes up Vlahx. The application is no longer just a collection of files sitting in a directory. It becomes a running process with objects, routes, middleware, plugins, templates, database connections and other components working together.

The invisible architecture

If we look at the project directory, we can see where the code lives. We cannot see the complete runtime architecture simply by looking at those files.

The runtime architecture is created when Python executes them.

In other words:

Source code ↓ Python execution ↓ Application initialization ↓ Runtime objects and relationships ↓ Running Vlahx application

This is the part of Vlahx that we want to understand throughout this documentation.

The source tree tells us where things are implemented. The runtime flow tells us how those things work together.

And this is where main.py becomes our first real doorway into Vlahx.

main.py — where the application comes together

The main.py file is not the whole Vlahx engine. It is the place where many of the major pieces are brought together to create the FastAPI application.

Its create_app() function creates the FastAPI instance and begins the application initialization process.

Among other things, it initializes the database, synchronizes the active theme, mounts static files, configures session middleware, builds the Jinja template environment, loads plugins, installs HTTP middleware and registers the application's routers.

At the end of the file, the application is created and exposed as app:

app = create_app()

That object is what the ASGI server eventually serves.

When everything has been initialized successfully, Uvicorn can report:

Started server process [1] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000

That final message is more than a comforting line in a terminal. It is an observable trace of a much larger process that happened inside Python.

The files are the pack.

The running application is the pack moving.

We cannot see every interaction simply by looking at the source tree, but we can observe the traces left behind by the running system through logs, HTTP requests, database changes, rendered templates and application behavior.

In the next chapter, we will stop looking at Vlahx from the outside and follow that process from run.py into main.py. We will start following the pack.