Zum Hauptinhalt springen
CContributors
Zur ProjektseitePilot-WorkspaceDatenschutz
EN
AnmeldenRegistrieren
Kontakt
Zur Projektseite
Audit-Room

Audit-Room: AI-Org Prototype 2.0

README, Vision, Architektur und Audit-Karte als überprüfbarer Kontext für Charter, Lead Ask, Risiko und Missions.

Artefakte
4
Geschlossener Concierge-Pilot
Prototype / Pre-MVP
Provider
codex
Sichtbarkeit
selective
Source Review
Geprüft
Freshness
Aktuell
AktuellQuelle, Snapshots und Review-Gate sind aktuell.

Source Review

Dieser Audit-Room rendert einen freigegebenen Source-Stand.

QuelleFreshnessHash
README.mdREADME.mdLokal verlinkt-
ARCHITECTURE.mdARCHITECTURE.mdLokal verlinkt-
VISION.mdVISION.mdLokal verlinkt-

Seit der letzten Source-Freigabe wurde noch kein Refresh ausgeführt.

Audit-Decision-Verlauf

Öffentliche Versionenkette der gespeicherten menschlichen Audit-Entscheidungen.

project-audit-scorecard@1.0.0Aktuelle Version
C - In Review
Last reviewed
2026-05-15T11:00:00.000Z
Readiness
Multi-Agent-Architektur-Mentor und 5 sekundäre Ask-Kontexte sind fuer kuratierte Contribution-Pruefung strukturiert.
Decision ID
20000000...0004
Ersetzt
-
Verifizierte Artefakte
  • docs/showcase/ai-org.md
  • README.md
  • ARCHITECTURE.md
  • VISION.md
Offene Risiken
  • Architecture Red Team vor offenem Contribution-Flow abschliessen.
README.mdProdukt- und Repo-Kontext ARCHITECTURE.mdTechnische Architektur VISION.mdVision und Produktdoktrin AUDIT.mdContributors Audit Card
README.md

Produkt- und Repo-Kontext

Produktkontext, heutiger Stand, Zielbild und Repo-Struktur als Einstieg für Reviewer und Contributors.

QuelleAI-Org repository

AI‑Org Prototype 2.0

Autonomous‑Agent SaaS • Neo4j‑driven • Multi‑Tenant • Token‑Aware • Prometheus‑Instrumented

End‑to‑End Skeleton, das ganze Software‑Projekte mittels LLM‑Agenten plant, baut, testet und ausliefert. Stack: Python 3.11 · FastAPI · Celery · SQLModel/Alembic · Neo4j 5 · Redis 7 · Prometheus/Grafana · React 18 / Vite / Tailwind · Node 20

✨ Hauptfeatures

ModulKurzbeschreibung
Graph Orchestrator 2.0Neo4j als Source of Truth, LLM‑basiertes Role‑Routing, Prom‑Metriken (blocked tasks, critical path, alert‑counter)
Erweitertes Task‑ModellBusiness‑Wert, Token KPI (Plan + Actual), Purpose‑Relevance, Multi‑Tenant FK
Budget‑GateRedis‑Hash budget:{tenant} + Celery‑Hook (Abbruch wenn Budget < 1 USD)
Monitoring‑StackPrometheus :8000 (FastAPI) + Celery exporter; fertig provisionierte Grafana‑Dashboards
React Admin‑Dashboard
Budget‑Gauge, Backlog‑Table, React‑Flow‑Graph (Bubble‑Size = Value, Color = Status)
MonorepoFrontend‑Workspaces (apps/web, packages/ui, packages/api-client), Backend ai_org_backend
Feedback-VerlaufArtifact-Kommentare liegen als ChatMessages (Intent feedback) inkl. Versions- & Autoren-Metadaten; Migration 20251006 backfillt bestehende ArtifactFeedback-Einträge

📁 1 | Architektur & Code-Struktur

  • Backend API (FastAPI) – Kernanwendung auf Port 8000, bietet REST-Endpunkte (z. B. Tasks anlegen, Backlog einsehen) und orchestriert die LLM-Agenten. In Docker-Umgebungen läuft Uvicorn standardmäßig auf Port 8000.
  • Celery Workers – Asynchrone Worker-Prozesse (eigene Queues für verschiedene Agenten-Rollen wie *dev*, *qa*, *ux_ui*, *planner* etc.), die Aufgaben aus Redis-Queues ziehen und z. B. LLM-APIs aufrufen. (Optional Celery Beat für periodische Aufgaben.)
  • Orchestrator (Scheduler) – Separater Prozess für Ablaufsteuerung. Überwacht den Task-Graphen (Neo4j) und startet neue Tasks, sobald deren Abhängigkeiten erfüllt sind. Führt beim Start einmalig ausstehende DB-Migrationen aus und plant Aufgaben kontinuierlich im Hintergrund.
  • PostgreSQL (Datenbank) – Speichert persistente Daten (Tenants, Purposes, Tasks, Artifacts, Feedback). Läuft im Container auf Port 5432 (Default-Creds: *postgres/ai*, DB *ai_org*).
  • Neo4j (Graph-DB) – Speichert den Pipeline-Graphen (Tasks und Abhängigkeiten) und Artefakt-Beziehungen. Läuft auf *bolt://localhost:7687* (Browser-UI auf Port 7474, Default-Login *neo4j/s3cr3tP@ss*).
  • Qdrant (Vektor-DB) – Vektorenspeicher für semantische Embeddings (Langzeitgedächtnis der Agenten). Läuft auf http://localhost:6333 (keine Authentifizierung).
  • Redis 7 (Broker & Cache) – In-Memory Store als Celery-Broker (Queues) und Cache (z. B. Budgetzählung). Läuft auf *redis://localhost:6379* (Passwort siehe .env).
  • Prometheus & Grafana (Monitoring) – Optionaler Monitoring-Stack. Das Backend stellt Metriken unter /metrics (Port 8000) bereit; ein Celery-Exporter liefert Queue-Metriken (Port 9808). Prometheus (Port 9090) scrapt die Daten und Grafana (Port 3000) visualisiert sie in Dashboards.

Verzeichnisstruktur:

backend/
└─ ai_org_backend/
   ├─ config.py         # ENV via Pydantic‑Settings
   ├─ db.py             # SQLModel Engine + Session
   ├─ main.py           # FastAPI entry
   ├─ models/           # Tenant, Task, Artifact
   ├─ services/         # graph_service, storage, billing
   ├─ tasks/            # celery_app, llm_tasks (dev / ux_ui / qa / telemetry)
   ├─ orchestrator/     # core, graph_orchestrator, executor, router, inspector, scheduler
   ├─ api/              # routers + dependencies
   └─ alembic/          # migrations/
frontend/
└─ apps/web/            # React 18 + Vite
   └─ src/pages/        # AdminDashboard.tsx, TaskGraph.tsx …
frontend/packages/
   ├─ ui/               # Shared UI (Button, Card …) + Storybook
   └─ api-client/       # OpenAPI‑Hooks (axios)
ops/                    # docker‑compose + Helm blueprints
prompts/                # Jinja2 Agent-Prompts
scripts/                # helper scripts
mermaid
Rendering diagram...
flowchart LR

subgraph Client

UI["Frontend (React)"]

end

subgraph Server

API["Backend API (FastAPI)"]

ORCH["Orchestrator\nScheduler"]

CELERY["Celery Workers\n(Queues: dev/qa/ux_ui/telemetry/architect/planner)"]

end

subgraph Data

PG[(PostgreSQL)]

Neo4j[(Neo4j Graph DB)]

Qdrant[(Qdrant Vector DB)]

