PowerOn PORTA -- Dokumentation

Produkt

PowerOn PORTA ist eine Multi-Tenant SaaS-Plattform mit Feature-Store-Modell, AI-Agent-Workspace und mandantenweiter Datenneutralisierung.

Komponente	Repository	Technologie	Beschreibung
Frontend Nyla	frontend_nyla	React/TypeScript, Vite	Zentrales UI für alle Features
Gateway	gateway	FastAPI, Python, PostgreSQL	Backend REST-API, Services, AI-Core
Private LLM	private-llm	Python	Internes LLM für Neutralisierung + sensitive Daten
Teams Bot	service-teams-browser-bot	TypeScript/Node.js	Bot für Teams-Meeting-Teilnahme
Wiki	wiki	Markdown	Dokumentation (dieses Repo)

---

Ordnerstruktur

Ordner	Zweck	Wann nutzen
a-strategy/	Produkt-Vision, Strategie, Roadmap, Markt, Investor	Richtung setzen, Business-Kontext
b-reference/	Wie das System funktioniert (code-verifiziert)	System verstehen, Architektur-Fragen
c-work/	Laufende Arbeit -- Kanban (plan → build → validate → done)	Feature planen, bauen, testen
d-guides/	How-to: Dev-Setup, Deployment, Testing, Coding-Regeln	Etwas tun, Prozess nachschlagen
e-compliance/	Sicherheit, Datenschutz, Audit-Dokumente	Regulatorische Fragen
f-decisions/	Entscheidungen (ADR-light): Kontext, Entscheidung, Konsequenz	Warum wurde X so entschieden?
z-archive/	Veraltete Docs mit Forward-Link zum Nachfolger	Historischer Kontext

---

Lebenszyklus: Feature oder Refactor

1. Neues Arbeits-Dokument in c-work/1-plan/ anlegen (Vorlage: c-work/_TEMPLATE.md)
2. Bei Umsetzungsbeginn → nach c-work/2-build/ verschieben
3. Bei Test-Phase → nach c-work/3-validate/
4. Wenn merged/released → nach c-work/4-done/
5. Einmalig: betroffene b-reference/ Seite aktualisieren, TOPICS.md prüfen
6. Arbeits-Dokument → z-archive/ verschieben

Kernregel: Während Planung, Umsetzung und Testing pflegst du nur das eine Arbeits-Dokument in c-work/. Kanon-Seiten in b-reference/ und TOPICS.md werden erst am Ende aktualisiert.

---

b-reference/ Aufbau

b-reference/
├── product.md              Komponentenübersicht, Repo-Map, Tech-Stack
├── gateway/                Backend-Komponente
│   ├── architecture.md        Module, Services, Interfaces
│   ├── ai-agent.md            Agent Core, Tools, Knowledge/RAG
│   ├── workflow.md            Workflow-Engine, Methoden, Aktionen
│   ├── automation.md          Automation v1 + v2
│   ├── billing.md             Billing, Subscriptions
│   └── features/              trustee.md, commcoach.md, chatbot.md, ...
├── frontend-nyla/          Frontend-Komponente
│   └── architecture.md        Seiten, Komponenten, Hooks, Routing
├── private-llm/            Internes LLM
│   └── architecture.md        Setup, Modelle, Gateway-Integration
├── teams-bot/              Teams Meeting Bot
│   └── architecture.md        Service, WebSocket, Architektur
└── platform/               Cross-Cutting (repo-übergreifend)
    ├── neutralization.md      Gateway + Private-LLM Zusammenspiel
    ├── rbac.md                Rollensystem (Gateway + Frontend)
    └── navigation.md          Navigation API (Gateway → Frontend)

---

Cursor-Regel: Doc-Sync

Eine Cursor-Rule sorgt dafür, dass der AI-Assistent bei konzeptionellen Code-Änderungen automatisch an die Wiki-Pflege erinnert.

Datei: @poweron/.cursor/rules/doc-sync.mdc (Quelle: wiki/d-guides/doc-sync.mdc)

Falls die Regel lokal noch nicht existiert, kopiere sie:

# Prüfen und kopieren (PowerShell)
$src = "wiki\d-guides\doc-sync.mdc"
$dst = ".cursor\rules\doc-sync.mdc"
if (-not (Test-Path $dst)) {
    New-Item -ItemType Directory -Path ".cursor\rules" -Force | Out-Null
    Copy-Item $src $dst
    Write-Host "doc-sync.mdc installiert"
} else {
    Write-Host "doc-sync.mdc bereits vorhanden"
}

Was die Regel tut:

• Erinnert bei Änderungen an API, Domain-Logik, Security, RBAC, Navigation, Features, Billing
• Während Arbeit: c-work/<phase>/<feature>.md pflegen
• Bei Abschluss: betroffene b-reference/ Seite + TOPICS.md aktualisieren
• Kein Doku-Zwang bei reinen Refactors, Formatting oder Test-only Changes

---

Für AI-Assistenten

Immer zuerst laden: TOPICS.md -- dort steht, welche Datei für welches Thema massgeblich ist.

---

Status-Block (Kopf jeder Kanon-Seite)

<!-- status: canonical | draft | superseded -->
<!-- lastReviewed: YYYY-MM-DD -->
<!-- verifiedAgainst: gateway@<sha>, frontend_nyla@<sha> -->