Development

Git Workflow

main (production)
└── develop (integration)
    └── feature/<name> (desarrollo)
    └── bugfix/<name> (fixes)
    └── hotfix/<name> (urgentes)

Branch Naming

git checkout -b feature/user-authentication
git checkout -b bugfix/login-redirect
git checkout -b hotfix/security-patch

Commit Convention

git commit -m "feat(auth): add OAuth Google login"
git commit -m "fix(shipments): correct status update logic"
git commit -m "docs: update API endpoints table"

---

Pre-Commit Checklist

• [ ] Tests passing: uv run pytest tests/ -x -q
• [ ] Linting: uv run ruff check .
• [ ] Syntax check: python -m py_compile .

---

Backend Development

Project Structure

saas-backend/
├── core/              # Config, database, security
├── modules/           # Bounded contexts
│   └── <module>/
│       ├── domain/    # Entities, repository interfaces
│       ├── application/  # Use cases, DTOs
│       ├── infrastructure/  # SQLModel, services
│       └── presentation/  # FastAPI routes
├── shared/            # Cross-module utilities
└── tests/             # Test suite

Adding a New Module

# 1. Create domain layer
modules/<module>/domain/
├── entities.py
├── repositories.py
└── exceptions.py

# 2. Create application layer
modules/<module>/application/
├── dtos.py
├── interfaces/
└── usecases/

# 3. Create infrastructure layer
modules/<module>/infrastructure/
├── persistence/
└── services/

# 4. Create presentation layer
modules/<module>/presentation/
├── routes/
├── schemas/
└── dependencies.py

Layer Rules

Layer	Can Import
Domain	Only stdlib + shared contracts
Application	Domain + shared
Infrastructure	Application + core.database + ORM
Presentation	Application + infrastructure + FastAPI + Pydantic

---

Frontend Development

Project Structure

saas-fronted/
├── core/              # Infrastructure
│   ├── config.py
│   ├── error/
│   ├── network/
│   ├── security/
│   ├── storage/
│   └── theme/
├── modules/           # Feature modules
│   └── <module>/
│       ├── domain/
│       ├── data/
│       └── presentation/
└── shared/            # Reusable components

Flet Guidelines

1. SafeArea is mandatory on all pages
2. Check Flet docs before using controls
3. No deprecated APIs (ft.app, page.shared_preferences)
4. Use ft.run(main) entry point

i18n

# Static text
ft.Text(t("auth.login"))

# Reactive text (updates on language change)
t_text("auth.welcome", page, weight=ft.FontWeight.BOLD)

---

Debugging

Backend

# Verbose logging
uv run uvicorn main:app --reload --log-level debug

# PDB
import pdb; pdb.set_trace()

Frontend

# Hot reload (may crash)
uv run flet run

# Without hot reload (more stable)
uv run flet -r

---

Clean Architecture Checklist

• [ ] Layer Integrity: No mixing layers
• [ ] Framework Independence: Domain layer is pure Python
• [ ] Exception Mapping: Infrastructure exceptions → Domain exceptions
• [ ] Multi-Tenancy: RLS context manager used
• [ ] Dependency Direction: Points inward
• [ ] Datetime API: datetime.now(timezone.utc).replace(tzinfo=None)