Skip to content

Add CLAUDE.md for Claude Code guidance #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
fluxsaas wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add CLAUDE.md for Claude Code guidance #2

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Copy link
Collaborator

@martingregoire martingregoire Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's also include a step in the API section above to generate the API schema:

bin/dev exec api bundle exec rails rswag

Copy link
Collaborator

@martingregoire martingregoire Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, also we could remove this script bin/generate-api (it is only one command), and run the command directly. WDYT? We would need to change the frontend/README.md as well.

Suggested change
bin/generate-api # Regenerate API client after API changes
bin/dev exec frontend pnpm 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.
Copy link
Collaborator

@martingregoire martingregoire Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's include both steps here then, first generate the schema in the API, then generate the hooks in the frontend.


**TanStack Router** (`frontend/src/routes/`) — File-based routing. Protected routes under `_authenticated/` layout.