# Repository Guidelines

## Project Structure & Module Organization

This repository currently contains the technical architecture report and its bundled Mermaid asset:

- `tech-architecture/tech-architecture.html`: self-contained architecture and technology-selection report.
- `tech-architecture/_shared/js/mermaid.min.js`: local Mermaid renderer; keep vendored assets beside the HTML report.
- Root-level images and screenshots are reference material, not application source.

The report defines the planned Python implementation. When implementation begins, use a `src` layout under `src/lmpm/`, with subpackages such as `domain/`, `data/`, `doe/`, and later `ml/` and `api/`. CLI entry points belong in `src/lmpm/scripts/`, tests in `tests/`, and generated SQLite or CSV artifacts in `data/`. Do not commit local database files or experiment data.

## Build, Test, and Development Commands

For the current static report:

- `python -m http.server 47319 --directory tech-architecture`: serve the report locally; open `http://localhost:47319/tech-architecture.html`.

For the planned Python package:

- `uv sync`: install dependencies declared in `pyproject.toml`.
- `uv run pytest`: run the test suite.
- `uv run ruff check .`: lint Python sources.
- `uv run ruff format .`: apply the repository formatter.

## Coding Style & Naming Conventions

Use Python 3.10+ and 4-space indentation. Keep modules, classes, functions, and tests in `snake_case`/`PascalCase` as standard Python requires. Prefer descriptive domain names: `MaterialProperty`, `ExperimentRecord`, and `ParameterSpace` mirror the documented domain model. Keep one primary concern per module, place data models under `domain/`, and isolate hardware, persistence, and ML concerns behind small, testable APIs. Run Ruff before committing.

## Testing Guidelines

Use `pytest`. Cover domain validation, SQLite/CSV data import-export behavior, DOE generation, and model or API behavior as those layers are added. Name tests after the unit under test, for example `tests/test_material.py` or `tests/test_store.py`. Prefer small, deterministic tests and use temporary files or in-memory SQLite for persistence tests.

## Deployment Environment

Production deployment and model training target the Ubuntu server. Prefer Docker as the deployment and training runtime so the scientific Python stack, CUDA-free CPU dependencies, and filesystem paths remain reproducible across machines. Use `uv.lock` as the dependency source of truth and avoid compiling native binaries unless a required dependency has no compatible wheel. Direct Ubuntu deployment with `uv sync` is acceptable only when a lightweight host environment is explicitly required.

## Commit & Pull Request Guidelines

No Git history exists yet, so use concise, imperative Conventional Commits such as `feat: add material schema` or `docs: update architecture report`. Pull requests should describe the change and motivation, link related issues or project tasks, include verification commands and results, and add screenshots for visible report changes.

## Agent-Specific Instructions

Treat the architecture report as the source of truth for planned structure and dependencies. Keep documentation, diagrams, and implementation decisions aligned; call out intentional deviations in commit messages or pull requests.