backend/
├── app/
│   ├── main.py              # FastAPI app with lifespan
│   ├── config.py            # Pydantic settings
│   ├── database.py          # SQLModel session factory
│   ├── api/
│   │   ├── deps.py          # Auth & session dependencies
│   │   └── routes/
│   │       ├── tasks.py     # Task CRUD
│   │       ├── chat.py      # AI chat
│   │       ├── notifications.py
│   │       ├── websocket.py
│   │       └── health.py
│   ├── models/              # SQLModel entities
│   ├── schemas/             # Pydantic schemas
│   ├── services/            # Business logic
│   └── mcp/                 # MCP tools for AI
├── alembic/                 # Migrations
├── tests/                   # pytest tests
└── pyproject.toml

# All I/O operations use async/await
async def get_tasks(session: AsyncSession, user_id: str) -> list[Task]:
    result = await session.exec(
        select(Task).where(Task.user_id == user_id)
    )
    return result.all()

from typing import Annotated
from fastapi import Depends

CurrentUserDep = Annotated[CurrentUser, Depends(get_current_user)]
SessionDep = Annotated[AsyncSession, Depends(get_session)]

@router.get("/tasks")
async def list_tasks(
    current_user: CurrentUserDep,
    session: SessionDep
) -> list[TaskResponse]:
    ...

# Always filter by user_id
tasks = await session.exec(
    select(Task)
    .where(Task.user_id == current_user.id)
    .order_by(Task.created_at.desc())
)

cd backend

# Install dependencies
pip install -e ".[dev]"

# Run development server
uvicorn app.main:app --reload --port 8000

# Run migrations
alembic upgrade head

# Run tests
pytest -v

# Create migration
alembic revision --autogenerate -m "description"

DATABASE_URL=postgresql+asyncpg://user:pass@localhost/db
BETTER_AUTH_SECRET=your-32-char-secret
GEMINI_API_KEY=your-api-key
KAFKA_BOOTSTRAP_SERVERS=localhost:9092
KAFKA_ENABLED=true
CORS_ORIGINS=http://localhost:3000