Immohai Architekturübersicht¶

Status: verbindlicher Zielentwurf
Spezifikationsversion: 0.3.1
Modellbezug: 0.6.2
Implementierungsbezug: frontend-mvp-0.2.5
Stand: 2026-07-05

1. Zweck¶

Diese Datei beschreibt die technische Zielarchitektur der Immohai-App und verbindet fachliche Domänen, Frontend-MVP, Berechnungsengine, lokale Speicherung, Marktmiet-Daten, Batch-Analyse, spätere Persistenz und Deployment.

Die detaillierte Domänentrennung steht in docs/specification/product-domains-and-workflows/application-domains.md.

2. Produktziel¶

Immohai ist eine private Web-App zur transparenten Bewertung von Immobilieninvestitionen gegenüber einer ETF-Alternative unter Best-, Base- und Stress-Annahmen.

3. Fachliche Domänen¶

Einzelanalyse
Batch-Analyse
Meine Objekte
Marktmiet-Daten

Einzel- und Batch-Vollanalyse erzeugen ein normalisiertes PropertyInput und verwenden dieselbe Single-Property-Engine.

4. Zielbild¶

Einzelanalyse ─┐
               ├──> PropertyInput
Batch-Analyse ─┘        ↓
                 Single-Property-Engine
                        ↓
                  AnalysisResult
                        ↓ bewusste Übernahme
                  Meine Objekte

Separat:

Mietdatei
-> RentObservation[]
-> Validierung und Aggregation
-> RentReferenceDataset
-> published
-> RentEstimate
-> Einzel- oder Batch-Analyse

5. Zentrale Regeln¶

Rohdaten werden nie direkt berechnet.
Berechnung wird nicht automatisch gespeichert.
Batch-Ergebnisse werden nicht automatisch persönliche Objekte.
Meine Objekte enthält keine Marktmiet-Rohdaten.
Marktmiet-Daten enthält keine persönlichen Investitionsstatus.
Nur published Mietdatasets liefern automatische RentEstimate-Werte.
UI-Komponenten dürfen wiederverwendet werden.
Datenmodelle, Statuswerte und Speicher bleiben getrennt.

6. Aktueller Frontend-MVP¶

Browser
-> statisches HTML, CSS und JavaScript
-> JavaScript-Single-Property-Engine
-> lokale Browser-Speicher
-> Ergebnisdarstellung
-> Browser-Druck und CSV-Export

Aktiv:

Einzelanalyse
Meine Objekte
lokaler Marktmiet-Prototyp
Batch-Platzhalter
Dokumentation

Nicht aktiv:

zentrales Backend
serverseitige Datenbank
Login
Gerätesynchronisation
produktive Batch-Analyse
Monte Carlo in der App
serverseitige PDF-Erzeugung

7. Deployment¶

Docker-Compose-Services:

immohai-web
immohai-docs

Lokale Serverports:

App: 127.0.0.1:8200
Doku: 127.0.0.1:8201

Der Host-Nginx übernimmt Reverse Proxy und HTTPS.

8. Seiten¶

Normale App:

/frontend/index.html
/frontend/batch.html
/frontend/objects.html

Adminbereich:

/frontend/admin.html
/frontend/admin-data-import.html

Der sichtbare Produktbegriff lautet Meine Objekte; der technische Dateiname objects.html bleibt vorerst bestehen.

9. Frontend-Schichten¶

UI und Seitensteuerung
  ↓
Adapter und Orchestrierung
  ↓
fachliche Services
  ↓
Berechnungsengine
  ↓
Speicheradapter

UI enthält keine Formeln, KPI-Schwellen, Ratinglogik oder Marktmiet-Aggregationsregeln.

10. Adapter und Orchestrierung¶

Verantwortlich für:

Formularwerte normalisieren
Legacy-Aliase lesen
ValueWithOrigin erzeugen
Defaults und Herkunft auflösen
Szenario-Policies anwenden
PropertyInput erzeugen
Engine aufrufen
PropertyRecord erzeugen

Manuelle finale Werte werden nicht durch Objektprofile verändert.

11. Single-Property-Engine¶

PropertyInput
-> ScenarioInput[]
-> AnnualProjectionRow[]
-> ScenarioResult[]
-> AnalysisResult

Best und Stress erhalten ScenarioAssessments. Nur Base beziehungsweise AnalysisResult erhält das vollständige Investment Rating.

Fehlende Datenqualität führt zu UNRATED und niemals zu einem automatischen Score 100.

12. Kanonische Feldnamen¶

Neue Ergebnisse schreiben:

monthly_cold_rent
noi_yield_y1
initial_ltv
current_ltv_y1
terminal_net_vs_etf_after_exit
non_purchase_costs_financed_amount

Legacy-Felder werden nur über Adapter gelesen.

13. Marktmiet-Datenarchitektur¶

RentImportRun
-> RentObservation[]
-> Validierung
-> RentAreaStats[]
-> RentReferenceDataset
-> RentEstimate

Dataset-Lifecycle:

draft
published
archived

Automatische Standardsegmente trennen mindestens market_type und unit_scope; Möblierung wird getrennt oder explizit ausgeschlossen.

14. Speicherbereiche¶

immohai.propertyRecords.v1
immohai.marketRentDatabase.v1

Später:

MyObjectsStore
RentReferenceStore
BatchWorkspaceStore

Storage Keys werden nicht ohne Migration geändert.

15. Backend-Zielbild¶

Später möglich:

FastAPI
SQLite als erste private Serverpersistenz
PostgreSQL bei höherer Parallelität oder größerem Volumen
serverseitige Analysehistorie
Importhistorie
Jobs
Reportgenerierung

Zeitpunkt und Datenbankwahl bleiben offene Entscheidungen.

16. Importarchitektur¶

Kaufobjekte:

CSV
-> Mapping
-> NormalizedListing
-> Pre-Screening
-> PropertyInput
-> Vollanalyse

Mietdaten:

CSV
-> RentObservation
-> Aggregation
-> Dataset

CSV ist das bevorzugte erste Austauschformat. XLSX bleibt eine spätere direkte Importoption.

17. Versionierung¶

Das Versionsmanifest verbindet Modell, Engine, PropertyInput-Schema, Defaults, Szenariopresets, Objektprofile und Marktmiet-Schema.

Jeder Rechenlauf und PropertyRecord speichert die wirksamen Versionen.

18. Testbarkeit¶

Berechnungsfunktionen bleiben unabhängig von DOM und Browser-UI testbar.

Pflichtprüfungen:

Konfigurationssync
Schema-Validierung
Baseline-Regression
PropertyRecord-Store
Marktmiet-Aggregation
Frontend-Baseline
MkDocs strict build

19. Umsetzungsreihenfolge¶

Fachmodell und Spezifikationen stabilisieren
Schema, Konfiguration und Engine synchronisieren
Meine Objekte konsolidieren
Marktmiet-Daten stabilisieren
Batch implementieren
Backend und Persistenz
Reporting
Monte Carlo