# Porting Rules

## Source of truth

The Django aiservice at `~/Desktop/work/cf_org/codeflash-internal/django/aiservice/` is the reference implementation. When porting:

1. Read the Django source first
2. Copy the logic, adapt the framework glue
3. Don't "improve" the logic during the port — that introduces subtle divergence
4. Improvements come in follow-up commits after the port passes tests

## Key files to port from (by priority)

### P0 — Core pipeline
- `aiservice/llm.py` → `llm/_client.py` (dual-provider abstraction, cost tracking)
- `core/languages/python/optimizer/optimizer.py` → `optimize/_pipeline.py`
- `core/languages/python/optimizer/context_utils/optimizer_context.py` → `optimize/_context.py`
- `core/languages/python/optimizer/postprocess.py` → `languages/python/_postprocess.py`
- `core/languages/python/cst_utils.py` → `languages/python/_cst_utils.py`
- `core/languages/python/optimizer/diff_patches_utils/` → `diff/`
- `core/languages/python/code_repair/` → `repair/`

### P1 — Supporting endpoints
- `core/languages/python/optimizer/refinement.py` → `refinement/`
- `core/languages/python/adaptive_optimizer/` → `adaptive/`
- `core/shared/ranker/ranker.py` → `ranking/`
- `core/shared/testgen_router.py` → `testgen/`
- `core/languages/python/explanations/` → `explain/`
- `core/languages/python/optimization_review/` → `review/`

### P2 — Secondary languages
- `core/languages/java/` → `languages/java/`
- `core/languages/js_ts/` → `languages/js_ts/`

## What NOT to port

- Django ORM models → replaced by asyncpg queries
- Django middleware classes → replaced by FastAPI dependencies
- `manage.py`, `wsgi.py`, `asgi.py` → replaced by FastAPI app factory
- `settings.py` → replaced by pydantic-settings `_config.py`
- Django `urls.py` / NinjaAPI router mounting → replaced by FastAPI router includes

## Prompt templates

Copy `.md` prompt files verbatim. They are not Django-specific. Place them in `languages/<lang>/prompts/` mirroring the Django structure.
