Architektur

Nano Banana ist ein Nx-Monorepo mit fünf Packages und zwei Cloud-Run-Services.

Repo-Aufbau

packages/
├── server/         # Genkit Backend (Web-API + Cloud Tasks Stage Handlers)
├── mcp-server/     # Remote MCP Server (OAuth 2.1 + Streamable HTTP)
├── pipeline-core/  # Shared lib: Firestore-Client, Cloud Tasks Enqueue, GCS,
│                   # PipelineDocument State Machine, subscribeToPipeline,
│                   # startGeneration / startArchitect
├── frontend/       # React + Vite + MUI Web-Client
├── color-edit/     # Python HSL Color-Replacement-Tool (Subprocess-Stage)
└── docs/           # Docusaurus Doku-Site (diese Site)

skills/
└── nano-banana/    # Claude Skill, der das MCP für AI-Clients wrappt

Pipeline-Stages

• Architect (optional, getriggert durch propose_concepts oder die Ideation-Phase der Web-UI): produziert 3–5 stilistisch kohärente Concept Proposals aus einer groben User-Idee. Jeder Proposal trägt einen refined Prompt + Keywords.
• Prompt Engineer (optional, läuft wenn kein Concept übergeben wird): schreibt einen rohen Prompt gegen den Corporate Style Guide um, damit das Diffusion-Modell brand-aware Sprache bekommt. Die Web-UI überspringt das normalerweise (der Architect hat schon refined). Der MCP-One-Shot generate_image lässt den Stage laufen. Siehe Brand Styling.
• Generate Image: ruft Gemini / Imagen mit dem (refined) Prompt + Reference Icons + optionalem Sketch auf. Schreibt das Intermediate Image in GCS.
• Enhance Image (optional): Post-Processing für Schärfe / ästhetisches Uplift.
• Color Adjust: Python-Subprocess (packages/color-edit/color_tool.py) ersetzt Brand Colors via HSL mit Luminanz-Erhaltung.

Jeder Stage ist ein eigenständiger HTTP-Handler auf nano-server. Die Stages hängen über drei Cloud Tasks Queues zusammen (text-generation, image-generation, processing) mit unterschiedlichen Concurrency- und Rate-Limit-Profilen.

Cloud-Run-Services

Service	Rolle	Public URL
nano-server	Web-API + Cloud Tasks Stage Handlers	https://nano-server-bc5eqn62ka-ez.a.run.app
nano-mcp-server	Remote MCP Server (4 Tools, OAuth 2.1)	https://mcp.nano.cpl.ai (Cloud-Run-Domain-Mapping)

Beide Services teilen sich @nano/pipeline-core und schreiben in dieselbe Firestore-pipelines-Collection. Der mcp-server enqueued Cloud Tasks, die auf die /tasks/*-Handler von nano-server zielen — es gibt immer nur ein Set an Stage-Implementierungen.

Firestore State Machine

Jede Generation legt ein pipelines/<uuid>-Dokument an:

{
  id: string;
  userId: string;
  status: 'pending' | 'running' | 'completed' | 'failed';
  stageOrder: string[];                     // deterministische Iterations-Reihenfolge
  stages: Record<string, {
    status: 'pending' | 'queued' | 'running' | 'completed' | 'failed';
    startedAt?, completedAt?, error?, result?: unknown;
  }>;
  input: { prompt, aspectRatio, enhance, ... };
  results?: Array<{ image, image_uri, thumbnail }>;
  createdAt, updatedAt;
}

• Das Frontend subscribed via onSnapshot auf das Dokument für Live-Progress.
• Der mcp-server subscribed server-seitig per subscribeToPipeline(id, cb) und pusht MCP-progress-Notifications an den verbundenen Claude-Client. Der Client redet nie direkt mit Firestore.
• Die markStage*- und markPipeline*-Helper (in pipeline-core/state.ts) sind die Single Source of Truth für State-Transitions.

Data Storage

Was	Wo
Pipeline-State	Firestore (default) DB, pipelines Collection
Reference Icons	Firestore icons Collection (Vector RAG)
Conversation History	Firestore conversations, history
User Settings	Firestore users/<uid>/settings
Generierte Bilder	GCS-Bucket cpl-gen-ai-marketing-images
OAuth-State (MCP)	Firestore oauth_* + mcp_jwks Collections