From 3da7252b772487d721e026279a6c0022c2ea2308 Mon Sep 17 00:00:00 2001
From: Kalle Saas <kalle@easypep.de>
Date: Fri, 6 Feb 2026 07:36:52 +0100
Subject: [PATCH] Add CLAUDE.md with repo usage notes

Add CLAUDE.md providing guidance for Claude Code when working with this repository. The file summarizes the project structure (API and Frontend services), startup notes (both run in Docker; start the API first), quick CLI commands for running tests/lint/typecheck and regenerating the API client, and key implementation patterns (CommonController, BaseDecorator hooks, Orval-generated client, TanStack Router layout).
---
 CLAUDE.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..4f46078
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,43 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+MiniStaffomatic is a staff scheduling application with two independent services:
+
+- **API** (`/api`): Ruby on Rails 7, MySQL 8.0, Redis — see [api/README.md](api/README.md)
+- **Frontend** (`/frontend`): React 19, TypeScript, Vite, TanStack — see [frontend/README.md](frontend/README.md)
+
+Both services run in Docker containers. Start the API first as the frontend depends on it.
+
+For getting started, demo credentials, and data model details, see the main [README.md](README.md).
+
+## Quick Reference
+
+### API
+
+```bash
+bin/dev exec api bundle exec rspec spec/requests/api/v1/shifts_spec.rb  # Single test
+bin/dev exec api bundle exec rspec                                       # All tests
+bin/dev exec api bundle exec rubocop                                     # Lint
+```
+
+### Frontend
+
+```bash
+bin/dev exec frontend pnpm test              # Tests
+bin/dev exec frontend pnpm typecheck         # TypeScript
+bin/dev exec frontend pnpm lint              # ESLint
+bin/generate-api                             # Regenerate API client after API changes
+```
+
+## Key Patterns
+
+**CommonController** (`api/app/controllers/api/v1/common_controller.rb`) — Convention-based CRUD. Resource controllers inherit and define only `common_params` and collection scope.
+
+**BaseDecorator** (`api/app/decorators/base_decorator.rb`) — Wraps create/update/destroy with hooks (`before_assign_attributes`, `after_save`, `update_state` for AASM transitions).
+
+**Orval API Client** (`frontend/src/generated/`) — Generated from OpenAPI spec. Run `bin/generate-api` in frontend after API changes.
+
+**TanStack Router** (`frontend/src/routes/`) — File-based routing. Protected routes under `_authenticated/` layout.