leistungsbilanz-ts/AGENTS.md

AGENTS.md

Project Context

This repository contains a web application for creating, editing, calculating, and documenting electrical power balances for building-services electrical planning.

The application is intended for small internal use by approximately 2–3 concurrent users. It should support practical planning workflows, not an over-engineered enterprise architecture.

The domain is electrical building planning, especially German TGA / ELT planning. Important concepts include:

• Power balance / Leistungsbilanz
• Distribution boards / Verteilungen
• Electrical consumers / Verbraucher
• Installed power / installierte Leistung
• Demand factor / Gleichzeitigkeitsfaktor
• Calculated demand power / berechnete Leistung
• Voltage, current, phases, cos phi
• Device groups and individual devices
• Project-based calculation and documentation

Use English identifiers in code, database fields, interfaces, classes, and file names. German wording is allowed and preferred in UI labels, reports, and domain-facing text.

Main Goal

Build a maintainable web application that allows users to:

• Create and manage projects
• Define electrical distributions or calculation areas
• Add individual electrical consumers
• Add grouped consumers with quantity
• Assign technical parameters to consumers
• Calculate installed and demand power
• Structure consumers by project, distribution, area, system, or category
• Export or print a usable power-balance report later

The application should be practical for electrical planners and should keep the data model understandable.

Technology Direction

Preferred stack:

• TypeScript
• Node.js backend
• SQLite database for the initial version
• ORM is allowed and preferred if it improves type safety and maintainability
• Drizzle ORM is preferred for a more explicit SQL-oriented approach
• Prisma is acceptable if the project already uses it
• Frontend may be React-based if a UI is implemented
• Docker support for local development is desired

Do not introduce unnecessary infrastructure such as PostgreSQL, Redis, Kubernetes, microservices, message queues, or complex event systems unless explicitly requested.

SQLite is sufficient for the expected initial workload.

Architecture Principles

Keep the application modular, but avoid excessive abstraction.

Preferred structure:

src/
├─ domain/
│  ├─ models/
│  ├─ services/
│  └─ calculations/
├─ db/
│  ├─ schema/
│  ├─ migrations/
│  └─ repositories/
├─ server/
│  ├─ routes/
│  ├─ controllers/
│  └─ middleware/
├─ frontend/
│  ├─ components/
│  ├─ pages/
│  └─ utils/
└─ shared/
   ├─ types/
   └─ validation/

The exact structure may be simplified if the project is still small.

Use object-oriented design where it is useful for domain behavior, but do not force everything into classes.

Good candidates for classes:

• Project
• PowerBalance
• DistributionBoard
• Consumer
• ConsumerGroup
• CalculationService
• ReportGenerator

Good candidates for interfaces/types:

• DTOs
• API request/response shapes
• ORM result types
• Configuration objects
• Form data
• Validation schemas

Avoid duplicating the same model excessively across domain, database, API, and frontend. Some separation is acceptable, but keep mappings simple and explicit.

Naming Conventions

Use English names in code.

Examples:

• Project
• PowerBalance
• DistributionBoard
• Consumer
• ConsumerGroup
• installedPower
• demandFactor
• demandPower
• ratedCurrent
• powerFactor
• quantity
• voltage
• phaseCount

Use PascalCase for classes, interfaces, React components, and types.

Use camelCase for variables, properties, functions, and methods.

Use kebab-case for file names unless the local framework convention requires otherwise.

Examples:

power-balance.service.ts
consumer.model.ts
distribution-board.repository.ts
calculation-utils.ts

Domain Model Guidelines

A consumer must still have a quantity. This allows the same structure to represent either a single device or a grouped device entry.

Example:

type Consumer = {
  id: string;
  projectId: string;
  distributionBoardId?: string;
  name: string;
  category?: string;
  quantity: number;
  installedPowerPerUnit: number;
  installedPowerTotal: number;
  demandFactor: number;
  demandPower: number;
  voltage?: number;
  phaseCount?: 1 | 3;
  powerFactor?: number;
  note?: string;
};

The calculated fields may either be persisted or calculated dynamically. Prefer dynamic calculation first unless persistence is needed for reporting, auditability, or performance.

Calculation Rules

Keep calculation logic centralized.

Do not spread electrical formulas across route handlers, UI components, or database repositories.

Use dedicated calculation services or pure functions.

Examples:

src/domain/calculations/power-calculation.ts
src/domain/services/power-balance.service.ts

