Chapter 4 — The Frontend Runtime: From Request to HTML

In the previous chapters, we looked at how Vlahx starts, how its Core manages configuration and extensions, and how plugins can behave as independent applications inside the platform.

There is now one important part of the runtime left to follow: what happens when a browser asks Vlahx for a page.

A request does not simply reach a template and become HTML. It passes through several layers of the application. The router coordinates the request, application logic prepares the data, the template runtime builds the rendering context, and the template system combines Core, theme, and plugin resources into the final response.

This chapter follows that path.

1. From an HTTP Request to an Application Response

At the HTTP level, Vlahx exposes several kinds of routes. Some return HTML pages intended for a browser. Others return JSON and are intended for JavaScript code or external clients.

                    VLAHX HTTP LAYER
                          │
             ┌────────────┴────────────┐
             ↓                         ↓
        HTML ROUTES               API ROUTES
             │                         │
             ↓                         ↓
     render_template()               JSON
             │                         │
             ↓                         ↓
          Browser                JS / clients

The distinction is important.

An API endpoint does not need the template system at all. For example, a status endpoint can obtain a database session, perform a simple database check, and return JSON directly.

An HTML route follows a different path. It eventually needs a complete rendering context and a template from which HTML can be generated.

This makes the router the natural boundary between HTTP and the application runtime.

2. The Router as an Orchestration Layer

A Vlahx router is not the frontend and it is not the database layer.

Its job is primarily to coordinate the request.

HTTP request
     ↓
FastAPI route
     ↓
authentication / authorization
     ↓
application logic
     ↓
database / services
     ↓
context
     ↓
render_template()
     ↓
HTML response

For example, an administrative route may first verify that the current user has the required role, retrieve data from the database, prepare the values needed by the page, and then call render_template().

The router therefore knows which operation is being requested. It does not need to know how Jinja locates templates, how themes override templates, or how plugin template hooks are assembled.

Those responsibilities belong to the template runtime.

3. The Template Runtime

The central piece of this layer is Vlahx's templates.py.

It would be easy to describe this file as a small wrapper around Jinja2. That would miss most of its purpose.

The template runtime is where several parts of the platform are brought together before a page is rendered.

Router
  │
  │ application context
  ↓
render_template()
  │
  ├── request information
  ├── current user
  ├── locale and translations
  ├── site configuration
  ├── navigation
  ├── SEO information
  ├── theme information
  └── plugin-provided content
  │
  ↓
Jinja environment
  │
  ↓
template resolution
  │
  ↓
HTML

This means that render_template() is more than a rendering helper. It is one of the main composition points of the Vlahx runtime.

The router supplies page-specific information. The template runtime supplies the platform-wide environment in which that page exists.

4. Building the Context of a Page

A template needs more than the data belonging to one particular page.

A normal Vlahx page may need to know who is currently logged in, which language is active, what the site name is, what navigation items should be displayed, which theme is active, and what plugin-provided elements should appear in specific areas of the interface.

The template runtime assembles this information into the context available to Jinja.

                    PAGE CONTEXT
                         │
       ┌─────────────────┼─────────────────┐
       ↓                 ↓                 ↓
    Request          Application       Platform
                         data           context
                                            │
                    ┌─────┼─────┬──────────┐
                    ↓     ↓     ↓          ↓
                  User  Locale  Theme    Plugins
                                            │
                                            ↓
                                      Template hooks

This is one of the reasons the frontend of Vlahx can remain relatively simple. Templates do not need to independently reconstruct the state of the application. The runtime prepares that state before rendering begins.

5. How Vlahx Finds a Template

The next question is where the template itself comes from.

Vlahx does not depend on one fixed template directory. The Jinja environment uses a loader chain that allows multiple sources to participate in template resolution.

                 TEMPLATE REQUEST
                       │
                       ↓
                Active Theme
                       │
              not found?
                       ↓
                Minimal Theme
                       │
              not found?
                       ↓
             Plugin Templates
                       │
              not found?
                       ↓
              Core Templates

This order is important because it creates an override mechanism.

The Core can provide a default template. A theme can provide its own version. A plugin can provide templates belonging to its own interface.

The template system therefore does not have to contain special cases such as:

if active_theme == "something":
    use_this_template()

The loader mechanism itself determines which resource is selected.

This is a much cleaner separation between the template consumer and the source of the template.

6. Themes Are Part of the Runtime

At this point, it is useful to change the way we think about a theme.

A theme is not simply a collection of CSS files.

In Vlahx, the active theme participates in template resolution. It can therefore influence the actual HTML structure returned to the browser.

                    VLAHX
                      │
                 Template Runtime
                      │
                      ↓
                 Active Theme
                  │         │
                  ↓         ↓
              Templates   Assets
                  │         │
                  └────┬────┘
                       ↓
                    Browser

The result is that frontend appearance and frontend structure can be changed without modifying the Core router that requested the page.

The router can continue asking for the same template while the active theme determines which implementation is ultimately rendered.

This is one of the key consequences of separating the application runtime from the presentation layer.

