# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

MinIO WebUI is a secure web interface for managing MinIO object storage. It's a monorepo with separate frontend (React/TypeScript) and backend (Express/Node.js) applications that communicate via REST API.

## Development Commands

### Backend (from `/backend`)
```bash
npm run dev          # Development with nodemon (hot reload)
npm run dev:node     # Development with Node.js --watch
npm start            # Production
npm test             # Jest tests with coverage
npm run lint         # ESLint check
npm run lint:fix     # ESLint auto-fix
```

### Frontend (from `/frontend`)
```bash
npm start            # Development server (port 7511)
npm run build        # Production build
npm test             # React Testing Library tests
npm run lint         # ESLint check
npm run lint:fix     # ESLint auto-fix
```

### Full Stack Development
```bash
./dev.sh                     # Start both backend and frontend
./scripts/quickstart.sh      # Interactive setup wizard
./scripts/setup.sh           # Initial project setup
```

### Docker
```bash
docker-compose up -d                     # Start all services
docker-compose --profile proxy up -d     # Start with Nginx SSL proxy
docker-compose logs -f                   # View logs
```

## Architecture

```
Browser (React) → Nginx (optional SSL) → Express API → MinIO CLI (mc) → MinIO Server
```

### Backend (`/backend`)
- **Entry**: `src/app.js`
- **Services**: `src/services/` - Business logic (minio.service.js, auth.service.js, report.service.js)
- **Routes**: `src/api/` - REST endpoints (auth/, buckets/, users/, policies/, reports/)
- **Middleware**: `src/middleware/` - Auth, IP filtering, error handling
- **Config**: `src/config/index.js` - Environment configuration

### Frontend (`/frontend`)
- **Entry**: `src/index.tsx` → `src/App.tsx`
- **Components**: `src/components/` - Feature-based organization (Auth/, Buckets/, Users/, etc.)
- **State**: `src/store/authStore.ts` - Zustand for auth state with persistence
- **API**: `src/services/api.ts` - Axios instance
- **i18n**: `src/i18n.ts` - English and German translations in `src/locales/`

### Key Patterns
- Backend uses MinIO CLI (`mc`) commands via child processes, not MinIO SDK
- JWT tokens stored in httpOnly cookies with IP binding
- Frontend proxies to backend at `http://localhost:7510` (see `frontend/package.json` proxy setting)
- Policy files are created temporarily in `backend/temp/` (falls back to OS temp on permission issues)

## Ports

- Backend API: 7510
- Frontend Dev: 7511
- Frontend Prod: 3000
- MinIO: 9000 (default)

## Environment Configuration

The `.env` file (created by `./scripts/setup.sh`) requires:
- `ADMIN_PASSWORD_HASH` - bcrypt hash (12 rounds)
- `JWT_SECRET` - Session signing key
- `DEFAULT_MINIO_ALIAS` - Typically `kopiaminio`
- `MINIO_ENDPOINT`, `MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY`

Generate password hash: `cd backend && npm run hash-password`

## Security Implementation

- Rate limiting: 100 req/15min general, 5 req/15min for auth
- IP whitelist via `ALLOWED_IPS` (CIDR notation supported)
- All operations logged to `logs/` with daily rotation
- CSRF protection with secure cookies
- Helmet.js for HTTP security headers

## Testing

Backend tests use Jest + Supertest. Frontend tests use React Testing Library.

Run a single backend test:
```bash
cd backend && npm test -- --testPathPattern="auth"
```

Run frontend tests in watch mode:
```bash
cd frontend && npm test
```