Folder Structure

backend-api/
├── app/
│   ├── main.py                # Entry point — create_app() + FastAPI instance
│   │
│   ├── api/                   # Route definitions (thin — delegate to services)
│   │   ├── deps.py            # Shared dependencies (auth, db session)
│   │   └── v1/
│   │       ├── __init__.py    # api_router — includes all v1 routers
│   │       ├── users.py
│   │       └── projects.py
│   │
│   ├── services/              # Business logic (no FastAPI imports here)
│   │   ├── users.py
│   │   ├── projects.py
│   │   ├── push.py            # FCM send helpers
│   │   ├── uploads.py         # S3 presigned URLs
│   │   └── email/             # Email provider adapters
│   │       ├── __init__.py    # Factory (ses | sendgrid | brevo)
│   │       ├── ses.py
│   │       ├── sendgrid.py
│   │       └── brevo.py
│   │
│   ├── middleware/            # ASGI middleware & exception handlers
│   │   ├── errors.py
│   │   └── rate_limit.py
│   │
│   ├── models/                # SQLAlchemy ORM models
│   │   └── user.py
│   │
│   ├── schemas/               # Pydantic request/response models
│   │   ├── users.py
│   │   └── projects.py
│   │
│   ├── db/                    # Database config & session factory
│   │   ├── session.py         # Async engine + session maker
│   │   └── migrations/        # Alembic migrations
│   │
│   ├── core/                  # Cross-cutting config & security
│   │   ├── config.py          # Pydantic settings
│   │   ├── security.py        # Cognito JWT verification
│   │   └── logging.py
│   │
│   └── lib/                   # Shared clients
│       ├── supabase.py
│       ├── s3.py
│       └── fcm.py
│
├── tests/
│   ├── unit/
│   └── integration/
│
├── .env.example
├── docker-compose.yml
├── Dockerfile
├── pyproject.toml
└── uv.lock

# app/api/v1/projects.py
from fastapi import APIRouter, Depends
 
from app.api.deps import CurrentUser, require_scope
from app.schemas.projects import ProjectCreate, ProjectOut
from app.services import projects as projects_service
 
router = APIRouter(prefix="/projects", tags=["projects"])
 
 
@router.get("", response_model=list[ProjectOut])
async def list_projects(user: CurrentUser):
    return await projects_service.list_by_user(user.sub)
 
 
@router.post("", response_model=ProjectOut, status_code=201)
async def create_project(
    payload: ProjectCreate,
    user: CurrentUser,
    _: None = Depends(require_scope("write:projects")),
):
    return await projects_service.create(user.sub, payload)

# app/schemas/projects.py
from datetime import datetime
from pydantic import BaseModel
 
 
class ProjectCreate(BaseModel):
    name: str
    description: str | None = None
 
 
class ProjectOut(BaseModel):
    id: str
    name: str
    owner_id: str
    created_at: datetime
 
    model_config = {"from_attributes": True}

# app/services/projects.py
from sqlalchemy import select
 
from app.db.session import async_session
from app.models.project import Project
 
 
async def list_by_user(user_id: str) -> list[Project]:
    async with async_session() as session:
        result = await session.execute(
            select(Project).where(Project.owner_id == user_id)
        )
        return list(result.scalars().all())