Skip to content

The application layout

This page describes the files of an application that uvx xtr-cli new shop --webapp makes. A console application has the same files, but it has no web/ directory.

shop/
├── .env                      # environment variables, written by the recipes
├── AGENTS.md                 # the rules for a coding agent that works in this project
├── compose.yaml              # services for development, written by the recipes
├── pyproject.toml            # dependencies, console scripts and tool settings
├── xtr.lock                  # the recipes that the application applied
├── bin/console               # the console wrapper: `uv run shop`, from any directory
├── src/shop/
│   ├── __main__.py           # the console entry point: uv run shop
│   ├── kernel.py             # the kernel that each entry point builds
│   ├── command/              # the console commands of the application
│   ├── config/
│   │   ├── bundles.py        # the bundles and their environments
│   │   └── packages/         # one configuration file for each bundle
│   │       ├── dotenv.py     # the layers of the .env files
│   │       └── dev/          # configuration for the dev environment only
│   └── web/
│       ├── __main__.py       # the web entry point: uv run shop-web
│       ├── app.py            # the FastAPI application
│       └── routes.py         # the routes of the application
└── tests/

The kernel

src/shop/kernel.py contains the kernel. The kernel reads the bundles from config/bundles.py, and it reads the environment from the APP_ENV variable. Then it builds the container.

Each entry point builds and starts its own kernel. The console entry point runs a command. The web entry point serves the FastAPI application.

bin/console is the executable wrapper around uv run shop: it changes to the project's root first, so it works from any directory.

kernel: Final = Kernel(
    __package__,
    allowed_envs=("dev", "test", "prod"),
    exclude=(".web.app",),
)

The kernel scans the shop package for services. __package__ is the name of the package that contains kernel.py, so the name of the package is in one location only. The kernel shows this name as kernel.package.

The exclude argument keeps shop.web.app out of the scan, because that module builds the web application when Python imports it. A pattern that starts with a dot is relative to the application package. The kernel adds these patterns to DEFAULT_EXCLUDES, which keeps the tests and the __main__ modules out of the scan.

The bundles

src/shop/config/bundles.py lists the bundles of the application. Each bundle has a map of the environments where it is active:

BUNDLES = {
    DotenvBundle: {"all": True},
    OrmBundle: {"all": True},
    SecurityBundle: {"all": True},
}

The list has only the bundles that the application selects. A bundle can require other bundles. The kernel adds these bundles. The debug:bundles command shows each bundle with its source: listed, required or kernel.

The configuration files

Each file in src/shop/config/packages/ configures one bundle. The file has a function with the @configure decorator. The function returns the configuration object of the bundle:

@configure
def logging() -> LoggingConfig:
    """One console handler, on every channel, following the command's verbosity."""
    return LoggingConfig(handlers={"console": ConsoleHandlerConfig()})

A bundle works with no configuration file. A configuration file is necessary only to change the default values. The configuration guide shows how to change a value.

A directory in src/shop/config/packages/ is an environment directory. The name of the directory is the name of an environment. The kernel imports its files only for that environment, after the other configuration files. Thus, its values replace the values of the other files. The kernel does not import the directory of a different environment. The same rule applies to the directories in src/shop/config/routes/.

Each environment directory must have the name of an environment in allowed_envs. The kernel refuses a different name with UnknownEnvironmentFolderError.

Put the configuration of a bundle for development in src/shop/config/packages/dev/, for example the configuration of MakerBundle. A production installation does not have the package of that bundle. The kernel does not import the dev directory in production, so the application starts.

The environment files

The .env file contains the environment variables of the application. Each recipe writes its variables between two marker lines:

###> xtr-orm ###
DATABASE_URL=postgresql+asyncpg://app:!ChangeMe!@127.0.0.1:5432/app
###< xtr-orm ###

Warning

Do not put a real password or a real secret in .env. Git tracks .env. Put local values in .env.local, which .gitignore excludes.

The lock file

xtr.lock records the recipe of each package that the application applied. Git must track this file. recipes:sync --check compares the application with the lock file.

The folders of your code

Each class goes in the folder named after what the class is, under src/shop/. One module holds one public class.

Folder What it holds
entity/ the table definitions of the database
repository/ the queries of each entity
message/ the messages of the message bus
message_handler/ the handler of each message
scheduler/ the provider of each schedule
command/ the console commands
event/ the events of the application
event_listener/ a class that reacts to one event
event_subscriber/ a class that reacts to more than one event
remote_event/ the consumer of the events of each other system
webhook/ the request parser of each webhook
middleware/ the middleware of the message bus
stamp/ the stamps of an envelope
transport/ the transports of the message bus
security/voter/ the voters of the access decisions
service/ the other services of the application
exception/ the errors of the application

The template makes only the folders that its own files need. Create a folder when you write the first class for it. A folder must have an __init__.py file, because the kernel imports each module by its dotted name.

The make:* commands of xtr-maker write into these folders, and they create the folder and the __init__.py file when neither is there. The Generate code guide shows one flow.

The console commands

The commands of the application are in src/shop/command/. The console commands guide shows how to add a command.