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

python main.py

Production

gunicorn -w 4 -k uvicorn.workers.UvicornWorker app:app --bind 0.0.0.0:6001

Frontend (Tailwind CSS)

npm install
npx tailwindcss -i ./public/styles/input.css -o ./public/styles/output.css --watch

Requirements

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).

CLAUDE.md 3.0 KB History Raw