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.

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.