Typical calculation concepts:

• Installed power total = quantity × installed power per unit
• Demand power = installed power total × demand factor
• Current calculation depends on voltage, phase count, and power factor

When implementing formulas, add comments for the electrical meaning, especially where three-phase and single-phase calculations differ.

Always be careful with units.

Preferred base units:

• Power: kW
• Current: A
• Voltage: V
• Demand factor: decimal number from 0 to 1

If other units are added later, implement explicit conversion helpers.

Database Guidelines

Use SQLite initially.

Keep schema clear and readable.

Avoid premature normalization. Normalize where it prevents real inconsistency, not just for theoretical purity.

Recommended core tables:

• projects
• power_balances
• distribution_boards
• consumers
• consumer_categories or system_types, if needed later

Use migrations. Do not manually modify the database schema without creating a migration.

Use repositories or database access modules. Do not place raw database queries directly in UI components or high-level route handlers.

API Guidelines

Keep API routes resource-oriented.

Example routes:

GET    /api/projects
POST   /api/projects
GET    /api/projects/:projectId
PUT    /api/projects/:projectId
DELETE /api/projects/:projectId

GET    /api/projects/:projectId/power-balances
POST   /api/projects/:projectId/power-balances

GET    /api/power-balances/:powerBalanceId/consumers
POST   /api/power-balances/:powerBalanceId/consumers
PUT    /api/consumers/:consumerId
DELETE /api/consumers/:consumerId

Validate all incoming API data.

Use shared validation schemas if possible.

UI Guidelines

The UI should be practical and data-entry friendly.

Prioritize:

• Tables for consumers
• Inline editing where useful
• Clear grouping by distribution board or area
• Totals at group and project level
• German UI labels
• Consistent units in column headers
• Minimal clicks for adding multiple consumers

Use German labels such as:

• Projekt
• Leistungsbilanz
• Verteilung
• Verbraucher
• Anzahl
• Leistung je Stück
• Installierte Leistung
• Gleichzeitigkeitsfaktor
• Berechnete Leistung
• Bemerkung

Code identifiers must remain English.

Testing Guidelines

Add tests for calculation logic.

Calculation tests are more important than superficial UI tests.

At minimum, test:

• Total installed power calculation
• Demand power calculation
• Quantity handling
• Single-phase current calculation, if implemented
• Three-phase current calculation, if implemented
• Edge cases such as quantity 0, demand factor 0, and missing optional values

Do not change formulas without updating or adding tests.

Docker and Development

The project should be runnable in a local development environment, including on Windows with Docker Desktop.

If Docker is used, provide:

• Dockerfile
• docker-compose.yml
• clear volume handling for SQLite database files
• documented development commands

Avoid configurations that only work on Linux unless explicitly documented.

Documentation Expectations

Keep documentation short but useful.

Document:

• How to install dependencies
• How to start the dev server
• How to run migrations
• How to run tests
• Basic domain assumptions
• Important formulas

Prefer concise Markdown documentation.

Development Progress Documentation

Document the current implementation status in dedicated Markdown files whenever regular status updates are requested.

• Keep status tracking explicit with TODO, WIP, and DONE sections.
• For each relevant module or feature area, document:
  • what it does,
  • how it works,
  • which files/functions are involved,
  • why important design choices were made,
  • current limitations or open points.
• Break larger features into small sub-sections so someone new can read through and understand the flow.
• Update these Markdown status documents incrementally during implementation so progress can be tracked clearly over time.
• Prefer understandable, step-by-step explanations over overly brief summaries when needed for clarity.

Coding Style

Write clear, explicit TypeScript.

Prefer readability over cleverness.

Avoid:

• unnecessary generic abstractions
• magic numbers
• hidden side effects
• large files with unrelated responsibilities
• mixing UI, database, and calculation logic

Use meaningful names even if they are longer.

Safety and Data Integrity

Do not delete user data without explicit confirmation in the UI or API design.

Use soft-delete only if the project introduces audit or recovery requirements.

Validate numeric values carefully:

• quantity must not be negative
• demand factor should normally be between 0 and 1
• installed power must not be negative
• voltage must be positive
• phase count should be limited to valid values

Agent Behavior

When modifying this repository:

