# CLAUDE.md

> Project context for Claude Code sessions. See also: [CONTRIBUTING.md](CONTRIBUTING.md) | [dev/](dev/)

## Project

Prism (`prisme` on PyPI) is a code generation framework that produces full-stack CRUD applications from Pydantic model specifications. Python 3.13+, MIT licensed.

**Always use `uv run`** to execute Python, pytest, and prisme commands (e.g., `uv run python`, `uv run pytest`, `uv run prisme`).

## Quick Reference

```bash
# Setup
uv sync --all-extras
uv run pre-commit install --hook-type pre-commit --hook-type commit-msg --hook-type pre-push

# Development loop
uv run pytest -x                        # Tests (stop on first failure)
uv run ruff check . --fix               # Lint + auto-fix
uv run ruff format .                    # Format
uv run mypy src                         # Type check

# Other test modes
uv run pytest tests/path/to/test.py     # Specific file
uv run pytest -m slow                   # Slow tests (excluded by default)
uv run pytest -m e2e                    # End-to-end tests
uv run pytest -m docker                 # Docker tests (requires Docker)
uv run pytest --cov --cov-report=html   # Coverage report

# Documentation
uv run mkdocs serve                     # Local docs server with hot reload
uv run mkdocs build --strict            # Build docs (strict mode)
```

## Architecture Overview

```
src/prisme/
├── cli.py                  # CLI entry point (Click, 67+ commands, 16 groups)
├── spec/                   # Pydantic specification models
│   ├── stack.py            # StackSpec, DatabaseConfig, GeneratorConfig
│   ├── model.py            # ModelSpec, RelationshipSpec, TemporalConfig
│   ├── fields.py           # FieldSpec, FieldType (13 types), FilterOperator
│   ├── exposure.py         # RESTExposure, GraphQLExposure, MCPExposure, FrontendExposure
│   ├── auth.py             # AuthConfig, Role, APIKeyConfig, AuthentikConfig
│   ├── design.py           # DesignSystemConfig, ThemePreset, IconSet
│   ├── infrastructure.py   # TraefikConfig
│   ├── overrides.py        # DeliveryOverrides, FrontendOverrides, MCPOverrides
│   ├── project.py          # ProjectConfig
│   └── validators.py       # Cross-model validation
├── generators/             # 31 generator classes
│   ├── base.py             # GeneratedFile, GeneratorContext, GeneratorResult, FileStrategy
│   ├── backend/            # 11 generators (models, schemas, services, rest, graphql, mcp, auth, api_key_auth, admin, alembic)
│   ├── frontend/           # 15 generators (types, components, hooks, pages, router, auth, graphql_ops, headless, widgets, design, admin, landing, dashboard, error_pages, profile, search)
│   ├── infrastructure/     # 1 generator (authentik compose)
│   └── testing/            # 2 generators (backend tests, frontend tests)
├── templates/jinja2/       # 282 Jinja2 templates mirroring generator structure
├── docker/                 # Docker/Traefik proxy management
├── deploy/                 # Hetzner/Terraform deployment
├── devcontainer/           # Dev container lifecycle
├── ci/                     # CI/CD workflow generation
├── config/                 # Prism configuration handling
├── migration/              # Database migration utilities
├── tracking/               # Manifest and override tracking (ManifestManager)
├── utils/                  # File handling, spec loading, template rendering
├── planning/               # Planning utilities
├── project/                # Project scaffolding
└── dx/                     # Developer experience utilities
```

### Generator Pipeline

```
StackSpec → validate → GeneratorContext → Generator.generate() → GeneratorResult → write files
```

Each generator inherits from `generators/base.py`, implements `generate()` → `GeneratorResult`, uses `TemplateRenderer` for Jinja2 processing, and creates `GeneratedFile` objects with a `FileStrategy`:

| Strategy | Behavior | Example files |
|---|---|---|
| `ALWAYS_OVERWRITE` | Regenerated every time | types, schemas, `_generated/` |
| `GENERATE_ONCE` | Created once, never overwritten | custom pages, user service files |
| `GENERATE_BASE` | Base regenerated, user extension preserved | services, components |
| `MERGE` | Smart merge with conflict markers | schema/router assembly |

### Protected Regions

`PRISM:PROTECTED:START - <name>` / `PRISM:PROTECTED:END` markers allow users to embed custom code inside `ALWAYS_OVERWRITE` files. The merge logic lives in `src/prisme/utils/file_handler.py` (`parse_protected_regions()`, `merge_protected_regions()`, `write_file_with_strategy()`).

## Test Structure

```
tests/
├── conftest.py             # sample_field_spec, sample_model_spec, sample_stack_spec fixtures
├── spec/                   # Specification model tests
├── generators/
│   ├── backend/            # Backend generator tests
│   ├── frontend/           # Frontend generator tests
│   └── infrastructure/     # Infrastructure tests
├── cli/                    # CLI command tests
├── e2e/                    # End-to-end tests
├── docker/                 # Docker integration tests
├── deploy/                 # Deployment tests
├── devcontainer/           # Dev container tests
├── dx/                     # Developer experience tests
├── planning/               # Planning module tests
├── ci/                     # CI/CD tests
├── config/                 # Configuration tests
├── migration/              # Migration tests
└── tracking/               # Manifest & override tracking tests
```

Test markers: `slow`, `e2e`, `docker` — all excluded from default runs. Timeout: 120s per test. Async mode: auto.

## Code Style

- **Ruff**: line-length 100, target py313, rules `E/W/F/I/UP/B/SIM/TCH/RUF`
- **Mypy**: pydantic plugin, `ignore_missing_imports = true`, not strict
- **Imports**: isort via ruff with `prisme` as first-party
- **Commits**: Conventional Commits (`type(scope): description`). `feat` → minor bump, `fix`/`perf` → patch bump

## Internal Dev Docs

- `dev/roadmap.md` — priorities and feature status
- `dev/issues/` — 3 active issue analysis documents (resolved ones archived)
- `dev/plans/` — 10 active feature implementation plans (3 archived)
- `dev/suggestions/` — codebase audit findings (2026-02-08)
- `dev/dev-docs.md` — document conventions and templates

## Skills

- **[prism-cli](.claude/skills/prism-cli/SKILL.md)** — Prism CLI commands, spec model reference, and generated project structure
- **[generate-prism-spec](.claude/skills/generate-prism-spec/SKILL.md)** — Generate a StackSpec from a natural-language description (`/generate-prism-spec`)
- **[develop-prism](.claude/skills/develop-prism/SKILL.md)** — Develop features and fix bugs in the Prism framework itself
- **[modify-prism-project](.claude/skills/modify-prism-project/SKILL.md)** — Rules for safely modifying existing Prism-generated projects
- **[issue-triage](.claude/skills/issue-triage/SKILL.md)** — Triage new issues by labeling, prioritizing, and categorizing (`/issue-triage`)
- **[backlog-groom](.claude/skills/backlog-groom/SKILL.md)** — Write acceptance criteria and clarify issue descriptions (`/backlog-groom`)
- **[sprint-plan](.claude/skills/sprint-plan/SKILL.md)** — Plan sprint work and move issues to Up Next (`/sprint-plan`)
- **[product-review](.claude/skills/product-review/SKILL.md)** — Review PRs from a product perspective (`/product-review`)
- **[product-status](.claude/skills/product-status/SKILL.md)** — Report on project health and milestone progress (`/product-status`)
- **[launch-dev](.claude/skills/launch-dev/SKILL.md)** — Kick off development work via GitHub Actions (`/launch-dev`)
