aza/AzA march 2026/project_handover.md

# AZA - Master Handover / Operational Runbook

## Working Mode Rules

- User does not tinker or manually edit files.
- Always provide 1:1 Composer patches (usually Opus).
- One step at a time.

## CURRENT PROJECT PHASE (2026-03-25)

**Phase:** B1 Backend Sprint – Server-Side OpenAI Architecture (Variant B mandatory)

**ARCHITECTURE DECISION VARIANT B (mandatory, 2026-03-25):**
- NO OpenAI key in the desktop app
- NO per-customer OpenAI key requirement
- NO shared OpenAI key client-side
- Instead: AZA Office talks ONLY to own AZA backend
- Only the AZA backend talks to OpenAI
- The OpenAI key resides EXCLUSIVELY server-side
- NO half-measures, NO shared-key hacks

**Honest Assessment:**
- Desktop app is far advanced and fundamentally usable
- Architecture decision Variant B is made
- Hetzner backend is now being seriously built as server path
- WordPress/Shop (Hostpoint) continues in parallel

## B1 BACKEND SPRINT (4 Weeks)

| Week | Approx. Dates | Focus |
|------|--------------|-------|
| **1** | Mar 25 – Apr 01 | Backend Chat Proxy Endpoint (POST /v1/chat) + Auth + Rate Limiting |
| **2** | Apr 02 – Apr 08 | Desktop app: all OpenAI calls via backend instead of direct |
| **3** | Apr 09 – Apr 15 | Hetzner Deploy: Docker/Caddy/HTTPS + Production Env + Smoke Tests |
| **4** | Apr 16 – Apr 22 | E2E Test Desktop→Backend→OpenAI + Customer journey without OpenAI key + Go-Live |

## CURRENT PRIORITY ORDER (B1 Backend Sprint)

1. **Backend Chat Proxy POST /v1/chat** (Week 1) – Foundation of architecture
2. **Desktop app migration to backend** (Week 2) – Migrate all OpenAI calls
3. **Hetzner Deploy** (Week 3) – Set up production server
4. **E2E Test + Go-Live backend path** (Week 4) – Customer journey without OpenAI key
5. WooCommerce/Stripe purchase path runs IN PARALLEL (Hostpoint)

**EXPLICITLY DEFERRED / NOT NOW:**
- Update comfort / separate auto-updater
- Browser-AZA web app (after backend architecture)
- Large refactors not serving Variant B

**HOSTPOINT vs. HETZNER:**
- Hostpoint remains for website/marketing/WooCommerce/Stripe
- Hetzner is NOW the backend path for OpenAI proxy/API
- Both run in parallel, not against each other

## NEXT MAIN BLOCK (B1-W1)

**Backend Chat Proxy Endpoint (POST /v1/chat)**

**Why this block first:**
- Without /v1/chat, desktop app cannot migrate away from direct OpenAI calls
- Pattern already exists: /v1/transcribe does exactly this for audio transcription
- Everything else (Hetzner deploy, key removal from app) depends on this

**What already exists:**
- POST /v1/transcribe: Backend→OpenAI for transcription (WORKS)
- Auth contract: X-API-Token + X-Device-Id headers
- Docker/Caddy/Compose: Deployment stack in deploy/
- License system: /license/status endpoint
- OpenAI client: imported and configured in backend_main.py

**What is missing (B1-W1 scope):**
1. POST /v1/chat endpoint in backend_main.py
2. Request model: model, messages, temperature, max_tokens etc.
3. Server-side OpenAI chat.completions.create
4. Rate limiting per token/device
5. Local Docker test

**Target customer workflow (after B1 complete):**
1. Customer buys via WooCommerce/Stripe
2. Customer installs → app starts → NO OpenAI key needed
3. All AI features run through AZA backend on Hetzner
4. OpenAI key resides ONLY on the server

**Blocker Rule:** One clear block at a time. No 10 construction sites simultaneously.

## CUSTOMER JOURNEY ANALYSIS (2026-03-25)

| Step | Status | Detail |
|---|---|---|
| Purchase (WooCommerce) | IN PROGRESS (parallel) | Docs ready, 7 admin steps on Hostpoint |
| Download | PARTIAL | Mechanism exists, WooCommerce upload missing |
| Installer | FUNCTIONALLY COMPLETE | No code signing (SmartScreen warning) |
| Activation | BRIDGE IMPLEMENTED | AZA key sets full mode, trial dialog shows status |
| First Start | BEING REBUILT (VARIANT B) | OpenAI key being replaced by backend proxy. B1 sprint running. |

## OPEN FOCUS BLOCKS

| Priority | Block | Description |
|---|---|---|
| HIGHEST | B1-W1: Backend /v1/chat | Chat Proxy Endpoint – foundation of Variant B |
| HIGHEST | B1-W2: Desktop migration | All OpenAI calls via backend |
| HIGHEST | B1-W3: Hetzner Deploy | Docker/Caddy/HTTPS on Hetzner VPS |
| HIGHEST | B1-W4: E2E + Go-Live | Desktop→Backend→OpenAI end-to-end |
| HIGH (parallel) | FB-A: WooCommerce | Stripe purchase path on Hostpoint |
| MEDIUM | FB-C: Signing | Signing readiness prepared |
| DEFERRED | FB-D: Update Comfort | Only after stable customer journey |