1. Inspect the existing structure before adding new files.
2. Reuse existing patterns unless they are clearly wrong.
3. Keep changes small and focused.
4. Do not introduce large framework changes without explicit instruction.
5. Do not silently change the database technology.
6. Do not silently change the ORM.
7. Keep domain terms consistent.
8. Add or update tests when changing calculation logic.
9. Update this AGENTS.md if a new recurring project rule is established.
10. Prefer practical implementation over theoretical perfection.

Out of Scope Unless Explicitly Requested

Do not implement the following unless explicitly requested:

• Multi-tenant user management
• Role-based permissions
• Cloud deployment
• PostgreSQL migration
• Realtime collaboration
• Complex report designer
• Full BIM integration
• GAEB integration
• Revit integration
• Authentication providers
• Enterprise audit logging

Preferred First Milestone

The first useful milestone should be:

• Create a project
• Create one power balance
• Add distribution boards
• Add consumers with quantity
• Calculate installed power and demand power
• Show totals in the UI
• Persist data in SQLite
• Provide basic tests for calculation logic

Do not start with advanced reporting before the core data and calculation workflow works.

Current UI Workflow Requirements

Implement and preserve the following navigation and workflow structure:

1. A dedicated project page that lists all projects and allows creating new projects.
2. On the same project page, users can configure global devices/consumers.
3. Inside a project, users first see all distribution boards and can open a selected board.
4. Circuit lists are edited in a dedicated view where up to 3 circuit lists can be opened in parallel.
5. Users must be able to copy circuit entries/consumers between the open circuit lists with minimal clicks.
6. In the circuit-list view, exactly 1 list is open by default. Users can add/remove list panels dynamically with a minimum of 1 and a maximum of 3 open lists.

When implementing frontend changes, keep this structure as the default interaction model unless the user explicitly requests a different UX.

Language and Text Rules

Use proper German umlauts (ä, ö, ü, Ä, Ö, Ü, ß) in all new or changed German UI texts and documentation text, unless technical constraints explicitly prevent this.

Responsiveness Rule

Frontend implementations must remain fully responsive by default across mobile, tablet, laptop, and wide desktop breakpoints. Layouts with dynamic panel counts (for example 1-3 parallel circuit-list panels) must adapt so available horizontal space is used appropriately instead of leaving fixed empty columns.

Language and Text Rules (Enforced)

Use proper German umlauts (�, �, �, �, �, �, �) in all new or changed German UI texts and documentation text, unless technical constraints explicitly prevent this.

Project Voltage and Columns Rules

• Project properties must include default single-phase and three-phase voltages. Use 230 V for single-phase and 400 V for three-phase by default, and allow users to change both values in project settings.
• In circuit lists, when a consumer is single-phase and has no explicit voltage override, calculations use the project single-phase default voltage. When a consumer is three-phase and has no explicit voltage override, calculations use the project three-phase default voltage.
• When creating a new consumer/device entry, the standard input fields should be: consumer display name, quantity, unit power, demand factor, and total power.
• By default, the table should initially hide: power factor (cos phi), phase count, and current.
• Users must be able to add any available attribute as a table column at any time, and must be able to reorder column positions.

Open TODOs from docs/electrical-load-balance-requirements-context-dump.md

• Extend CircuitEntry data model with missing fields from requirements, especially circuitNumber, description, deviceType, phaseType, tradeOrCostGroup, group, protectionType, protectionRatedCurrent, protectionCharacteristic, cableType, cableCrossSection, cableLength and comment.
• Allow multiple entries with the same circuitNumber and make this visible/editable in the circuit-list table.
• Implement project-specific device lists (ProjectDeviceList) in backend + UI.
• Implement copying devices both directions between global and project-specific device lists.
• Add separate device naming model with Device.name and Device.displayName.
• Add explicit entry description field (CircuitEntry.description) independent of linked device naming.
• Implement device-link lifecycle on entries: link, unlink/detach, and update propagation from device changes to linked entries.
• Add addCount when adding a device to a circuit list to create multiple entries in one action (addCount != quantity).
• Relax circuit-entry validation so incomplete entries are possible (currently several fields are required).
• Add duplicate-entry action within the same circuit list (separate from copy to another list).
• Add sorting/filtering/bulk-edit capabilities for circuit-list tables (beyond current copy-selection flow).
• Define and implement fixed selection lists for domain fields (deviceType, phaseType, tradeOrCostGroup, group, protection and cable fields).
• Extend tests beyond pure power formulas to cover new circuit-entry/device-link behaviors once implemented.