7. Plugins Can Enter the Frontend

The same principle applies to plugins.

A plugin can have its own templates, but it can also participate in the platform's template hooks.

                         Plugin
                           │
             ┌─────────────┴─────────────┐
             ↓                           ↓
       Plugin templates             Template hooks
             │                           │
             ↓                           ↓
       Loader chain              navbar / sidebar /
                                 footer / dashboard /
                                 login / other areas
             │                           │
             └─────────────┬─────────────┘
                           ↓
                    Rendered page

This creates two different forms of frontend integration.

The first is ownership: a plugin can provide templates for pages belonging to the plugin itself.

The second is participation: a plugin can contribute content to interfaces controlled by the Core.

These are conceptually different, and Vlahx supports both.

This is also where the architecture described in Chapter 3 becomes visible from the frontend side. The Core provides the runtime and the extension points. A plugin decides how much of that environment it wants to use.

8. The Template Runtime Is Also an Integration Point

The frontend is therefore not isolated from the rest of Vlahx.

Configuration, authentication, internationalization, navigation, plugins, themes, and SEO all meet at the template runtime.

                  CORE RUNTIME
                       │
       ┌───────────────┼────────────────┐
       ↓               ↓                ↓
 Configuration      i18n          Authentication
       │               │                │
       └───────────────┼────────────────┘
                       ↓
                Template Runtime
                       ↑
                       │
              ┌────────┴────────┐
              │                 │
            Theme            Plugins
              │                 │
              └────────┬────────┘
                       ↓
                    Jinja
                       ↓
                     HTML

This makes templates.py an important architectural boundary.

The router does not need to know how all these systems are assembled. The individual plugins do not need to know how the entire page is constructed. The theme does not need to know which router requested the page.

Each part contributes its own information or resources, while the template runtime composes them into one response.

9. Rendering the Final Page

Once the context and template have been resolved, Jinja performs the final rendering step.

Request
   ↓
Router
   ↓
Application logic
   ↓
Page context
   ↓
render_template()
   ↓
Jinja environment
   ↓
Template loader
   ↓
Theme / Plugin / Core template
   ↓
Rendered HTML
   ↓
HTTP response
   ↓
Browser

From the browser's point of view, the result is simply an HTML document.

Behind that document, however, several independent runtime systems have already participated in its creation.

This is the important architectural point: the browser receives one page, but Vlahx builds that page from multiple runtime layers.

10. Where JavaScript Enters the Picture

So far, the flow described in this chapter is primarily server-side.

Vlahx first generates HTML on the server. The browser then receives that HTML together with the frontend assets required by the page.

JavaScript can subsequently add client-side behavior, interact with API endpoints, update parts of the interface, and perform operations that do not require a complete page reload.

                SERVER
                  │
      Router → Context → Jinja
                  │
                  ↓
                HTML
                  │
                  ↓
               Browser
                  │
             ┌────┴────┐
             ↓         ↓
            CSS       JavaScript
                       │
                       ↓
                    API calls
                       │
                       ↓
                     JSON

This creates a natural separation between the server-rendered application and browser-side behavior.

The detailed structure of themes, static assets, JavaScript, CSS, and template inheritance belongs to the next layer of the architecture and will be examined separately.

Conclusion

The Vlahx frontend is not a separate application sitting on top of the backend.

It is another part of the runtime.

A request enters through FastAPI, a router coordinates the operation, application logic prepares the page data, and the template runtime builds the environment in which that data becomes HTML. Themes and plugins can participate without forcing the router to know their implementation details.

                 HTTP REQUEST
                      ↓
                    Router
                      ↓
              Application Logic
                      ↓
                   Context
                      ↓
              Template Runtime
                      ↓
             ┌────────┼────────┐
             ↓        ↓        ↓
           Theme    Plugins    Core
             └────────┼────────┘
                      ↓
                    Jinja
                      ↓
                     HTML
                      ↓
                   Browser

This is the bridge between Vlahx's backend architecture and its frontend architecture.

The backend decides what the application does. The template runtime decides how the application's current state becomes a page. Themes and plugins then allow that page to be extended or transformed without requiring the Core to know every possible frontend implementation.

In the next chapter, we can move one level deeper and examine the theme itself: its structure, template overrides, assets, inheritance, and the way a Vlahx installation can change its frontend without changing the application logic behind it.

What's Next?

With Chapter 4, the Vlahx Docs series reaches the end of its architectural introduction.

You have now followed Vlahx from the application startup process, through the Core configuration and extension model, all the way to the frontend runtime and the generation of the final HTML response.

The next step is no longer to explain how Vlahx works as a platform, but to start building on top of it.

For that purpose, Vlahx provides two dedicated documentation categories:

Plugins Docs

Learn how to build Vlahx plugins — from the basic plugin structure and registration process to routes, databases, settings, hooks, events, templates, APIs and complete plugin applications.

Themes Docs

Learn how to build Vlahx themes — including theme structure, templates, overrides, inheritance, assets and integration with the Vlahx template runtime.

The architectural foundation is now in place.

It's time to build.