## PRODUCT NAME – CURRENT DIRECTION

**Current favorite:** AZA Office

**Preferred long form:**
- **AZA Office – Ihr medizinischer KI-Arbeitsplatz fuer die Praxis**

**Second good variant:**
- AZA Office – Die KI-Assistenz fuer medizinische Dokumentation

**Status:** Current preferred naming direction. Not yet legally/brand-strategically finalized. Use for WooCommerce/website/download/Go-Live/product presentation.

**Earlier shortlist (AZA Desktop):** Documented in project_roadmap.json and project_plan.json. Superseded by AZA Office.

## WORKING PRINCIPLES FOR NEXT CHATS

- Root-cause-first instead of blind patching
- One clear block at a time
- No 10 construction sites simultaneously
- Weight real installed builds higher than code assertions
- Don't declare "done" too early
- Distinguish Desktop into:
  1. Dev code
  2. Newly built installer
  3. Real behavior in installed build

## Key Commands

**Local start:**
```
cd "C:\Users\surov\Documents\AZA\backup 24.2.26"
powershell -ExecutionPolicy Bypass -File .\deploy\local_reset_and_start.ps1
```

**Tests:**
```
powershell -ExecutionPolicy Bypass -File .\deploy\authorized_status.ps1
powershell -ExecutionPolicy Bypass -File .\deploy\smoke_suite.ps1
powershell -ExecutionPolicy Bypass -File .\deploy\docker_smoke.ps1
```

## Desktop UX Block (2026-03-18)

- Benutzerdaten bei Deinstallation erhalten (Inno Setup, Standard: Nein)
- Signatur-UI: Haekchen "Profilname verwenden" + abweichender Signaturname in Einstellungen
- Rechtsklick-Haekchen im Minifenster (synchronisiert)
- Kommentare-Fenster (TEILWEISE: Grundstruktur, Detailmodus + Live-Update offen)
- Briefstil-Lernen (DOCX-Upload, Stilprofil-Analyse, Profilauswahl, Integration)
- Briefstil-Profile Fix: KISIM/Klinisch als feste Systemprofile, vereinheitlichtes Stilprofil-UI im Brief-Bereich
- Autotext Root-Cause-Fix (_is_admin NameError, Listener-Revert)
- Persistenz-Patch: Erststart-Consent, Profil+Code, Kommentare-Toggle, Einstellungs-Gruppierung
- Uebersetzer-Stabilitaetsfix: Toplevel-Embedded statt Tkinter-in-Thread
- Briefprofile: KISIM Bericht + Klinischer Bericht als vordefinierte Profile

## AZA Clean Uninstall / Reset Tool

**Per Doppelklick:** `AZA_Deinstallieren.bat`

**Per PowerShell:**
```
powershell -ExecutionPolicy Bypass -File .\tools\aza_clean_uninstall.ps1
```

- Modus 1: Nur App entfernen, Benutzerdaten behalten
- Modus 2: Vollstaendig zuruecksetzen (App + Benutzerdaten)
- Kein Neustart noetig (Standardfall)
- Danach direkt Neuinstallation moeglich

## Do-Not-Break Rules

1. Do not change existing API response formats (especially /license/status).
2. Do not modify auth/security mechanisms.
3. Do not log or print secrets/tokens/keys.
4. Signature fallback: profile name used when no explicit signature set.
5. User data in %APPDATA%\AZA Desktop NOT deleted on uninstall by default.
6. Style learning from old letters: only style/structure, NEVER copy patient data or old content.

## Correction Patch (FIX-01) – 2026-03-19

1. Translator label: "Fachuebersetzer" renamed to "Uebersetzer" everywhere
2. Comments window: auto-open checkbox (persistent), live-update on KG change, clickable diagnosis headings with detail popups
3. Correction window: scrollbar for saved corrections list
4. Style profile live application: brief regenerated immediately on profile change/toggle
5. "Profil anwenden" button in style profile management dialog
6. KG creation writes directly to main window (no popup)
7. Persistence: dokumente_collapsed now properly saved/loaded
8. Main window centering: robust delayed centering after widget build via self.after()

## FIX-02 Nachschaerfungs-Patch (2026-03-19)

1. Style profile dialog: now management-only (status display, learn, delete). Active selection exclusively in brief window.
2. Comments window: auto-opens after KG creation when checkbox is active (not just refreshes existing window).
3. Logo separation: Wassertropfen (logo.ico) for EXE/desktop/installer/title bar icon. Original logo (logo.png) for internal branding (bottom-left).

Files: basis14.py, aza_text_windows_mixin.py, aza_desktop.spec, logo.png, logo.ico

## FIX-09/10/11 Quellenstrenge Kommentarlogik – Inhaltsquelle / Originallink Trennung (2026-03-22)

