Conventions

create-mountaineer-app generates the structure below. You can also create it by hand.

If you want the rationale behind these conventions before adopting them, see Philosophy & Tradeoffs.

For a project called my_webapp:

my_webapp/
├── README.md
├── docker compose.yml
├── my_webapp
│   ├── __init__.py
│   ├── app.py
│   ├── cli.py
│   ├── config.py
│   ├── controllers
│   │   ├── __init__.py
│   │   ├── detail.py
│   │   └── home.py
│   ├── main.py
│   ├── models
│   │   ├── __init__.py
│   │   └── detail.py
│   └── views
│       ├── app
│       ├── node_modules
│       ├── package-lock.json
│       ├── package.json
│       ├── postcss.config.js
│       └── tailwind.config.js
├── uv.lock
└── pyproject.toml

Application code lives in the my_webapp Python package. Add modules and import them as you would in any Python project.

Mandatory Conventions

views contains the React and TypeScript project, including package.json and tsconfig.json. Organize nested views in nested folders.

To give sections of your app separate layouts, use the (root) folder pattern described in Layout Organization.

Suggested Conventions

controllers - Python classes that supply data and actions to your views. Start with a flat folder; split it into subfolders when distinct areas of the application emerge.

app.py - Instantiate your controllers and add them to an AppController to register them for client access.

config.py - Define settings such as the database host and secret keys. Configuration can read environment variables and is accessible throughout the app.

main.py - Expose your application to uvicorn or another async compatible webserver that follows the ASGI specification (Asynchronous Server Gateway Interface).