> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cirron.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Common files

> Shared files generated for every project template.

# Common Files

Every Cirron CLI project includes a set of common files that provide essential infrastructure, configuration, and project management capabilities. These files are generated regardless of your chosen template or model type. Framework-specific pages ([PyTorch](/cli/templates/pytorch), [TensorFlow](/cli/templates/tensorflow), [scikit-learn](/cli/templates/sklearn)) link here for the shared scaffolding.

## Project Structure

```
my-project/
├── src/                    # Source code (framework-specific)
├── tests/                  # Test files
├── models/                 # Saved models
├── checkpoints/            # Training checkpoints
├── logs/                   # Training and application logs
├── data/                   # Data directory
│   └── sample/             # Sample data (optional)
├── notebooks/              # Jupyter notebooks (optional)
├── requirements.txt
├── Dockerfile
├── .gitignore
├── README.md
├── .env.example
└── cirron.yaml
```

## Dockerfile

The generated `Dockerfile` is a minimal Python image. The Cirron-relevant lines:

```dockerfile theme={null}
FROM python:3.9-slim
WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY src/ ./src/
COPY models/ ./models/

EXPOSE 8000
CMD ["python", "src/inference.py"]
```

The `CMD` defaults to running `src/inference.py` so the image is immediately serve-ready. `cirron build` reads this file by default; override with `dockerfile_path` in `cirron.yaml`.

## .gitignore

The generated `.gitignore` covers standard Python artifacts plus ML-specific patterns:

```gitignore theme={null}
# ML artifacts
*.pkl
*.joblib
*.h5
*.pth
*.onnx
models/*.bin
checkpoints/
logs/
data/raw/
data/processed/
.wandb/
mlruns/

# Notebooks (stripped before commit)
.ipynb_checkpoints/

# Environment
.env
.env.local
```

Add framework- or project-specific exclusions as needed. Python, venv, IDE, and OS patterns are included by default.

## cirron.yaml

The project manifest. See the framework pages for example contents. Resolution order at runtime: global config (`~/.cirron/config.json`) → project `cirron.yaml` → command flags.

## README.md

A generated README with sections for quick start, project structure, and the `cirron` commands that operate on the project (`test`, `build`, `deploy`, `status`, `logs`). Customize freely after `init`.

## .env.example

Environment variable template. Copy to `.env` for local development:

```bash theme={null}
MODEL_PATH=models/best_model.pth
BATCH_SIZE=32
DEVICE=cuda
DATA_PATH=data/
API_HOST=0.0.0.0
API_PORT=8000
LOG_LEVEL=INFO
```

Manage env vars on the platform with `cirron env list`, `cirron env set`, and `cirron env delete`.

## Test files

Three unittest skeletons are generated under `tests/`:

* **`test_model.py`**: verifies `create_model()` returns a usable model and exposes expected methods (`forward` for PyTorch, `predict` for sklearn).
* **`test_inference.py`**: verifies `ModelInference` instantiates and exposes `preprocess` / `predict`.
* **`test_data.py`**: placeholder for data validation tests.

Run with `cirron test` or `python -m unittest discover tests`.

## Optional components

### Sample data: `--include-sample-data`

Generates `data/sample/sample_data.csv` (classification or regression depending on selected model type) so `cirron test` and the generated training scripts work out of the box.

### Jupyter notebook: `--include-notebook`

Generates `notebooks/explore.ipynb` with cells pre-wired to import from `src/`.

## Integration with the CLI

```bash theme={null}
cirron test       # Runs tests/
cirron build      # Reads Dockerfile + requirements.txt
cirron deploy     # Uses cirron.yaml + .env
cirron status     # Reads project structure
cirron logs       # Streams from logs/
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Template generation" href="/cli/templates/template-generation">
    How templates are authored and extended
  </Card>

  <Card title="PyTorch" href="/cli/templates/pytorch">
    Deep learning with PyTorch
  </Card>

  <Card title="TensorFlow" href="/cli/templates/tensorflow">
    Deep learning with TensorFlow
  </Card>

  <Card title="scikit-learn" href="/cli/templates/sklearn">
    Traditional ML algorithms
  </Card>
</CardGroup>