tilbudgivern/codemaps/backend.md

Backend Structure

Entry point: backend/unified-server.js. It mounts modular routers and defines ~180 routes inline in the same file (verified by grepping app.get/post/put/patch/delete('/api/...') occurrences). Both patterns are live in production — inline routes are not legacy cruft to be migrated, they're simply how a large share of this API is built.

Mounted routers

Mount path	File	Purpose
/api/enhanced	src/routes/enhancedFeatures.js	Roof-type package search, add package to project (loaded in a try/catch at startup, not top-level)
/api/smart-packages	src/routes/smartPackagesRoutes.js	Smart Package CRUD, management view, recalculation (also try/catch-loaded)
/api/stark	src/routes/starkImport.js	Stark CSV catalog upload + import history/status (also try/catch-loaded)
/api/customer-projects	src/routes/customerProjects.js	Customer + project CRUD, the core project lifecycle
/api/ai	src/routes/ai.js	AI feature flags, subscription usage, support-draft generation
/api/users	src/routes/users.js	New (2026-09-04). Admin-only user management CRUD
/api/mobile	src/routes/mobileOrders.js	Field/mobile intake against Ordrestyring order history
/api/analytics	src/routes/analytics.js	KPIs, employees, customers pulled from the Ordrestyring GraphQL layer
/api/product-telemetry	src/routes/productTelemetry.js	Frontend product-usage event tracking + scorecards
/api/ordrestyring	routes/ordrestyring.js	Quote submission, order status/list against Ordrestyring
/api/ordrestyring/offers	routes/offers.js	Offer creation in Ordrestyring
/api/calendar	routes/calendar.js	Calendar read + sync
/api/ordrestyring/case	routes/cases.js	Case detail / work breakdown
/api/visual-reports	routes/visualTestReports.js	Visual test report browsing (admin-API-key gated)
/api/admin/logs	routes/adminLogs.js	Structured log browsing (admin-API-key gated)
/api/health	src/routes/healthDashboard.js	DB/server health metrics
/api/client-errors	routes/clientErrors.js	Frontend error/session reporting intake
/api/support	src/routes/supportTickets.js	osTicket support worklist/ticket creation

Note there are two routes directories: backend/src/routes/ (newer) and backend/routes/ (older, still actively mounted — ordrestyring.js, offers.js, calendar.js, cases.js, adminLogs.js, clientErrors.js, visualTestReports.js). Both are live; the split is historical, not a deprecation boundary.

Dead route files (unmounted — do not assume these are live)

These files exist in backend/src/routes/ but are not required anywhere in the codebase (verified by grepping every require('./src/routes/<name>') call site): bygmaPrisbog.js, categories.js, cleanup.js, pricing.js, quotes.js, uploads.js, webPrices.js. Same situation applied to auth.js, which was deleted 2026-09-04 for exactly this reason — its logic had silently diverged from the real, inline /api/auth/login handler in unified-server.js. Before editing any of these seven files, confirm first whether they're actually reachable; as of this writing, none are.

Inline routes in unified-server.js (representative, not exhaustive)

/api/auth/login, /api/auth (legacy no-op), /api/pdf/generate, /api/web-prices/search, plus ~180 more (183 app.<verb>('/api/...') calls total, verified 2026-09-04) covering pricing, geometry, quote generation, PDF, and Ordrestyring glue. Grep unified-server.js for app\.(get|post|put|patch|delete)\('/api/ to enumerate the current full list — it changes often enough that a static list here would go stale immediately.

Services (backend/src/services/, 68 files)

Grouped by domain:

AI / quote generation — openaiService.js, projectAiService.js, aiSuggestionService.js, aiValidationJobService.js, aiFeatureFlagService.js, codexGenerationService.js, codexCliValidationService.js, quoteRealismService.js, quoteTemplateService.js, quoteBenchmarkService.js, quoteEconomicsService.js

Smart packages — smartPackageService.js, smartPackageManagementService.js, smartPackageDefaultsService.js, smartPackageIntegrityService.js, smartPackageWorkspaceService.js, smartPackageMaterialMatchService.js, smartPackageExcelImportService.js, smartPackageExcelValidationService.js, historicalSmartPackageSearchService.js, packageService.js, materialPackageService.js (an older, parallel package system — see data.md)

Material pricing / import — starkImportService.js, bygmaImportService.js, bygmaPrisbogImportService.js, bygmaScraperService.js, haandvaerkPriserImportService.js, priceImportService.js, pricingService.js, materialPriceStatusService.js, installationManualService.js, webPriceService.js

Project lifecycle — customerProjectService.js, projectCalculationService.js, projectLaborService.js, projectMaterialService.js, projectExperienceService.js, projectFlowValidationService.js, projectQuoteGenerationService.js, roofGeometryService.js, advancedGeometryService.js, timeCalculatorService.js, orderSuggestionService.js, taskCategorizationService.js, planningService.js

Ordrestyring sync/integration — ordrestyringService.js, ordrestyringSyncService.js, ordrestyringQuoteService.js, ordrestyringMoneyService.js, orderStatusService.js, graphqlClient.js, enhancedOrderDataService.js, mobileOrderService.js

PDF / documents — pdfGenerationService.js, pdfResponseService.js, documentParserService.js, ocrService.js, excelMappingService.js

Auth / users — userService.js (new, 2026-09-04, bcrypt + auth_accounts)

Platform / infra — databaseService.js (MariaDB pool + query wrapper; also runs ~37 inline CREATE TABLE IF NOT EXISTS statements at startup — see data.md), databaseCleanupService.js, bootstrapServiceContainer.js, dynamicImportService.js, productTelemetryService.js, googleSearchService.js, repositoryStatusDiscordService.js, supportDraftService.js

Request flow and auth

flowchart LR
    Req["Incoming request"] --> R{"Router or\ninline handler?"}
    R -- "mounted router" --> MW["verifyToken\n(backend/src/middleware/auth.js)"]
    R -- "inline in\nunified-server.js" --> MW
    MW -- "valid JWT" --> Admin{"needs admin?"}
    MW -- "missing/invalid" --> Reject["401/403"]
    Admin -- "yes: requireAdmin" --> Svc["Service layer\n(backend/src/services/*)"]
    Admin -- "no" --> Svc
    Svc --> DBS["databaseService.query()"]
    DBS --> DB[("MariaDB")]

Not every route requires auth — verifyToken is applied per-router/per-endpoint, not globally. Some admin surfaces use a separate optionalAdminApiKeyGuard (API-key based) rather than JWT — see the /api/visual-reports and /api/admin/logs mounts above.

Auth accounts — the auth_accounts / users naming trap

As of 2026-09-04, login credentials moved out of hardcoded env vars into a real table: auth_accounts (id, username, password_hash [bcrypt], role enum admin/user, last_login_at), managed by userService.js and src/routes/users.js.

This is deliberately not called users. A pre-existing, unrelated table named users already exists — it holds employee records synced from Ordrestyring (first_name, last_name, init, email; written by ordrestyringSyncService.js). It has nothing to do with login. If you're adding auth-related columns or queries, make sure you're touching auth_accounts, not users.

The live login handler is the inline POST /api/auth/login in unified-server.js (not a separate router file) — it looks up auth_accounts via userService.findByUsername, verifies with bcrypt, and issues a JWT carrying { username, id, role }. requireAdmin middleware gates /api/users/* on role === 'admin'.