first commit
This commit is contained in:
@@ -0,0 +1,399 @@
|
||||
# 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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```ts
|
||||
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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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.
|
||||
Reference in New Issue
Block a user