# Aegis — Lessons Learned

## Architecture

- Domain entities must have ZERO framework imports. If you need SQLAlchemy or FastAPI in an entity, the design is wrong.
- Services should never call `db.commit()`. Use UnitOfWork at the router/use-case level.
- Domain exceptions propagate up and the error_handler middleware maps them to HTTP responses automatically.
- The `from_orm()` / `apply_to()` pattern bridges ORM models and domain entities cleanly.

## Testing

- Use the `db` fixture for repository/integration tests, `client` fixture for API tests.
- SQLite conftest patches PostgreSQL types (UUID, JSONB) — always verify on real PG in CI.
- Pure domain tests need no fixtures at all — just construct entities directly.

## Patterns to Avoid

- Never raise `HTTPException` from services — raise domain exceptions instead.
- Never put business logic in routers — delegate to entities or services.
- Never create DB sessions manually (`SessionLocal()`) outside of background jobs.
- Never swallow exceptions with bare `except: pass` — at minimum log a warning.