Root Cause (FIX-09): LLM generated medication info purely from model knowledge.
Root Cause (FIX-10): PharmaWiki regex wrong (used h2/h3 instead of span#subtitle). Compendium.ch is SPA (not scrapable).
Root Cause (FIX-11): Content source and external link were mixed in one dropdown/dict.

Fix (FIX-11): Clean separation of content source and external link:

**CONTENT SOURCE** (what is shown in detail window):
- `_fetch_doccheck_info(med_name)`: DocCheck Flexikon (default) – server-rendered, h2/h3 headings
- `_fetch_pharmawiki_info(med_name)`: PharmaWiki (fallback) – span#subtitle headings
- User-selectable via "Inhaltsquelle:" dropdown, persistent in `med_content_quelle`
- New dict `_MED_CONTENT_QUELLEN` (DocCheck, PharmaWiki)
- Curated `_MEDICATION_FACTS` as offline fallback

**EXTERNAL LINK** ("Originalquelle oeffnen" button):
- CH = Compendium, AT = BASG, DE = BfArM – UNCHANGED
- Still via `_MED_QUELLEN` / `medikament_quelle` – NOT modified

Therapies/procedures: separate handling via DocCheck/PharmaWiki (unchanged).
Candidate logic (Dermowarte→Dermovate etc.): untouched.

Files: basis14.py

## ARCH-MED: Medication Source Architecture (2026-03-22)

Architecture (implemented):
1. Detect medication in KG text (existing tagging + validation)
2. Fetch content from DocCheck Flexikon (default) or PharmaWiki (user choice/fallback)
3. Inject source text into LLM prompt (strict: only use provided data)
4. Curated facts list as offline fallback
5. External link always country-based (CH/AT/DE)
6. Omit anything not from the source

Coverage: All medications available on DocCheck Flexikon + PharmaWiki.

Next steps:
1. Caching strategy (cache fetched content locally)
2. Robustness against HTML structure changes
3. Long-term: Compendium API / HCI Solutions data license evaluation

Later market profiles (DE: BfArM, AT: BASG) separately.

## Zukunftsblock – Internationalisierung / Laender- und Quellenprofile (GEPARKT)

**Status:** Zukunftsthema – NICHT fuer jetzt. Erst nach DACH-Stabilitaet und Produkterfolg.

**Voraussetzung:** DACH (CH/DE/AT) stabil, Go-Live gesichert, Produkt erfolgreich.

**Zielbild:**
- UI/Sprache, Medikamenten-/Diagnose-/Therapiequellen pro Markt anpassbar
- Profil-Felder: app_language, market_region, med_source_profile, dx_source_profile, therapy_source_profile
- Manueller Override durch Benutzer/Praxis
- Nicht hart nach Herkunftsland schalten – saubere Profil-Logik
- Handelsnamen/Zulassungen/Fachinfos sind laenderspezifisch → Quellenprofile pro Markt

**Kein aktueller Implementierungsblock.** Erst nach Go-Live und DACH-Erfolg relevant.

## Windows Code-Signing / Smart App Control Readiness (2026-03-23)

**Problem:** Windows Smart App Control blockiert unsignierte Apps bei Kunden.

**Status:** Signing-Readiness vorbereitet, noch NICHT produktiv aktiviert.

**Vorbereitet:**
- `sign_release.ps1` – signiert EXE + DLLs/PYDs + Installer (DryRun-Modus verfuegbar)
- `build_and_test_release.ps1` – Signing-Schritt integriert (optional, graceful skip)
- `build_release_artifacts.ps1` – Artefakt-Report mit Signatur-Status
- `SIGNING_READINESS.md` – Vollstaendige Dokumentation

**Signing-Reihenfolge:** DLLs/PYDs → EXE → Installer-Build → Installer signieren → Artefakt-Report

**Vor Kundenauslieferung noch offen:**
1. EV Code-Signing-Zertifikat beschaffen
2. signtool.exe installieren (Windows SDK)
3. Publisher-Name abstimmen (Zertifikat ↔ AppPublisher ↔ Handelsregister)
4. Produktiver Signierlauf + Test auf Windows-PC mit Smart App Control

**Publisher-/Namenskonsistenz (Analyse 2026-03-23):**

3 Namensformen im Projekt – beabsichtigt, keine Inkonsistenz:
- **AZA MedWork** = Firma/Publisher → SIGNING-KRITISCH (Installer, Legal, Consent, E-Mail-Absender)
- **AZA Desktop** = Produktname → konsistent, kein Handlungsbedarf
- **AZA Medical AI Assistant** = interner Projektname → nicht signing-relevant

Vor Zertifikatskauf: HR-Name pruefen, AppPublisher auf Zertifikats-Subject abstimmen.
Falls HR-Name abweicht: alle signing-relevanten Stellen gemeinsam anpassen (Liste in handover.md).
Nach Festlegung: Publisher-Name NICHT mehr wechseln (SmartScreen-Reputation).