Project Structure

Running buraq startproject myblog creates:

myblog/
├── config/
│   ├── __init__.py
│   ├── settings.py       # all project settings
│   └── urls.py           # root URL config — urlpatterns and nothing else
├── templates/
│   └── base.html
├── static/
│   ├── css/
│   └── js/
├── tests/
│   └── test_smoke.py     # one passing test, so `buraq test` reports something
├── main.py               # ASGI entry point — builds the application
├── manage.py             # CLI — buraq <command>
├── pyproject.toml
├── .env
└── .gitignore

After running buraq startapp posts:

myblog/
├── posts/
│   ├── __init__.py
│   ├── models.py
│   ├── views.py
│   ├── urls.py
│   ├── forms.py
│   ├── admin.py
│   ├── schemas.py        # Pydantic schemas for JSON endpoints — see Schemas
│   ├── apps.py           # AppConfig: display name, startup hook — optional
│   └── migrations/
│       └── __init__.py
...

Key files

config/settings.py

All configuration lives here — database, installed apps, middleware, cache, email, etc. See Settings for the full reference.

config/urls.py

The root URL configuration. Creates the app instance and loads all URL patterns.

from buraq.urls import path, include

urlpatterns = [
    path("/auth",  include("buraq.contrib.auth.urls")),
    path("/posts", include("posts.urls")),
]

manage.py

The same entry point as the buraq command, run from inside the project. Both do the same thing, in whatever environment you are already in:

buraq runserver
buraq runserver 8080       # custom port
buraq makemigrations
buraq migrate
buraq startapp <name>
buraq createsuperuser

alembic/

Buraq uses Alembic for database migrations — the same tool SQLAlchemy recommends. makemigrations and migrate are thin wrappers over Alembic commands.