Chapter 1: Project Setup¶
Tools: bluefox-cli, bluefox-core, bluefox-auth
This chapter uses bfx init to scaffold a project with core and auth already wired up.
What you'll build¶
By the end of this chapter you'll have:
- A new Bluefox project with the standard directory structure
- Database migrations ready to run
- Auth (login, register, password reset) working out of the box
- A local dev server running with hot reload
Scaffold the project¶
Creating project 'taskflow'...
Project 'taskflow' created successfully!
Next steps:
cd taskflow
bfx db migrate initial
bfx dev
bfx init generates a complete project structure:
taskflow/
├── app/
│ ├── __init__.py
│ ├── main.py # App factory
│ ├── settings.py # BluefoxSettings config
│ └── routes/
│ └── __init__.py
├── migrations/
│ └── env.py # Alembic config (pre-wired)
├── tests/
│ └── conftest.py
├── .env # Local settings
├── pyproject.toml
└── Makefile
Set up the database¶
This creates an Alembic migration with the base tables — including the auth tables for users, sessions, and password resets.
Run the dev server¶
Visit http://localhost:8000 — you'll see the Bluefox welcome page.
What you get out of the box¶
The scaffolded app comes with everything wired up:
/health— health check endpoint (checks database connection)/auth/register— user registration/auth/login— JWT login/auth/me— current user profile- Structured logging — JSON output, request IDs, correlation
- CORS and exception handlers pre-configured
- Alembic migrations pointed at your database
You didn't write any of that. bfx init set it up, and bluefox-core + bluefox-auth provide the runtime. Convention over configuration.
Explore the generated code¶
Open app/main.py:
from bluefox_core import BluefoxSettings, create_bluefox_app
from bluefox_auth import setup_auth
settings = BluefoxSettings()
app = create_bluefox_app(settings, welcome=True)
setup_auth(app, settings)
The welcome=True flag enables the built-in welcome page you saw at http://localhost:8000. The entire app factory is just composing Bluefox packages together. As you add more packages in later chapters, you'll follow the same pattern.
When you're ready to start building your own routes, remove welcome=True and you'll have a clean slate:
from bluefox_core import BluefoxSettings, create_bluefox_app
from bluefox_auth import setup_auth
settings = BluefoxSettings()
app = create_bluefox_app(settings)
setup_auth(app, settings)
Open app/settings.py:
from bluefox_core import BluefoxSettings
class Settings(BluefoxSettings):
app_name: str = "taskflow"
Extend BluefoxSettings when you need app-specific config. It reads from .env automatically via Pydantic Settings.
Next: Chapter 2: Testing