Concepts

Place of apx in the ecosystem

This section describes the place of apx in the tech stack related to application development.

High level architecture and frameworks

Modern Pythonic application development is dominated by two different approaches:

1. Pythonic backend and frontend - using Python as the primary language for both backend and frontend.
2. Backend in Python, frontend in JavaScript - using Python for the backend and JavaScript for the frontend.

Practice shows that the second approach provides vastly more flexibility and allows to use the best tools for the job.

However, the problem is that combining (and supporting) a project with two mixed codebases and building tools is not a trivial task. It takes a certain amount of skills and knowledge to correctly configure the repository, understand the border between frontend and backend, and make sure that the project can be developed and deployed in a consistent way.

How apx fits into the ecosystem

apx is a tool that helps to solve the problem of combining a project with two mixed codebases and building tools.

It provides a set of commands and tools that help to:

• Configure the repository
• Connect your backend and frontend codebases
• Build and deploy your application

Specifically, apx does it in a following way:

1. On the backend side, apx uses Python as the primary language and FastAPI as the web framework.
2. apx automatically generates a type-safe API client for the frontend in TypeScript.
3. On the frontend side, apx uses React as the primary library and Vite as the build tool. To simplify the frontend development, apx uses shadcn/ui as the default set of UI components, and provides a CLI for working with shadcn registries.

A combination of the above practically resolves the problem of LLM hallucinations, so the only thing the developer needs to do is to describe the desired application behaviour, and then adjust the frontend by visual means and with the help of the MCP server.

Build Pipeline

When you run apx build, the following steps happen:

1. Frontend build — Vite compiles the React/TypeScript frontend into static assets
2. Asset embedding — Built assets are copied into the Python package's __dist__ directory
3. Wheel packaging — hatchling builds a Python wheel that includes both the backend code and the embedded frontend assets

The result is a single .whl file that contains everything needed to run the application. The FastAPI backend serves the built frontend assets at runtime — no separate frontend deployment is needed.

OpenAPI Bridge

The OpenAPI bridge is the mechanism that connects your Python backend to the TypeScript frontend with full type safety:

1. Python models — You define Pydantic models and FastAPI routes in Python
2. Schema extraction — apx extracts the OpenAPI schema from your FastAPI application
3. Code generation — The schema is transformed into a TypeScript client with React Query hooks

This means that when you add a new endpoint or modify a Pydantic model, the TypeScript client is regenerated automatically. Your frontend code gets type-safe hooks (useListItems, useCreateItem, etc.) that match your backend exactly. Import mismatches and payload errors are caught at compile time rather than at runtime.

During development (apx dev start), the OpenAPI watcher monitors your Python files and regenerates the client on every change. During build (apx build), the client is generated once as part of the build pipeline.

Deployment Model

Applications developed with apx are ready to be deployed as Databricks Apps. The deployment flow:

1. apx build produces a Python wheel with embedded frontend assets
2. databricks bundle deploy uploads the wheel and applies the databricks.yml configuration
3. Databricks Apps runtime installs the wheel and starts the FastAPI server

The databricks.yml file (generated by apx init) defines the app configuration, including the entrypoint, environment variables, and resource permissions. The FastAPI backend runs as a single process that serves both the API endpoints and the static frontend assets.

Workspaces

For projects that need to coexist with other Python packages in a monorepo, apx supports uv workspaces. This allows you to add a Databricks App as a member of an existing Python workspace, sharing dependency resolution and a single git repository.