Redis[(Redis Broker & Cache)]

end

subgraph Monitoring

Prom[[Prometheus]]

Exporter[[Celery Exporter]]

Grafana[[Grafana]]

end

⚙️ 2 | Setup & Quick Start (Lokale Installation)

Docker Compose (Lokale Demo)

  1. Repository klonen:
bash
    git clone https://github.com/3lC4pt41n/ai_org_prototype.git
    cd ai_org_prototype
  1. Umgebungsvariablen einrichten: Kopiere .env.example nach .env und passe die Werte (z. B. OPENAI_API_KEY, NEO4J_PASS etc.) an.
bash
    cp .env.example .env
  1. Container starten: Basisdienste (Backend, DBs, Orchestrator) via Docker Compose hochfahren:
bash
    docker compose -f ops/persistent.yml up -d
    docker compose -f ops/persistent.yml --profile ui up -d         # optional: Frontend
    docker compose -f ops/monitoring.yml up -d                      # optional: Monitoring (Prom+Grafana)
  1. Status prüfen: Stelle sicher, dass alle Container laufen:
bash
    docker compose -f ops/persistent.yml ps

Wichtige Endpunkte:

  • Backend API: http://localhost:8000 (OpenAPI-Doku, /metrics verfügbar)
  • Frontend UI: http://localhost:5173 (Admin-Dashboard; optional)
  • Neo4j Browser: http://localhost:7474 (Login standardmäßig neo4j/Passwort laut .env)
  • Qdrant: http://localhost:6333 (REST-Interface)
  • Grafana: http://localhost:3000 (Login admin / admin, falls aktiviert)

Lokale Entwicklung (ohne Container)

*Hinweis:* Für ein schnelles Coding-Setup können Backend und Worker auch direkt auf dem Host gestartet werden (Docker wird weiterhin für Redis/Neo4j/Qdrant genutzt). Stellen Sie sicher, dass die .env entsprechend auf die laufenden Container-Services zeigt (siehe REDIS_URL, NEO4J_URL etc.).

Backend (Uvicorn)

bash
pip install -e backend/.[dev]  # Ab Projektwurzel mit aktiviertem venv
uvicorn ai_org_backend.main:app --reload --port 9102

Celery Worker

bash
celery -A ai_org_backend.tasks.celery_app.celery worker --loglevel=INFO

Frontend (Entwicklung)

bash
cd frontend
pnpm install
pnpm dev

*Das UI ist danach unter http://localhost:5173 erreichbar.*

Daten & Volumes

Das Compose-Setup nutzt folgende benannte Volumes und Verzeichnisse für persistente Daten:

  • workspace/ – Projekt-Artefakte (vom Backend generiert, inkl. Git-Repository für Code-Artefakte).
  • neo4j_data/ – Neo4j-Datenbank.
  • qdrant_storage/ – Qdrant-Persistenz für Vektordaten.
  • pgdata/ – PostgreSQL-Daten (Persistent Volume).

Troubleshooting

  • Backend nicht erreichbar / Health-Check schlägt fehl:
  • Logs prüfen: docker compose -f ops/persistent.yml logs -f ai-app (Backend-Container)
  • .env prüfen (insb. Datenbank-, Redis-, Neo4j-, Qdrant-URLs und Credentials)
  • Celery verarbeitet keine Tasks:
  • Läuft Redis? (docker compose ps bzw. docker compose -f ops/persistent.yml ps prüfen)
  • Worker-Logs ansehen: docker compose -f ops/persistent.yml logs -f celery-dev (bzw. -f celery-planner für den Planner-Worker)
  • Neo4j Login fehlgeschlagen:
  • Verwende Benutzer/Passwort aus .env (Default: neo4j / s3cr3tP@ss)
  • Ggf. Neo4j-Container neu starten, falls das Default-Passwort nicht übernommen wurde
  • Qdrant liefert Fehler (404 / Verbindung):
  • URL prüfen (QDRANT_URL). Im Compose-Default: http://qdrant:6333 (Container) bzw. http://localhost:6333 (Host)
  • Frontend zeigt keine Daten:
  • Läuft das Backend unter http://localhost:8000? Sind CORS und WebSocket-Endpunkte korrekt konfiguriert?

Nützliche Befehle

bash
# Dienste-Status anzeigen
docker compose -f ops/persistent.yml ps

# Logs eines Dienstes verfolgen (Beispiel: Backend)
docker compose -f ops/persistent.yml logs -f ai-app

# Container neu bauen und starten (Beispiel: Backend nach Code-Änderung)
docker compose -f ops/persistent.yml build ai-app
docker compose -f ops/persistent.yml up -d ai-app

📊 3 | Erweitertes Task-Schema

FeldTypBeschreibung
idstr (PK)8-char UID (Primärschlüssel)
tenant_idstr (FK)Mandanten-Zuordnung (Tenant Isolation)
descriptiontextAufgabentext
statusenumtodo / doing / done / failed
ownerstrZuständige Rolle (Agent/Person)
business_valuefloat€- oder Punkte-Wert (Geschäftswert)
tokens_planfloatgeplantes Token-Budget (in 1k Tokens)
tokens_actualfloattatsächlich verbrauchte Tokens
purpose_relevancefloatRelevanz für Ziel (0–1; wichtiger = größere Bubble)
depends_onstr (FK)Abhängigkeits-Referenz (DAG-Kante)
created_atdatetimeErzeugungszeitpunkt (ISO-UTC)

PostgreSQL wird sowohl in Entwicklung als auch Produktion eingesetzt und mittels Alembic-Migrationen verwaltet.

Datenmodelle & Beziehungen: Das Backend nutzt SQLModel (SQLAlchemy) auf PostgreSQL mit den Haupt-Entitäten Tenant, Purpose, Task, TaskDependency und Artifact (zusätzlich existieren Feedback-Modelle). Ein *Tenant* (Mandant) kann mehrere Purposes (Projekte) besitzen. Jede *Purpose* gehört zu genau einem Tenant und bildet einen Backlog (Sammlung von Tasks) für dieses Projekt. Die einzelnen *Tasks* sind über tenant_id und purpose_id einem Tenant bzw. Purpose zugeordnet. Tasks können Abhängigkeiten untereinander haben: die Tabelle TaskDependency verknüpft Tasks als gerichtete Kanten (von Vorgänger-Task zu Nachfolger-Task), um Ablaufreihenfolgen (z. B. "finish-to-start") im Pipeline-Graph abzubilden. Jeder Task kann zudem mehrere Artifacts erzeugen – Artefakte sind Dateien oder Ergebnisse eines Tasks (z. B. Code oder Dokumentation), verknüpft über das Feld task_id.

Feedback speichert auf Purpose-Ebene Freigaben für zentrale Artefakte (etwa PRD oder Architektur-Blueprint) inklusive Versionsstand und Status. Detailkommentare zu Artefakten werden als Chat-Verlaufseinträge mit Feedback-Intent gespeichert und sind damit direkt dem jeweiligen Artefakt zugeordnet.

🔌 4 | API-Schnittstelle

In der FastAPI-Backend-API sind folgende zentrale Endpunkte definiert. *(Hinweis: Alle unten aufgeführten Routen unter /api erfordern einen gültigen Bearer-Token im Authorization-Header, sofern nicht anders angegeben.)*

