Aegis/tasks/lessons.md

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.