tilbudgivern/CLAUDE.md

CLAUDE.md

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

Project Overview

Tilbudgivern is an AI-powered quote calculator for the carpentry trade (tømrerfaget). It generates detailed professional quotes based on project descriptions, using OpenAI GPT-4 for AI-powered quote generation.

Tech Stack:

• Frontend: React 18 with Material-UI, served as static build
• Backend: Node.js/Express unified server (~400K lines in backend/unified-server.js)
• Database: MariaDB/MySQL (running on host, not containerized)
• AI: OpenAI GPT-4 API (default budget: $9/month)
• Process Manager: PM2 (process name: tilbudgivern-unified)

Common Commands

Development

npm run dev                          # Start development server with hot reload
npm run build                        # Build frontend for production
pm2 restart tilbudgivern-unified     # Restart PM2 after changes
pm2 logs tilbudgivern-unified        # View logs

Testing

npm run test:pw                      # Playwright UI tests against production
npm run test:pw:local                # Playwright tests against local server
npm run test:pw:ui                   # Playwright interactive UI mode
npm run test:pw:headed               # Playwright with visible browser
npm run test:selenium                # Selenium UI tests
cd backend && npm test               # Backend unit tests (Jest)

Single Test Execution

cd tests && PLAYWRIGHT_BASE_URL=https://tilbudsgiveren.alw.dk playwright test <test-file>.spec.js
cd tests && PLAYWRIGHT_BASE_URL=https://tilbudsgiveren.alw.dk playwright test <test-file>.spec.js --headed

Architecture

Unified Server Pattern

The application uses a unified server (backend/unified-server.js) that:

• Serves the React frontend build from frontend/build/
• Provides all API endpoints on port 4032 (configured in .env)
• Handles WebSocket connections via Socket.IO
• Includes structured logging with correlation IDs

Key Backend Services (backend/src/services/)

• openaiService.js - AI quote generation via GPT-4, budget tracking
• databaseService.js - MariaDB connection pool and queries
• smartPackageManagementService.js - Smart package CRUD (15 carpenter packages)
• ordrestyringSyncService.js - GraphQL integration with Ordrestyring API
• pdfGenerationService.js - Quote PDF generation via Puppeteer
• roofGeometryService.js - Roof area calculations for 7 roof types
• starkImportService.js - Stark material catalog import
• bygmaPrisbogImportService.js - Bygma price book import

Key Backend Routes (backend/src/routes/)

• smartPackagesRoutes.js - Smart package management API
• customerProjects.js - Customer and project CRUD
• quotes.js - Quote generation and management
• pricing.js - Price database endpoints
• starkImport.js - Stark CSV import endpoint

Key Frontend Components (frontend/src/components/)

• InlineSmartPackage.js - Smart package wizard with step-by-step flow
• EnhancedGeometry.js - Roof geometry input with SVG visualizations for 7 roof types
• MaterialsManager.js - Material selection with cached API searches
• PlanningDashboard.js - Project planning calendar
• FinalReview.js - Quote review and Ordrestyring offer creation
• ProjectCreation.js - Project form with autosave, validation, tooltips

Smart Packages System

15 pre-configured carpenter packages for roofing work:

• Auto-calculation based on geometry (tagareal, rygningslængde, facadelængde)
• Includes materials with prices and labor hours
• Categories: Tagdækning, Tagrende/Nedløb, Tagvinduer, Brædder, Specialarbejde

Roof Types (7 supported)

1. Sadeltag (pitched roof) - default
2. Valmtag (hip roof)
3. Københavnertag (Copenhagen roof)
4. Fladtag (flat roof)
5. Pulttag (shed roof)
6. Tag med Kviste (roof with dormers)
7. Mansardtag (mansard roof)

External Integrations

Ordrestyring API

• GraphQL endpoint: https://beta7-api.ordrestyring.dk/graphql
• Used for: customers, cases, offers, calendar, hours tracking
• Token: ORDRESTYRING_API_TOKEN in .env
• API test scripts: apitest/examples/

Material Suppliers

• Bygma: Price book import, installation manuals
• Stark: CSV catalog import via /api/stark/upload

Database

• MariaDB on localhost:3306
• Database: tilbudgivern
• Key tables: smart_packages, package_tasks, package_materials, materials, customers, projects
• Schema files: database/schema_system_logs.sql
• Migrations: database/migrations/, backend/migrations/

Environment Configuration

• Main config: backend/.env
• Required:
  • OPENAI_API_KEY - for AI features
  • DB_HOST, DB_USER, DB_PASSWORD, DB_NAME - database
• Optional:
  • ORDRESTYRING_API_TOKEN - order management integration
  • OPENAI_ADMIN_KEY - for cost tracking API

Logging System

• Structured JSON logs with correlation IDs
• Database persistence in system_logs table
• Error codes: DB_001 (connection), DB_002 (query), VAL_001 (validation), API_001 (Ordrestyring), etc.
• Admin endpoints: /api/admin/logs

Deployment

pm2 restart tilbudgivern-unified  # Restart after code changes
pm2 logs tilbudgivern-unified     # View live logs
pm2 status                        # Check process status

Daily database backups configured via cron at 02:00, retention: 7 days.

Danish Terminology

• Tilbud = Quote/Offer
• Tømrer = Carpenter
• Materiale = Material
• Pakke = Package
• Pris = Price
• Tag = Roof
• Spær = Rafters
• Tagrende = Rain gutter
• Nedløb = Downspout
• Vindsked = Barge board
• Sternbræt = Fascia board