Allgemein & Authentifizierung:

  • GET / – Öffentlicher Health-Check, liefert den API-Status und (für den Demo-Tenant) das verbleibende Budget (budget_left) sowie das Gesamtbudget (budget_total).
  • POST /api/register – Neuen Tenant-Account registrieren (kein Auth-Token erforderlich). Erwartet JSON {"email": ..., "password": ..., "name": ...}; gibt bei Erfolg den neuen Tenant id und die email zurück.
  • POST /api/login – Login und Token-Erhalt (kein Auth-Token erforderlich). Erwartet Form-Daten (username, password gemäß OAuth2 Standard); gibt ein JWT als access_token (Bearer) plus token_type zurück.

Purpose-Verwaltung:

  • GET /api/purposes – Listet alle Purpose-Projekte des aktuellen Tenants als Array von Purpose-Objekten.
  • POST /api/purposes – Erstellt eine neue Purpose (Projekt). Erwartet JSON {"purpose": "<Name>", "mode": "manual"|...}. Als Folge wird initial ein *Product Requirements Document* (PRD) via LLM-Agent erzeugt und als erster Task + Artefakt gespeichert. Response liefert u. a. {"purpose_id": "...", "requirements": "<PRD-Inhalt>"}.
  • GET /api/purposes/{purpose_id}/status – Liefert Status-Infos zur angegebenen Purpose (z. B. {"paused": false, "budget_left": 123.45, "budget_total": 200.0}), inklusive Pipeline-Pause-Flag und aktuellem Budget.

Backlog & Tasks:

  • GET /api/backlog – Gibt alle offenen Tasks (Status "todo") des Tenants zurück, optional gefiltert per ?purpose_id=<ID> für einen Purpose. Response: Liste von Task-Objekten (mit Feldern wie id, description, status, purpose_id etc.).
  • POST /task – Fügt einen neuen Task manuell hinzu. Erwartet JSON (z. B. {"description": "...", "business_value": 5, ...}); der Task wird dem Tenant und optional einem Purpose (via purpose_id) zugeordnet. Response enthält den erzeugten Task (inkl. generierter id und Default-Werten).

Pipeline & Graph:

  • GET /api/graph – Liefert den vollständigen Aufgaben-Graphen des Tenants als JSON. Enthält {"tasks": [...]} (Liste aller Task-Objekte) und {"dependencies": [...]} (Kantenliste mit from_id → to_id).
  • GET /api/purposes/{purpose_id}/graph – Wie /api/graph, aber gefiltert auf einen einzelnen Purpose. Gibt nur Tasks+Dependencies dieses Projekts zurück.
  • POST /api/pause – Pausiert die Pipeline-Ausführung für den aktuellen Tenant. (Setzt ein Pause-Flag, so dass der Orchestrator keine neuen Tasks startet.) Response: {"status": "paused"}.
  • POST /api/resume – Beendet einen gesetzten Pause-Zustand und setzt die automatische Ausführung fort. Response: {"status": "resumed"}.

Artefakte & Ergebnisse:

  • GET /api/artifacts – Listet alle Artefakte des Tenants auf (optional filterbar mit ?purpose_id=<ID>). Jedes Artefakt-Objekt enthält u. a. id, zugehörige task_id+task_desc, den Speicherpfad repo_path, den MIME-Typ media_type, Zeitstempel created_at und ein released-Flag. Zudem wird eine Download-URL (/api/artifact/<id>) angegeben.
  • GET /api/artifact/{artifact_id} – Download eines Artefakts als Datei. (Gibt den Datei-Inhalt des angegebenen Artefakts zurück, z. B. Code oder Markdown.)
  • POST /api/artifacts/{artifact_id}/approve – Markiert ein Artefakt als *freigegeben*. Dadurch wird ein ggf. gesetzter Pipeline-Pausezustand für die zugehörige Purpose aufgehoben, so dass der Orchestrator weiterarbeiten kann. Response: {"status": "approved"}.
  • GET /api/artifacts/{artifact_id}/feedback – Holt alle Feedback-Einträge zu einem Artefakt (Liste mit History der Reviews). Jeder Eintrag enthält u. a. author, content (Text), version und created_at.
  • GET /api/project.zip – Stellt alle Artefakte des Tenants in einem ZIP-Archiv zum Download bereit (kompletter Projekt-Output als ZIP).

Einstellungen:

  • GET /api/settings/research – Liefert die aktuelle Einstellung, ob Agents Web-Recherchen durchführen dürfen ({"allow_web_research": true|false}).
  • POST /api/settings/research – Setzt die *Web-Research*-Einstellung für den Tenant. Erwartet JSON {"allow_web_research": true|false}; Response spiegelt den neuen Wert wider.

📈 5 | Monitoring

Das Monitoring-Stack umfasst Prometheus und Grafana. Das FastAPI-Backend stellt Metriken an /metrics bereit, und ein Celery-Exporter liefert Worker-Queue-Metriken. Prometheus (Port 9090) ist so konfiguriert, die folgenden Targets zu scrapen:

  • FastAPI Backend – Endpoint http://ai-app:8000/metrics (Uvicorn)
  • Celery Exporter – Endpoint http://celery-exporter:9808/metrics (Worker-Metriken)

