tilbudgivern/GEMINI.md

GEMINI.md

This file provides a comprehensive overview of the Tilbudgivern project, its structure, and how to work with it.

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.

Key Features:

• AI-generated quotes: Utilizes OpenAI GPT-4 to generate detailed quotes.
• Interactive feedback: Allows for adjustments to quotes based on feedback.
• Price database: Built-in database with experience-based prices for carpentry work.
• Responsive design: Works on both desktop and mobile.
• Audit trail: Saves all quotes and feedback for analysis.
• Smart Packages: 15 pre-configured carpenter packages for roofing work that auto-calculate based on geometry.
• Roof Geometry Calculation: Supports 7 different roof types for accurate area calculations.
• Ordrestyring Integration: Integrates with the Ordrestyring GraphQL API for customer, case, and offer management.

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 Frontend Components (frontend/src/components/)

• InlineSmartPackage.js: Smart package wizard with a 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, and tooltips.

Technologies

• Frontend: React 18 with Material-UI
• Backend: Node.js with Express
• Database: MariaDB/MySQL (running on host, not containerized)
• AI: OpenAI GPT-4 API
• Containerization: Docker (for PostgreSQL in older setups)
• Process Manager: PM2 (process name: tilbudgivern-unified)
• Testing: Playwright, Selenium, Jest

Getting Started

Prerequisites

• Node.js 18+
• Docker and Docker Compose (for older setups)
• MariaDB/MySQL
• OpenAI API key
• Ordrestyring API token

Quick Start

1. Install dependencies:

   # Root project
   npm install
   
   # Backend
   cd backend
   npm install
   
   # Frontend
   cd ../frontend
   npm install
   cd ..
   

2. Set up the database:

   • The project uses a MariaDB/MySQL database. Ensure it is installed and running.
   • The database name is tilbudgivern.
   • Schema files can be found in database/schema_system_logs.sql and migrations in database/migrations/ and backend/migrations/.

3. Configure the environment: Create a .env file in the backend directory and add the following:

   OPENAI_API_KEY=sk-your-actual-openai-api-key-here
   DB_HOST=localhost
   DB_USER=your-db-user
   DB_PASSWORD=your-db-password
   DB_NAME=tilbudgivern
   ORDRESTYRING_API_TOKEN=your-ordrestyring-api-token
   

4. Start the application:

   npm run dev
   

   This command starts the unified server with hot reload.

Building, Running, and Testing

Development

• Start development server: npm run dev
• Build frontend: npm run build
• Start unified server (production): npm run start

PM2 (Process Manager)

• Restart application: pm2 restart tilbudgivern-unified
• View logs: pm2 logs tilbudgivern-unified
• Check status: pm2 status

Testing

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

Deployment

The application is deployed using PM2. A detailed deployment guide can be found in docs/deployment/DEPLOYMENT.md.

Development Conventions

• Coding Style: Follow the existing patterns in each folder. The frontend uses react-scripts with the default ESLint config.
• Commit Messages: Use Conventional Commits (e.g., feat: ...).
• Pull Requests: PRs should include a brief summary, test evidence, and screenshots for UI changes.

External Integrations

Ordrestyring API

• GraphQL endpoint: https://beta7-api.ordrestyring.dk/graphql
• Purpose: Used for customers, cases, offers, calendar, and hours tracking.
• Documentation: A complete guide to the Ordrestyring API integration can be found in apitest/README.md.

Material Suppliers

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

Database

• Type: MariaDB/MySQL
• Database Name: tilbudgivern
• Key Tables: smart_packages, package_tasks, package_materials, materials, customers, projects
• Schema: database/schema_system_logs.sql
• Migrations: database/migrations/, backend/migrations/

Logging

The backend implements structured JSON logging with correlation IDs for end-to-end request tracing. Logs are persisted in the system_logs table. See backend/LOGGING.md for more details.

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