# ara

The Domna retrofit modelling backend. Replaces the legacy `backend/engine/engine.py` monolith with a service-oriented pipeline that survives the 30 May 2026 gov EPC API cut-over and that other team members can read, fix, and extend.

Design document: [`../../ara_backend_design.md`](../../ara_backend_design.md).
Domain glossary: [`../../CONTEXT.md`](../../CONTEXT.md).

## Layout

```
src/ara/
├── services/        # the 9 domain services from PRD §9.2:
│                    #   EpcRemappingService, EpcPredictionService,
│                    #   FeatureBuilder, EpcEnergyDerivationService,
│                    #   RebaseliningService, RecommendationService,
│                    #   ImpactPredictionService, OptimiserService,
│                    #   ValuationService, ResultsPersister
├── orchestrators/   # IngestionPipeline, ModellingPipeline, RefreshOrchestrator
└── lambdas/         # one handler.py per Lambda + the event-shape contracts
```

## Pipeline

See [PRD §9.4](../../ara_backend_design.md) for the per-batch step order. Briefly: per-property setup (steps 1–6) runs once per Property; the per-scenario × per-phase loop (steps 7–10) re-derives candidates and impact predictions against the rolling Effective EPC state; results are persisted under one Unit of Work per (Plan, Scenario).

## Testing

- `tests/unit/` — service tests against fakes from `tests/fakes/`. No DB, no network, no ML lambda.
- `tests/integration/` — real Postgres (testcontainers / localstack), fake fetchers + fake ML lambdas.
- ML transform contract tests live with `domain.ml.transform` in `packages/domain/`.