# Architecture

## Service Flow

```
VSC-Extension / CLI → cf-api (Express, :3001) → aiservice (Django-Ninja, :8000)
cf-webapp (:3000) reads from the same PostgreSQL DB via Prisma
```

## Monorepo Layout

```
codeflash-internal/
├── django/aiservice/          # Python backend (Django-Ninja, ASGI)
│   ├── aiservice/             # Django project: settings, urls.py, llm.py
│   ├── authapp/               # Authentication (HttpBearer + django_auth)
│   ├── core/                  # Business logic
│   │   ├── shared/            # Cross-language routers (optimizer_router, testgen_router, ranker)
│   │   ├── languages/         # Per-language handlers (python/, js_ts/, java/)
│   │   ├── protocols/         # Handler protocols (LanguageHandler, OptimizerProtocol, etc.)
│   │   ├── registry.py        # Language handler registration
│   │   ├── dispatcher.py      # Handler lookup by language + feature
│   │   └── log_features/      # Domain models (OptimizationFeatures, OptimizationEvents)
│   └── tests/                 # pytest tests by feature: optimizer/, testgen/, integration/
├── js/
│   ├── cf-api/                # Express middleware layer (:3001)
│   ├── cf-webapp/             # Next.js dashboard (:3000)
│   ├── common/                # Shared Prisma schema + utilities (CommonJS)
│   └── VSC-Extension/         # VS Code extension
├── cli/                       # CLI tools
└── deployment/                # Infrastructure configs
```

## Glossary

- **Optimization Candidate** — LLM-generated code that may be faster
- **Read-Write Context** — code the LLM can modify
- **Read-Only Context** — code provided as info only (not modified)
- **Tracer** — collects input args for a Python function at runtime
- **Replay Test** — reruns traced inputs to verify behavior
- **Comparator** — compares two Python objects for equality

## Key Entry Points

| Task | Start here |
|------|------------|
| Optimization dispatch | `core/shared/optimizer_router.py` |
| Testgen dispatch | `core/shared/testgen_router.py` |
| Python optimization | `core/languages/python/optimizer/optimizer.py` |
| LLM provider abstraction | `aiservice/llm.py` |
| Endpoint registration | `aiservice/urls.py` |
| Domain models | `core/log_features/models.py` |
| Request/response schemas | `core/shared/optimizer_models.py` |
| Handler registration | `core/registry.py` + `core/dispatcher.py` |
| cf-api route registration | `js/cf-api/routes/index.ts` |