tilbudgivern/.github/copilot-instructions.md

GitHub Copilot Instructions for Tilbudgivern

Project Overview

Tilbudgivern is an AI-powered quote calculator for the Danish carpentry trade (tømrerfaget). It generates detailed professional quotes for roofing and construction work using OpenAI GPT-4.

Primary Users: Danish carpenters creating quotes for roofing projects

Tech Stack

• Frontend: React 18 with Material-UI, served as static build from frontend/build/
• Backend: Node.js/Express unified server (backend/unified-server.js)
• Database: MariaDB/MySQL on localhost:3306, database name tilbudgivern
• AI: OpenAI GPT-4 API (budget: $9/month)
• Process Manager: PM2 (process: tilbudgivern-unified)
• Testing: Playwright (primary), Selenium (backup), Jest (unit tests)

Architecture

Unified Server Pattern

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

• Serves React frontend from frontend/build/
• Provides all API endpoints on port 4032
• Handles WebSocket via Socket.IO
• Includes structured logging with correlation IDs

Key Directories

backend/src/services/     # Business logic (openaiService, databaseService, etc.)
backend/src/routes/       # API endpoints (smartPackagesRoutes, customerProjects, etc.)
frontend/src/components/  # React components (InlineSmartPackage, EnhancedGeometry, etc.)
tests/                    # Playwright and Selenium tests
docs/                     # Project documentation

Smart Packages System

15 pre-configured carpenter packages for roofing work:

• Auto-calculation based on geometry (tagareal, rygningslængde, facadelængde)
• Categories: Tagdækning, Tagrende/Nedløb, Tagvinduer, Brædder, Specialarbejde
• Database tables: smart_packages, package_tasks, package_materials

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

Material Suppliers

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

Code Style Guidelines

JavaScript/Node.js

• Use async/await for asynchronous operations
• Use structured logging via logger.logInfo(), logger.logError()
• Include correlation IDs in log calls
• Wrap route handlers with asyncHandler for error handling

React Components

• Use functional components with hooks
• Use Material-UI components for consistency
• Follow existing patterns in frontend/src/components/

API Endpoints

• Return { success: true/false, data/error } format
• Use Danish error messages for user-facing errors
• Log errors with context and correlation IDs

Danish Language

The codebase and UI are in Danish. Key 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
• Tagareal = Roof area
• Rygningslængde = Ridge length
• Facadelængde = Facade length

Common Commands

npm run dev                    # Development with hot reload
npm run build                  # Build frontend
pm2 restart tilbudgivern-unified  # Restart server
npm run test:pw                # Playwright tests
cd backend && npm test         # Jest unit tests

Environment Variables

Required in backend/.env:

• OPENAI_API_KEY - for AI features
• DB_HOST, DB_USER, DB_PASSWORD, DB_NAME - database

Optional:

• ORDRESTYRING_API_TOKEN - order management
• OPENAI_ADMIN_KEY - cost tracking