Housegur FastAPI Development
Short, actionable guidance for AI coding agents working on the housegur-api FastAPI project.
What This App Is
**Framework**: FastAPI application (entry point: `app/main.py`)**Routing**: Routers in `app/routers/` included in `app/main.py` with prefixes: `/auth`, `/properties`, `/transactions`**Database**: SQLAlchemy engine in `app/database.py` but uses raw SQL and stored procedures (no ORM models)**Business Logic**: `app/crud.py` contains DB calls using `sqlalchemy.text` and calls stored procedures (e.g., `sp_comprar_tokens`, `sp_vender_tokens`) in the `housegur` schema**Schemas**: Pydantic request/response models in `app/schemas.py` used as `response_model` in routersKey Conventions & Patterns
Database Access
Use `SessionLocal()` from `app/database.py` for DB accessAlways close the session in a `finally` block (see `app/crud.py` and `app/routers/properties.py`)Prefer raw SQL via `text(...)` and stored-procedure calls for write operationsExample: `app/crud.comprar_tokens` calls `CALL housegur.sp_comprar_tokens(...)`Architecture Pattern
**Router → CRUD separation**: Router functions (in `app/routers/*`) are thin and delegate to `app/crud.py`Response shaping: Router endpoints return plain dicts or values from `app/crud.py` that must match the Pydantic response model field namesField names use Spanish conventions (e.g., `propiedad_id`, `usuario_id`, `nombre`)Environment
`app/database.py` reads `DATABASE_URL` via `python-dotenv`Ensure `.env` has `DATABASE_URL` for local runsAdding a New Endpoint
Follow this checklist when implementing new features:
1. **Define schemas**: Add Pydantic request/response models in `app/schemas.py`
2. **Implement DB logic**: Add function in `app/crud.py` using `SessionLocal()` and `sqlalchemy.text` (or call an existing stored procedure)
3. **Create router**: Add new router under `app/routers/` with appropriate prefix and `response_model`, delegating to `app.crud`
4. **Register router**: Include the router in `app/main.py` with a clear `prefix` and `tags` entry
5. **Maintain consistency**: Use Spanish field names to match existing codebase conventions
Reference Files
Inspect these files for implementation patterns:
`app/main.py` — Router registration and inclusion`app/routers/auth.py` — Simple POST login wiring to `crud.login_user``app/crud.py` — Examples of INSERT, SELECT and stored-procedure usage`app/database.py` — Engine/session setup and `.env` usage`app/schemas.py` — Pydantic request/response shapesImportant Caveats
**No ORM models**: This project uses raw SQL, not SQLAlchemy ORM models. Follow existing raw-SQL style unless intentionally migrating the pattern.**Database-side business logic**: Stored procedures are authoritative for token buy/sell flows. Avoid duplicating business rules in Python.**Spanish conventions**: Field names and messages use Spanish throughout. Maintain this consistency in new endpoints and schemas.**Stored procedures are king**: The `housegur` schema contains business-critical stored procedures that must be called rather than reimplemented in Python.Example Pattern
```python
1. Schema (app/schemas.py)
class TokenCompraRequest(BaseModel):
usuario_id: int
propiedad_id: int
cantidad: int
2. CRUD (app/crud.py)
def comprar_tokens(request: TokenCompraRequest):
session = SessionLocal()
try:
session.execute(text(
"CALL housegur.sp_comprar_tokens(:uid, :pid, :cant)"
), {"uid": request.usuario_id, "pid": request.propiedad_id, "cant": request.cantidad})
session.commit()
return {"success": True}
finally:
session.close()
3. Router (app/routers/transactions.py)
@router.post("/comprar", response_model=dict)
def comprar_tokens_endpoint(request: TokenCompraRequest):
return crud.comprar_tokens(request)
4. Registration (app/main.py)
app.include_router(transactions.router, prefix="/transactions", tags=["transactions"])
```
When You Need More Details
Request specific guidance on:
Stored procedure input/output examplesLocal database fixture recommendationsAutomated test patterns for this architectureMigration strategies from raw SQL to ORM (if desired)