Project Structure Requirements

Phemeral analyzes your repository to determine how to build and run your application. This page describes what Phemeral looks for and how to structure your project for successful detection.

Project Root Detection

The project root is the directory that contains your dependency file. Phemeral searches for dependency files in this priority order:

1. uv.lock
2. poetry.lock
3. pyproject.toml
4. requirements.txt

The search walks the directory tree from the repository root, favoring files at shallower depths. The directory containing the first matching file becomes the project root.

Example

Given this repository structure:

my-repo/
├── README.md
├── backend/
│   ├── pyproject.toml
│   ├── uv.lock
│   └── app/
│       └── main.py
└── frontend/
    └── ...

Phemeral finds uv.lock at backend/uv.lock and sets the project root to backend/.

Directory Structure Examples

FastAPI with uv

my-project/
├── .python-version
├── pyproject.toml
├── uv.lock
└── app/
    └── main.py          # app = FastAPI()

Flask with poetry

my-project/
├── .python-version
├── pyproject.toml
├── poetry.lock
└── app/
    └── main.py          # app = Flask(__name__)

Django with pip

my-project/
├── .python-version
├── requirements.txt
└── myproject/
    ├── manage.py
    ├── myproject/
    │   ├── settings.py
    │   ├── urls.py
    │   └── asgi.py      # application = get_asgi_application()
    └── myapp/
        └── ...

Monorepo (Backend in Subdirectory)

my-repo/
├── frontend/
│   └── ...
└── backend/
    ├── pyproject.toml
    ├── uv.lock
    └── app/
        └── main.py      # app = FastAPI()

Phemeral detects backend/ as the project root because uv.lock is located there.

Python Version

Place a .python-version file at or near your project root containing the Python version:

3.11

Phemeral searches for this file starting at the project root. If not found, Python 3.12 is used as the default.

Application Entry Point

Phemeral scans .py files in your project for framework instantiation.

Ensure your framework instance is assigned to a module-level variable:

# app/main.py
from fastapi import FastAPI

app = FastAPI()  # Phemeral detects "app" as the object name

@app.get("/")
def read_root():
    return {"message": "Hello, World!"}

Checklist

Before deploying, verify that your project includes:

• A dependency file (uv.lock, poetry.lock, pyproject.toml, or requirements.txt)
• A .py file that imports and instantiates a supported framework (FastAPI, Flask, or Django)
• The framework instance is assigned to a module-level variable
• Optionally, a .python-version file specifying your Python version