# CLAUDE.md

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

## Project Overview

**Biergarten Klein** - FastAPI backend for a craft beer bar ordering system. Serves a web frontend and provides an AI assistant ("Camilo Klein") powered by OpenAI GPT-4o-mini.

## Commands

### Development
```bash
python main.py
```

### Production
```bash
gunicorn -w 4 -k uvicorn.workers.UvicornWorker app:app --bind 0.0.0.0:6001
```

### Frontend (Tailwind CSS)
```bash
npm install
npx tailwindcss -i ./public/styles/input.css -o ./public/styles/output.css --watch
```

### Requirements
```bash
pip install -r requirements.txt
```

## Architecture

### Entry Point Flow
`main.py` → `app.py:create_app()` → `app.py:setup_routes()` → mounts routers from `routes/`

### Key Directories
- **config/** - Settings, messages, email templates
- **routes/** - FastAPI routers (chat, orders, products, users, sales, store)
- **services/** - Business logic (openai_service/, data_service.py, print_service.py, fudo_service.py)
- **models/** - Pydantic schemas for request/response validation
- **auth/** - Token generation and validation (security.py)
- **middleware/** - NoCacheMiddleware, InTimeMiddleware (currently disabled)
- **data/** - JSON data files (products.json, llm_data.json)
- **public/** - Frontend (Vanilla JS, Tailwind CSS)

### Dependencies
- **Redis** (localhost:6379) - Session tokens, anti-abuse tokens, connected users list
- **PostgreSQL** - Configured via POSTGRES_* env vars (db: pedidos_express_pruebas by default)
- **OpenAI API** - GPT-4o-mini for AI assistant
- **Fudo POS** - External ordering system integration

### Route Protection
Most API routes require `Depends(get_current_user)` from `auth/security.py`. Chat endpoints use a separate anti-abuse token system (`/api/chat/init-chat` → `/api/chat/completions`).

### Configuration
All settings loaded from `.env` via `config/settings.py` using Pydantic. `validate_config()` checks required vars on startup.

## Commit Convention
Use Spanish conventional commits: `tipo(ámbito): descripción` (see `.github/commit-instructions.md`)

## Database
PostgreSQL connection config in `config/settings.py:POSTGRESQL_DB_CONFIG`. Redis DB 0 for production, DB 1 for development (clears `connected_users` and `chat_history` on startup).

## graphify

This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.

Rules:
- ALWAYS read graphify-out/GRAPH_REPORT.md before reading any source files, running grep/glob searches, or answering codebase questions. The graph is your primary map of the codebase.
- IF graphify-out/wiki/index.md EXISTS, navigate it instead of reading raw files
- For cross-module "how does X relate to Y" questions, prefer `graphify query "<question>"`, `graphify path "<A>" "<B>"`, or `graphify explain "<concept>"` over grep — these traverse the graph's EXTRACTED + INFERRED edges instead of scanning files
- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).