Grafana (Port 3000) bietet vordefinierte Dashboards zur Visualisierung (siehe dashboards/*.json):

  • *admin_dashboard*: Task-Latenz (Histogramm) und Budget-Verlauf
  • *ai_org_overview*: Anzahl blockierter Tasks und kritische Pfadlänge

🧮 6 | LLM-Token-Budget

Für LLM-Aufgaben wird ein Pauschalpreis pro 1000 Tokens angesetzt (Default: 0,0005 USD / 1k Tokens, konfigurierbar via .env). Jeder Tenant erhält ein eigenes Budget, das als Redis-Hash (budget:{tenant}) geführt wird. Vor der Ausführung eines Tasks prüft ein Celery-"before_publish" Hook, ob das verbleibende Budget für die geplanten Tokens ausreicht – ist das Budget zu gering, wird der Task nicht ausgeführt (Status wechselt auf *budget_exceeded*).

♻️ 7 | Orchestrator Flow

  • Initialisierung neuer Projekte: Beim Anlegen einer neuen Purpose (Projekt) sorgt der Orchestrator für ein initiales Backlog. Dazu werden spezielle LLM-Agents aktiv – der *Product Owner* Agent generiert ein *Product Requirements Document* (Produktkonzept), anschließend erstellt der *Architect* einen Architektur-Blueprint und der *Planner* plant daraus initiale Tasks. Diese Tasks (inklusive z. B. "Initialize repository", "Product Requirements Document", "Architecture Blueprint") werden mit ihren Abhängigkeiten in der Datenbank angelegt. Falls beim Start des Systems ein aktiver Purpose noch keinen Backlog hat, führt seed_if_empty diesen Seed-Schritt automatisch aus.
  • Laufende Ablaufsteuerung: Der Orchestrator läuft als Hintergrund-Scheduler, der kontinuierlich alle offenen Tasks überwacht und zum richtigen Zeitpunkt ausführt. Über Graph-Abfragen (Neo4j) ermittelt er alle bereitstehenden "todo"-Tasks ohne unerledigte Vorgänger. Für jeden solchen Task wird anhand der Beschreibung ein zuständiger Rollen-Agent bestimmt (z. B. *Dev*, *QA*, *UX/UI*), entweder per festen Schlüsselworten oder via LLM-Klassifizierung (classify_role). Anschließend setzt der Orchestrator den Task auf "doing" und gibt ihn an einen Celery-Worker der entsprechenden Agentenrolle zur Ausführung. Der Agent bearbeitet die Aufgabe (z. B. Code implementieren, Test durchführen) und erstellt dabei eventuell ein Artefakt.
mermaid
Rendering diagram...
sequenceDiagram

participant U as User (Frontend)
participant API as Backend API (FastAPI)
participant ORCH as Orchestrator (Scheduler)
participant PG as PostgreSQL (Tasks DB)
participant G as Neo4j (Graph DB)
participant R as Redis (Broker & Cache)
participant W as Celery Worker (Agent)
participant LLM as LLM API (OpenAI)

Note over U,API: 1. Projektinitialisierung
U->>API: POST /api/purposes (neues Projekt)
API->>PG: Purpose speichern
API->>R: Initiales Budget setzen
API->>LLM: PRD generieren (Product Owner Agent)
API->>PG: PRD-Task + Artefakt speichern
API-->>U: PRD-Inhalt zurückgeben

Note over U,API: 2. Freigabe Anforderungen → Architektur & Planung
U->>API: POST /api/artifacts/PRD/approve
API->>LLM: Architektur-Blueprint generieren (Architect Agent)
API->>PG: Blueprint-Task + Artefakt speichern
API->>LLM: Task-Plan generieren (Planner Agent)
API->>PG: Tasks (todo) + Abhängigkeiten speichern
API->>G: Tasks in Neo4j importieren
API->>R: Pause-Flag entfernen (Projekt aktivieren)
API-->>U: "approved" Response

Note over ORCH,W: 3. Orchestrierungs-Schleife
ORCH->>G: Bereit stehende Tasks abfragen
ORCH->>PG: Task-Details laden
ORCH->>R: Budget prüfen
ORCH->>PG: Task-Status auf "doing"
ORCH->>R: Task in Celery-Queue einstellen

Note over W,LLM: 4. Agenten-Task-Ausführung
W->>LLM: Task ausführen (Dev/QA/etc.)
W->>PG: Artefakt speichern (falls vorhanden)
W->>PG: Task-Status = done/failed aktualisieren
ORCH->>G: Graph mit Status updaten

Note over U,API: 5. Monitoring & Abschluss
U->>API: GET /api/graph (Pipeline-Status)
API->>PG: Tasks abfragen
API-->>U: Graph-JSON zurückgeben
U->>API: GET /api/project.zip
API->>PG: Artefakte sammeln
API-->>U: ZIP-Download
mermaid
Rendering diagram...
flowchart TB
    U[User] -->|Start / Freigabe / Feedback| API
    API --> ORCH

    subgraph ORCH [Orchestrator]
        O1["Modus prüfen (auto/manuell)"]
        O2["PRD-Task erzeugen"]
        O3["Architect Agent"]
        O4["Planner Agent"]
        O5["Tasks einplanen"]
    end

    subgraph Agents [Celery Workers]
        PO["Product Owner"]
        AR["Architect"]
        PL["Planner"]
        DEV["Developer"]
        QA["QA"]
        UX["UX/UI"]
    end

    ORCH -->|delegieren| PO
    ORCH -->|delegieren| AR
    ORCH -->|delegieren| PL
    ORCH -->|Tasks dispatchen| DEV
    ORCH -->|Tasks dispatchen| QA
    ORCH -->|Tasks dispatchen| UX

    ORCH --> PG[(PostgreSQL)]
    ORCH --> G[(Neo4j Graph DB)]
    ORCH --> R[(Redis Budget/Queue)]

    DEV -->|Artefakte speichern| PG
    QA -->|Ergebnisse eintragen| PG
    UX -->|Design-Artefakte| PG

    ORCH -->|Updates| API
    API --> U
  • Abhängigkeits-Graph: Alle Tasks einer Purpose sind über TaskDependency-Kanten zu einem gerichteten azyklischen Graph verbunden. Der Orchestrator stellt sicher, dass kein Task ausgeführt wird, solange abhängige Vorgänger-Tasks noch nicht *done* sind. Über /api/graph bzw. /api/purposes/{id}/graph kann der aktuelle Task-Graph (Knoten: Tasks mit Status, Kanten: Abhängigkeiten) abgerufen werden.
  • Nutzer-Freigaben: Bestimmte Schlüssel-Artefakte erfordern eine manuelle Abnahme, bevor es im Pipeline-Prozess weitergeht. Zum Beispiel pausiert nach Abschluss des PRD-Tasks die Planung, bis das erzeugte PRD-Artefakt vom Nutzer geprüft und via POST /api/artifacts/{artifact_id}/approve explizit freigegeben wurde. Ist dies geschehen, startet der Orchestrator die nächste Phase: der *Architect* erstellt den *Architecture Blueprint* und der *Planner* erzeugt daraufhin die Implementierungs-Tasks. Ähnlich muss ein später erstellter *Architecture & Domain Review*-Task vom Nutzer über /reviews/{task_id}/approve genehmigt werden, bevor die finalen Schritte erfolgen. Der Orchestrator überwacht solche Freigaben (Flags wie Artifact.released bzw. Feedback-Einträge) und setzt die Pipeline fort, sobald die Zustimmung vorliegt.
  • Fehlerbehandlung & Budget: Fehlgeschlagene Tasks werden vom Orchestrator automatisch neu versucht (mit begrenzter Anzahl an Retries). Vor dem Start eines Tasks prüft das System außerdem, ob das geschätzte Token-Kontingent (tokens_plan) im verbleibenden Budget liegt – ist das Budget zu gering, wird der Task übersprungen (Status wechselt auf "budget_exceeded"). Über POST /api/pause bzw. /api/resume kann ein Administrator die Pipeline des Tenants manuell anhalten oder weiterlaufen lassen. Zudem protokolliert der Orchestrator laufend Metriken (z. B. Anzahl blockierter Tasks, kritische Pfadlänge) nach Prometheus, um den Fortschritt und Engpässe sichtbar zu machen.

💻 8 | Frontend (React)

  • AdminDashboard.tsx – React-Page mit Budget-Gauge (Prometheus-Metrik) und einer Backlog-Tabelle.
  • TaskGraph.tsx – React-Page mit dem Pipeline-Graphen (React Flow DAG); Bubble-Größe entspricht dem Business Value, Farbe signalisiert den Status.
  • *Entwicklung:* Vite-Devserver proxied /api/*-Requests an Port 8000 (FastAPI). Genutzt werden Tailwind 3.x und PNPM Workspaces.

UI-Workflow: Übersicht der Hauptbereiche im Frontend:

BereichBeschreibung
Purpose FormNeues Projektziel eingeben → löst initialen *Architect*-Seed (PRD-Erstellung) aus
Pipeline-DashboardVisualisierung des Aufgaben-Graphen (via React Flow) mit Status-Farbcodierung
ArtefactsListe aller vom System generierten Dateien zum Download

🛣 9 | Roadmap (Q3 → Q4 2025)

SprintGeplantes Feature
S-1Deep-Research-Agent (SERP + PDF Summariser)
S-2Self-Improve-Agent (PR-Generator + CI Gate)
S-3Slack/Discord Notification Hooks
S-4JWT-Auth + Stripe Billing (Multi-Tenant)
S-5Autoscaling Celery on K8s + Helm Charts
ARCHITECTURE.md

Technische Architektur

Technische Architektur, Systemgrenzen, Datenmodell, Raum-Lifecycle und Betriebsrisiken als prüfbarer Kontext.

QuelleAI-Org repository

AI-Org Prototype Architecture

Zweck dieses Dokuments

Dieses Dokument ist der technische Einstiegspunkt für die Root-Ebene des Repositories. Es fasst die aktuelle Architektur, Laufzeitkomponenten, Datenflüsse und wichtigsten Grenzen zusammen. Detail-ADRs und Phasendokumente liegen ergänzend unter docs/architecture/.

AI-Org ist ein Monorepo mit einem FastAPI/Celery-Backend, einem React/Vite-Frontend, relationalen und graphbasierten Datenmodellen, Vektorspeicher, Queueing, Monitoring und Docker-Compose-Betrieb.

Architektur auf einen Blick

mermaid
Rendering diagram...
flowchart LR
    User["User / Operator"]

    subgraph Frontend["Frontend Workspace"]
        Web["React 18 + Vite<br/>apps/web"]
        UI["Shared UI<br/>packages/ui"]
        APIClient["API Client<br/>packages/api-client"]
    end

    subgraph Backend["Backend Runtime"]
        API["FastAPI API<br/>ai_org_backend.main"]
        Intent["Intent Compiler"]
        Graph["PipelineGraph Contracts"]
        Orchestrator["Orchestrator Scheduler"]
        Celery["Celery Workers<br/>tenant:role queues"]
    end

    subgraph Data["State and Memory"]
        Postgres[("PostgreSQL<br/>SQLModel + Alembic")]
        Neo4j[("Neo4j<br/>graph projection / traversal")]
        Redis[("Redis<br/>broker, cache, budget")]
        Qdrant[("Qdrant<br/>vector memory")]
        Workspace[("workspace/<br/>artifact files")]
    end

    subgraph Observability["Observability"]
        Metrics["/metrics"]
        Prom["Prometheus"]
        Exporter["Celery Exporter"]
        Grafana["Grafana"]
        Traces["Run / Cost / Lineage contracts"]
    end

    User --> Web
    Web --> APIClient --> API
    API --> Intent
    API --> Graph
    API --> Postgres
    API --> Redis
    API --> Qdrant
    API --> Workspace
    API --> Metrics

    Orchestrator --> Postgres
    Orchestrator --> Neo4j
    Orchestrator --> Redis
    Redis --> Celery
    Celery --> Postgres
    Celery --> Qdrant
    Celery --> Workspace
    Celery --> Neo4j

    Metrics --> Prom
    Exporter --> Prom
    Prom --> Grafana
    API --> Traces
    Celery --> Traces

Systemgrenzen

BereichVerantwortungCode
APIAuth, Purpose-, Task-, Artifact-, Graph-, Chat-, Template- und Settings-Endpunktebackend/ai_org_backend/api/, backend/ai_org_backend/main.py
OrchestrierungScheduling, Task-Inspection, Routing, Watchdog, Locks und Ausführungbackend/ai_org_backend/orchestrator/
AgentenRollenbasierte Arbeitseinheiten für PRD, Architektur, Planung, Dev, QA, Reviews usw.backend/ai_org_backend/agents/
Graph ContractsPipelineGraph-v2, Validierung, Templates, Synthese, Workflow Searchbackend/ai_org_backend/graph/
IntentKompilierung und Validierung von Nutzerabsichtenbackend/ai_org_backend/intent/
PersistenzSQLModel-Modelle, Alembic-Migrationen, Repo-Helper, Storagebackend/ai_org_backend/models/, backend/ai_org_backend/alembic/, backend/ai_org_backend/services/
FrontendLogin, Dashboard, Pipeline, Graph, Reports, Templates, Chatfrontend/apps/web/
OpsDocker Compose, Prometheus, Grafana, persistent volumesops/, docker-compose.yml

Laufzeitkomponenten

KomponenteRolleStandard-Port
FastAPI ai-appREST API, WebSockets, Metrics, Runtime-Koordination8000
Celery WorkerAgentenarbeit auf tenant-spezifischen Queuesintern
OrchestratorScheduler und Graph-/Task-Ausführungintern
PostgreSQLAutoritative relationale Daten: Tenants, Purposes, Tasks, Artifacts, Graph Records5432
RedisCelery Broker, Result Backend, Budget-/Pause-/Runtime-Cache6379
Neo4jGraph-Projektion und Traversal für Dependencies/Lineage7687, UI 7474
QdrantSemantischer Kontext und Vektorspeicher6333
React/ViteAdmin- und Pipeline-Oberfläche5173 dev, Nginx im Container
PrometheusMetriken-Scraping9090
GrafanaDashboards3000

Kern-Domänenmodell

mermaid
Rendering diagram...
erDiagram
    TENANT ||--o{ PURPOSE : owns
    TENANT ||--o{ TASK : scopes
    PURPOSE ||--o{ TASK : contains
    PURPOSE ||--o{ FEEDBACK : receives
    PURPOSE ||--o{ PIPELINE_GRAPH : selects
    TASK ||--o{ ARTIFACT : produces
    TASK ||--o{ TASK_DEPENDENCY : from_task
    TASK ||--o{ TASK_DEPENDENCY : to_task
    ARTIFACT ||--o{ CHAT_MESSAGE_ARTIFACT : tagged_by
    CHAT_MESSAGE ||--o{ CHAT_MESSAGE_ARTIFACT : links
    PIPELINE_GRAPH ||--o{ PIPELINE_NODE : contains
    PIPELINE_GRAPH ||--o{ PIPELINE_EDGE : contains
    PIPELINE_GRAPH ||--o{ RUN : executed_as

    TENANT {
        string id
        string email
        string name
    }
    PURPOSE {
        string id
        string tenant_id
        string name
        string mode
        boolean is_active
    }
    TASK {
        string id
        string tenant_id
        string purpose_id
        string status
        string owner
        int tokens_plan
        int tokens_actual
        int version
    }
    ARTIFACT {
        string id
        string task_id
        string repo_path
        string media_type
        string sha256
        string status
        int version_number
    }
    PIPELINE_GRAPH {
        string id
        string template_family
        string checksum
        int version
    }

PostgreSQL ist die autoritative Persistenz für Geschäftsobjekte und Graph-v2-Records. Neo4j dient als graphoptimierte Projektion für Abhängigkeiten, Traversal und Scheduling-Sichten. Direkte, manuelle Neo4j-Mutation ist nicht das primäre Schreibmodell; Änderungen laufen über Backend-Services, Sync/Reconciliation und SQLModel-nahe Verträge.

Request- und Ausführungsfluss

mermaid
Rendering diagram...
sequenceDiagram
    actor U as User
    participant UI as React UI
    participant API as FastAPI API
    participant IC as Intent Compiler
    participant PG as PostgreSQL
    participant G as PipelineGraph
    participant R as Redis
    participant O as Orchestrator
    participant W as Celery Worker
    participant VS as Qdrant
    participant FS as workspace/

    U->>UI: Purpose anlegen oder Anfrage stellen
    UI->>API: POST /api/purposes oder /api/intent/*
    API->>IC: Absicht strukturieren und validieren
    IC-->>API: UserIntent + Constraints
    API->>PG: Purpose, Tasks, Reviews oder Graph Records speichern
    API->>G: Template matchen / Graph validieren
    API->>R: Budget, Pause-State und Queue-Kontext setzen

    O->>PG: Ausführbare Tasks / Runs lesen
    O->>R: Budget und Locks prüfen
    O->>R: Task auf tenant:role Queue legen
    R-->>W: Agent Task ausliefern
    W->>VS: Kontext suchen oder speichern
    W->>FS: Artefakt schreiben
    W->>PG: Status, Artifact, Tokens, Feedback aktualisieren
    W-->>O: Abschluss / Fehler / Retry-Signal
    UI->>API: Graph, Status, Artifacts, Reports lesen
    API-->>UI: Kontrollierbarer Projektstatus

Backend

FastAPI

backend/ai_org_backend/main.py ist der API-Einstiegspunkt. Die App installiert:

  • Request IDs,
  • Security Headers,
  • HTTP Metrics,
  • Rate Limiting,
  • Input Sanitization,
  • CORS,
  • globale Exception Handler,
  • Health- und Readiness-Probes,
  • /metrics via Prometheus ASGI App.

Wichtige Router:

  • auth: Registrierung und Login,
  • pipeline: Purposes, Backlog, Graph, Artifacts, Pause/Resume, Pipeline-Konfiguration,
  • intent: Compile, Validate, Intent Review,
  • chat: Chat, WebSocket, Artifact-Tags,
  • artifact_bridge: Artifact-Metadaten und feedbacknahe Zugriffspfade,
  • purposes: Purpose Lifecycle,
  • settings: Theme und Research-Settings,
  • templates: Template Studio.

Celery

backend/ai_org_backend/tasks/celery_app.py definiert Broker, Backend, Routing, Timeouts, Budget-Gate und Lifecycle-Signale.

Wichtige Eigenschaften:

  • Redis ist Broker und Result Backend.
  • Tasks werden dynamisch auf tenant_id:role Queues geroutet.
  • Vor dem Publish wird Budget geprüft.
  • Beim Start einer Task wird Status doing, Version und Heartbeat gesetzt.
  • Fehler schreiben failed oder verschieben nach Retry-Erschöpfung in DLQ-/Watchdog-Flows.
  • Terminale Tasks werden gegen doppelte Ausführung geschützt.

Orchestrator

Der Orchestrator ist die Scheduling-Schicht. Er liest Graph-/Task-Zustand, prüft Abhängigkeiten, Budget und Locks, aktualisiert Status und dispatcht Arbeit an Celery. Er ist bewusst getrennt von der HTTP-Schicht, damit API-Zugriffe, Scheduler und Worker unabhängig skalierbar bleiben.

Agenten

Agenten sind Celery Tasks mit rollenbezogener Verantwortung. Beispiele:

  • agent.po: PRD und Produktanforderungen,
  • agent.architect: Architektur-Blueprint,
  • agent.planner: Entwicklungsplan und Tasks,
  • agent.dev: Implementierungsartefakte,
  • agent.qa, agent.integration, agent.security, agent.performance: Qualitätssicherung,
  • agent.reviewer: Review-Artefakte,
  • agent.vision: Vision-Dokumente,
  • graph.sync und graph.reconcile: Graph-Synchronisation.

Intent, Graph und Templates

AI-Org trennt Nutzerabsicht, Workflow-Vertrag und Runtime-Ausführung.

mermaid
Rendering diagram...
flowchart TB
    Prompt["Raw user request"]
    Intent["UserIntent<br/>domain, action, deliverable, target, risk"]
    Gate{"Clarification<br/>needed?"}
    Template["Template Matcher"]
    Synth["Bounded Synthesizer"]
    Graph["PipelineGraph<br/>nodes, edges, schemas, budgets"]
    Validate["Graph Validator"]
    Runtime["Legacy/Celery Engine Adapter"]

    Prompt --> Intent --> Gate
    Gate -- yes --> Review["Intent Review / Clarification"]
    Gate -- no --> Template
    Template -- confident match --> Graph
    Template -- no match --> Synth --> Graph
    Graph --> Validate --> Runtime

Der aktuelle Stand ist additiv:

  • Legacy-Pipeline und bestehende Celery Tasks bleiben ausführbar.
  • PipelineGraph-v2 definiert den Zielvertrag für neue Workflows.
  • Template-Familien liegen unter backend/ai_org_backend/graph/templates/*.yaml.
  • Capability-Kataloge liegen unter backend/ai_org_backend/graph/capability_catalog/*.yaml.
  • Validierung verhindert tote Knoten, inkompatible Datenkanten, ungebundene Zyklen und High-Risk-Ausführung ohne Approval.

Frontend

Das Frontend ist ein pnpm-Workspace unter frontend/.

PackageAufgabe
apps/webReact-App mit Routen für Login, Dashboard, Pipeline, Graph, Templates, Reports, Insights und Profil
packages/uiGemeinsame UI-Komponenten
packages/api-clientFetch-/API-Helfer und Auth-Header-Handling

Die App nutzt:

  • React 18,
  • Vite 5,
  • Tailwind,
  • React Router,
  • Zustand,
  • React Flow,
  • Mermaid-Rendering für Markdown,
  • Monaco Editor für Template-/Textarbeit.

Private Routen prüfen den JWT aus localStorage. API-Aufrufe laufen in der Entwicklung über den Vite-Proxy auf /api; im Containerbetrieb übernimmt Nginx/Compose die Kopplung.

Datenhaltung und Artefakte

PostgreSQL

PostgreSQL hält die transaktionale Wahrheit:

  • Tenants und Auth-Kontext,
  • Purposes,
  • Tasks und Dependencies,
  • Artifacts,
  • Feedback und Chat Messages,
  • Pipeline Templates und Phase-Konfiguration,
  • PipelineGraph-v2 Records,
  • Runs,
  • Audit-/Review-/Statusdaten.

Migrationen liegen unter backend/ai_org_backend/alembic/versions/.

Neo4j

Neo4j optimiert Graphabfragen. Es spiegelt Task- und Artifact-Beziehungen für Traversal, Statussicht, Scheduling und Reconciliation. Die Datenquelle für fachliche Persistenz bleibt PostgreSQL.

Qdrant

Qdrant speichert semantische Vektoren für Kontextsuche, Memory und relevante Snippets. Services wie vector_store.py, memory.py und kontextnahe Agenten verwenden diese Schicht.

Redis

Redis ist:

  • Celery Broker,
  • Celery Result Backend,
  • Budget-/Pause-/Runtime-Cache,
  • Heartbeat- und Watchdog-Hilfsspeicher.

workspace/

Dateibasierte Artefakte werden unter workspace/ abgelegt und in PostgreSQL mit Pfad, MIME-Type, Größe, SHA-256, Version und Status referenziert.

Rework, Review und Invalidation

Rework ist kein freier Loop. Die Architektur verlangt begrenzte Revisionen:

  • max_revisions,
  • cost_budget,
  • convergence_predicate.

Artefakte können fresh, stale, invalidated oder archived sein. Downstream-Invalidation soll dafür sorgen, dass Änderungen nicht nur lokal gespeichert werden, sondern betroffene Folgeartefakte sichtbar veraltet werden.

Observability

Die Observability-Schicht umfasst zwei Ebenen:

  1. Betrieb: Prometheus-Metriken aus FastAPI und Celery Exporter, Grafana-Dashboards, Health-/Readiness-Probes.
  2. Ausführung: Run-Traces, Cost Records und OpenLineage-artige Events als adapterfähige Verträge unter backend/ai_org_backend/observability/.

Ziel ist, KI-Arbeit wie einen Produktionsprozess zu betreiben: Status, Kosten, Fehler, Durchlaufzeit und Lineage müssen sichtbar sein.

Security und Governance

Aktuelle Schutzschichten:

  • JWT-basierte Authentifizierung,
  • Tenant-Scoping über API-Dependencies und Modelle,
  • Rate Limiting,
  • Security Headers,
  • Input Sanitization,
  • CORS-Konfiguration,
  • Budget-Gates vor Task-Publish,
  • Approval Gates für risikoreiche Graph-Knoten,
  • Audit- und Review-Modelle.

Für produktiven Mehrmandantenbetrieb bleiben Secrets Management, Rollen-/Rechtekonzept, Datenisolation, Backups, Audit-Export und Policy Enforcement explizite Ausbaupunkte.

Deployment und lokale Entwicklung

Docker Compose

Der persistente lokale Stack liegt in ops/persistent.yml:

bash
docker compose --env-file .env -f ops/persistent.yml up -d

Optionale Profile und Overlays können Frontend oder Monitoring aktivieren. Ports können lokal durch zusätzliche Compose-Override-Dateien angepasst werden, wenn Standardports belegt sind.

Lokales Backend

bash
pip install -e backend/.[dev]
uvicorn ai_org_backend.main:app --reload --port 9102

Lokales Frontend

bash
cd frontend
corepack pnpm install
corepack pnpm dev

Das Frontend erwartet in der Entwicklung standardmäßig einen /api-Proxy zum Backend.

Quality Gates

GateBefehl
Backend Lintmake lint
Backend Typesmake typecheck
Backend Testsmake test
Fünf-Schichten-Test-Harnessmake test-all
Architektur-Auditmake audit
Graph-/Template-Validierungmake graph-validate
Frontend Buildcd frontend && corepack pnpm --filter web build

CI-Workflows liegen unter .github/workflows/ und nutzen Node 20 mit pnpm 10.13.1 für den Frontend-Workspace.

Architekturprinzipien

  1. Postgres für Wahrheit, Graph für Struktur

Fachliche Zustände sind relational nachvollziehbar. Graphprojektionen dienen Traversal, Planung und Visualisierung.

  1. Runtime ist asynchron

LLM- und Agentenarbeit läuft nicht im Request-Thread, sondern über Queues, Worker, Heartbeats und Statusupdates.

  1. Graph Contracts sind stabiler als Rollennamen

Rollen bleiben wichtig, aber die langfristige Workflow-Semantik liegt in typisierten Knoten, Kanten und Capabilities.

  1. Jede Autonomie braucht Grenzen

Budget, Timeout, Retry, Approval, Revision Limits und Validation sind Teil des Ausführungsvertrags.

  1. Artefakte sind prüfbare Outputs

Antworten ohne persistierten Output gelten nicht als belastbare Lieferung.

  1. Beobachtbarkeit ist kein Add-on

Health, Metrics, Cost, Lineage und Audit müssen mitwachsen, wenn Agenten autonomer werden.

Bekannte Grenzen

  • PipelineGraph-v2 ist als Contract Layer vorhanden, aber Legacy-Tasks und Adapter sind weiterhin Teil der Runtime.
  • Einige Rework- und Review-Flows sind historisch gewachsen und werden schrittweise in zentrale Services konsolidiert.
  • Neo4j-Sync und Reconciliation sind operativ wichtig, aber nicht die alleinige Quelle der fachlichen Wahrheit.
  • Produktionsreife Mandantenisolation, RBAC, Secrets und Billing sind noch Ausbaupunkte.
  • Externe LLM-Provider und Research-Integrationen brauchen konsequente URL-, Kosten- und Datenkontrollen.

Weiterführende Dokumente

  • VISION.md - Produktvision und Leitprinzipien.
  • README.md - Setup, Features und API-Überblick.
  • README_local__setup.md - lokales Docker-Setup.
  • READMEpipeline.md - Pipeline- und Agentenabläufe.
  • docs/architecture/00-glossary.md - Begriffe.
  • docs/architecture/01-intent-compiler.md - Intent-Compiler.
  • docs/architecture/02-pipeline-graph.md - PipelineGraph-v2.
  • docs/architecture/03-templates.md - Template-Familien.
  • docs/architecture/04-rework-invalidation.md - Rework und Invalidation.
  • docs/architecture/05-observability.md - Tracing, Cost und Lineage.
  • docs/architecture/06-test-harness.md - Test-Harness.
VISION.md

Vision und Produktdoktrin

Vision, Mediation-OS-These, Zielgruppen, Grenzen und strategische Produktlinie.

QuelleAI-Org repository

AI-Org Prototype Vision

Kurzfassung

AI-Org ist ein autonomes, graphgesteuertes Agenten-System, das aus einem menschlichen Ziel ein prüfbares Projekt macht: Anforderungen, Architektur, Arbeitsplan, Implementierungsartefakte, Reviews, Reports und Auslieferungspakete entstehen in einem kontrollierten Ablauf mit Budgetgrenzen, Traceability und menschlichen Freigabepunkten.

Das Produktversprechen ist nicht "ein Chatbot schreibt Code", sondern: eine nachvollziehbare KI-Organisation plant und liefert Arbeitsergebnisse so, dass Menschen sie steuern, prüfen und freigeben können.

mermaid
Rendering diagram...
flowchart LR
    A["Purpose<br/>Was soll erreicht werden?"]
    B["Intent<br/>Was ist gemeint?"]
    C["Graph<br/>Welche Arbeitsschritte sind nötig?"]
    D["Agents<br/>Wer erledigt welchen Schritt?"]
    E["Artifacts<br/>Was wurde erzeugt?"]
    F["Review<br/>Ist es gut genug?"]
    G["Delivery<br/>Was wird ausgeliefert?"]

    A --> B --> C --> D --> E --> F --> G
    F -- "Feedback / Rework" --> C

Problem

LLM-basierte Arbeit ist heute oft schnell, aber schwer kontrollierbar. Einzelne Prompts liefern punktuelle Ergebnisse, doch komplexe Projekte brauchen mehr:

  • belastbare Zielklärung,
  • explizite Abhängigkeiten,
  • wiederholbare Workflows,
  • Kosten- und Budgetkontrolle,
  • nachvollziehbare Artefakt-Versionen,
  • Review- und Freigabeprozesse,
  • Monitoring für Laufzeit, Qualität und Fehler.

AI-Org adressiert diese Lücke, indem es KI-Arbeit nicht als Gespräch, sondern als operatives System aus Rollen, Graphen, Queues, Artefakten und Reviews modelliert.

Mission

AI-Org soll Organisationen ermöglichen, wissensintensive Arbeit mit KI-Agenten auszuführen, ohne Kontrolle, Nachvollziehbarkeit und Verantwortlichkeit zu verlieren.

Das System übersetzt menschliche Absichten in strukturierte Workflows und macht jeden Schritt beobachtbar:

  • Warum wurde eine Aufgabe erzeugt?
  • Welcher Agent oder welche Capability ist verantwortlich?
  • Welche Inputs und Artefakte wurden verwendet?
  • Welche Kosten und Risiken sind entstanden?
  • Welche Freigabe oder welches Feedback ist noch offen?

Zielnutzer

NutzergruppeBedarfAI-Org liefert
Gründer und ProduktverantwortlicheAus Ideen belastbare Projektartefakte erzeugenPurpose-, PRD-, Architektur- und Planungsflows
Engineering LeadsKI-Arbeit steuerbar in technische Prozesse einbettenGraphen, Aufgaben, Reviews, Artefakt-Lineage
Consultants und AnalystenWiederholbare Research- und Report-WorkflowsTemplate-Familien, Quellenkontext, Reports
Solo-BuilderSchneller von Ziel zu lauffähigem Ergebnis kommenPipeline UI, Agentenrollen, ZIP-/Artefakt-Ausgabe
BetreiberKosten, Stabilität und Qualität überwachenBudget-Gates, Metrics, Run-/Cost-Traces

Produktprinzipien

  1. Purpose vor Prompt

Jede Ausführung beginnt mit einem fachlichen Ziel, nicht mit einer isolierten Chat-Nachricht.

  1. Graph vor Magie

Komplexe Arbeit wird als expliziter Graph aus Knoten, Kanten, Bedingungen, Budgets und Freigaben modelliert.

  1. Artefakte vor Antworten

Wert entsteht durch persistierte, versionierte Ergebnisse: Dokumente, Code, Reports, Reviews, Konfigurationen und Archive.

  1. Menschliche Kontrolle bleibt Teil der Architektur

Kritische Schritte brauchen Approval Nodes, Review Gates oder manuelle Freigaben. Auto-Modus ist ein Betriebsmodus, kein Kontrollverlust.

  1. Kosten sind ein First-Class Constraint

Tokenbudgets, Budget-Gates und Cost-Traces sind nicht nachgelagert, sondern steuern Scheduling und Risiko.

  1. Traceability ist Produktqualität

Ergebnisse müssen erklärbar sein: von Purpose über Intent und Graph bis zu Task, Agent, Artefakt und Review.

  1. Templates schlagen Improvisation

Wiederholbare Arbeitsformen werden als deklarative Template-Familien gepflegt. Freie Synthese bleibt begrenzt und validiert.

Produktpfeiler

1. Purpose Workspace

Ein Purpose ist der Arbeitskontext eines Projekts. Er bündelt Ziel, Modus, Pipeline, Tasks, Chat, Artefakte, Feedback und Status. Der Workspace soll die zentrale Oberfläche sein, in der Menschen die KI-Organisation steuern.

2. Intent Compiler

Freitext wird in strukturierte Absichten übersetzt: Domain, Aktion, Deliverable, Zielartefakte, Risiken, Constraints und Konfidenz. Unsichere oder riskante Absichten werden nicht blind ausgeführt, sondern in Review- oder Clarification-Flows überführt.

3. PipelineGraph

Der PipelineGraph beschreibt die Arbeit als ausführbaren Vertrag: Knoten, Kanten, Schemas, Retry-Policy, Timeouts, Human Approval, Revision Limits und Budgets. Legacy-Tasks bleiben ausführbar, aber neue Workflows orientieren sich am Graph-Vertrag.

4. Agentenorganisation

Agenten sind Rollen und Capabilities mit klarer Verantwortung: Product Owner, Architect, Planner, Developer, QA, UX/UI, Reviewer, Security, Performance, Integration, Research und weitere spezialisierte Worker.

5. Artifact System

Artefakte sind die eigentlichen Ergebnisse. Sie werden persistiert, versioniert, mit Feedback verknüpft und für Download, Review, Rework und Lineage genutzt.

6. Observability und Governance

Metriken, Run-Traces, Cost Records, Lineage Events, Audit Logs, Health Checks und Dashboards machen das System betreibbar. Ziel ist, KI-Arbeit wie einen Produktionsprozess zu beobachten.

North-Star Outcomes

AI-Org ist erfolgreich, wenn es die folgenden Ergebnisse zuverlässig erzeugt:

  • Ein Nutzer kann aus einem Purpose eine nachvollziehbare Pipeline starten.
  • Das System erzeugt PRD, Architektur, Plan und Lieferartefakte mit Review-Status.
  • Jede Aufgabe ist einem Tenant, Purpose, Agenten, Status und Budgetkontext zugeordnet.
  • Artefakte sind versioniert, auffindbar, kommentierbar und exportierbar.
  • Rework-Schleifen sind begrenzt, budgetiert und nachvollziehbar.
  • Fehlerzustände bleiben sichtbar und wiederaufnehmbar statt still zu verschwinden.

Qualitätsmaßstab

Ein Ergebnis gilt erst als gut, wenn es:

  • fachlich zum Purpose passt,
  • auf nachvollziehbaren Inputs basiert,
  • im Graph korrekt eingeordnet ist,
  • Kosten- und Risikogrenzen respektiert,
  • als Artefakt gespeichert ist,
  • Review- oder Freigabestatus besitzt,
  • bei Änderungen downstream invalidiert oder aktualisiert werden kann.

Betriebsmodi

ModusBedeutungEinsatz
ManualDas System pausiert an wichtigen Freigabepunkten.Produkt-, Architektur- und Kundenarbeit
AutoDas System läuft nach initialem Ziel möglichst selbständig weiter.Demos, interne Workflows, risikoarme Aufgaben
Review/ReworkBestehende Artefakte werden gezielt überarbeitet.Qualitätsverbesserung, Feedbackzyklen
Research/AnalysisQuellen, Kontext und Synthesen stehen im Vordergrund.Briefings, Reports, Wissensarbeit

Roadmap-Leitbild

Jetzt

  • Stabiler End-to-End-Prototyp für Purpose -> PRD -> Architektur -> Plan -> Tasks -> Artefakte.
  • Mandantenfähigkeit, Auth, Budget-Gates, Monitoring und Docker-Compose-Betrieb.
  • React Admin UI mit Pipeline-, Graph-, Reports-, Template- und Chat-Flows.
  • Additive Architekturphasen für Intent, Graph Contracts, Templates, Rework, Observability und Test Harness.

Als Nächstes

  • Graph-v2 stärker als Runtime-Quelle etablieren.
  • Intent Review und PipelineGraph-Auswahl in der UI enger zusammenführen.
  • Artefakt-Lineage und Invalidation vollständig in Nutzerflows sichtbar machen.
  • Replay-, Evaluation- und Cost-Dashboards produktnäher ausbauen.
  • Template-Bibliothek mit mehr Domänen und besseren Acceptance-Kriterien erweitern.

Später

  • Mehrmandantenfähiger Betrieb mit klaren Isolation-, Billing- und Admin-Konzepten.
  • Capability Marketplace für interne und externe Agentenfähigkeiten.
  • Produktionsreife Governance: Rollen/Rechte, Audit, Policy Enforcement, Secrets, Compliance.
  • Integrationen in GitHub, Dokumentensysteme, Kalender, Ticketsysteme und Deployment-Pipelines.

Nicht-Ziele

AI-Org soll nicht:

  • unkontrolliert beliebige Arbeit im Hintergrund ausführen,
  • menschliche Verantwortung verschleiern,
  • Ergebnisse ohne Artefakt-, Kosten- oder Review-Kontext als erledigt deklarieren,
  • ein reiner Chat-Wrapper sein,
  • eine monolithische "Alleskönner"-Agentenrolle aufbauen,
  • unbegrenzte Rework- oder Suchschleifen erlauben.

Design-Ton

Das Produkt soll sich wie ein operatives Kontrollzentrum für KI-Arbeit anfühlen: ruhig, präzise, nachvollziehbar, dicht genug für echte Arbeit und klar genug für schnelle Entscheidungen. Die UI dient nicht der Inszenierung der KI, sondern der Steuerung des Arbeitsprozesses.

Leitentscheidung

AI-Org priorisiert kontrollierte Autonomie. Das System darf Arbeit selbständig ausführen, aber nur innerhalb expliziter Verträge: Purpose, Intent, Graph, Budget, Approval, Trace und Artefakt.

AUDIT.md

Contributors Audit Card

Contributors-Audit-Karte mit Lead Ask, Reifegrad, Risiken, Roadmap und Contribution-Slots.

Quellegenerierter Fallback

AI-Org Prototype 2.0

Hinweis: Dieses Dokument ist ein deploybarer Fallback aus dem Contributors-Projektprofil. Sobald eine Projektquelle README, Vision oder Architektur liefert, wird sie hier bevorzugt gerendert.

Audit Snapshot

AI-Org experimentiert mit einer Delivery-Pipeline, in der Agenten vorschlagen und Menschen die bindenden Gates halten.

Reifegrad

  • Vorhanden: 9-Phasen-Plan, Agenten-Idee, Human-in-the-loop-Doktrin und starke Kopplung an Contributors.
  • Fehlt: Eingegrenzte Pilot-Domäne, State-Modell, Eval-Plan, Demo-Hosting und UI-Narrativ.

Lead Ask

Multi-Agent-Architektur-Mentor: Architekt/in für Multi-Agent-, Graph- oder Orchestrierungs-Systeme, der den 9-Phasen-Plan auf Scope, State, Eval und Human Gates reduziert.