# CLAUDE.md — HLA-Compass Module

## What This Is

An HLA-Compass module — a containerized analysis unit that runs on the
HLA-Compass bioinformatics platform for immuno-peptidomics research.

## Guiding Principles

- **P0: UI/UX/DX** — Developer and user experience first.
- **P1: Security** — Scoped, signed, auditable.
- **P2: Performance** — Efficient by default.
- **P3: Elegance/Maintainability** — Clean, readable code.

**GUIDANCE:** No workarounds, no placeholders, no speculative abstractions.

## Key Commands

```bash
hla-compass dev                    # Run locally with examples/sample_input.json
hla-compass validate               # 7-layer manifest + code validation
hla-compass test                   # Run module test suite
hla-compass publish --env dev --scope org  # Publish to dev
```

## Architecture

```
Module.__init__  →  run(input, context)  →  validate_inputs  →  execute  →  success/error
```

- Extend `hla_compass.Module`, implement `execute()`.
- Define a Pydantic `Input` model for auto-validation.
- Return `self.success(results=..., summary=...)`.
- Raise `self.error(message, details={})` on failure.

## Available Helpers Inside `execute()`

| Helper | Access | Purpose |
|--------|--------|---------|
| `self.api` | `APIClient` | REST API: peptides, proteins, samples, modules, runs |
| `self.data` | `DataClient` | `self.data.sql.query()` for SQL, `self.data.storage` for S3 |
| `self.storage` | `Storage` | Save/load run artifacts (JSON, CSV, Excel, figures) |
| `self.db` | `ScientificQuery` | Direct DB functions (`search_peptides_by_sequence`, etc.) |
| `self.context` | `RuntimeContext` | run_id, module_id, organization_id, environment, etc. |

## Import Convention

```python
from hla_compass import Module
from hla_compass.module import ModuleError, ValidationError
from hla_compass.client import APIClient
```

## Testing

```python
module = MyModule(manifest_path="manifest.json")
result = module.run({"sequence": "SIINFEKL"}, mock_context)
assert result["status"] == "success"
```

## Complete Reference

See **SKILL.md** in this directory for the full API reference, all method
signatures, data access patterns, manifest schema, and code recipes.
