Nova3D — Architecture & Control Flow

flowchart TD
  User(("User"))
  FlutterApp["Flutter Web App\napp.nova3d.xyz"]
  MCPServer["MCP Server\nnova3d-mcp"]
  BlenderPlugin["Blender Plugin"]
  Backend["Nova3D Backend\nGraphFlow v2\nnova3d.xyz/api"]
  BlenderEngine["Server-side Blender\nexecutes generated Python"]
  LLM["LLM Provider\nGemini · Claude · GPT"]
  GLBStore["Artifact Storage\nGLB + code + joints"]

  User -->|"chat prompt"| FlutterApp
  User -->|"tool call"| MCPServer
  User -->|"panel UI"| BlenderPlugin

  FlutterApp -->|"REST /run/state"| Backend
  MCPServer -->|"REST /run/state"| Backend
  BlenderPlugin -->|"REST /run/state"| Backend

  Backend --> LLM
  LLM -->|"Blender Python script"| Backend
  Backend --> BlenderEngine
  BlenderEngine -->|"GLB file"| GLBStore
  GLBStore -->|"glb_url"| Backend
  Backend -->|"result"| FlutterApp
  Backend -->|"result"| MCPServer
  Backend -->|"result"| BlenderPlugin
          

stateDiagram-v2
  [*] --> Unauthenticated
  Unauthenticated --> PendingLogin : nova3d_login called
  PendingLogin --> Authenticated : browser callback received + code exchanged
  PendingLogin --> Unauthenticated : timeout or state mismatch
  Authenticated --> ReadyToGenerate : credits funded
  Authenticated --> NeedsCredits : credits empty
  NeedsCredits --> ReadyToGenerate : user purchases credits
  ReadyToGenerate --> Unauthenticated : token expired / nova3d_logout
          

flowchart TD
  Call["generate_3d(prompt, model, image?)"]
  Gate{"credits ready?\nGET /mcp/status"}
  Fail1["return {failed: true}"]
  Conv["POST /conversations\nget conversation_id"]
  Submit["POST /run/state/sketch_to_3d_v2\n{prompt, code_llm_tier, return_nodes, conversation_id}"]
  Poll{"GET /status/{workflow_id}\nevery 3s"}
  Progress["report_progress(node)"]
  Budget{"budget_exhausted?"}
  FetchResult["GET /result/{workflow_id}"]
  Parse["GenerationResult.from_api()\nextract glb_url · parts · code_artifact"]
  History["persist conversation history\nPATCH snapshot + POST messages + POST workflow-links"]
  EmbedMeta["embed _nova3d_conversation_id\ninto code_artifact"]
  Return["return {\n  glb_url, parts, code_artifact,\n  conversation_url, workflow_id\n}"]
  Fail2["return {failed: true, error_message}"]

  Call --> Gate
  Gate -->|"no"| Fail1
  Gate -->|"yes"| Conv
  Conv --> Submit
  Submit --> Poll
  Poll -->|"running"| Progress
  Progress --> Poll
  Poll -->|"budget_exhausted"| Budget
  Budget --> Fail2
  Poll -->|"terminal"| FetchResult
  FetchResult --> Parse
  Parse -->|"failed"| Fail2
  Parse -->|"success"| EmbedMeta
  EmbedMeta --> History
  History --> Return
          

flowchart TD
  Start(["workflow start"])

  subgraph Image["Image path (optional)"]
    caption_prompt["caption_prompt"]
    caption_llm["caption_llm\nunderstand image"]
  end

  generation_prompt["generation_prompt\nbuild LLM prompt"]
  code_generation_llm["code_generation_llm\nLLM writes Blender Python"]
  run_blender["run_blender\nexecute script → GLB"]
  repair_llm["repair_llm\nLLM fixes broken script"]

  subgraph Validation["Validation pass"]
    capture_validation_screenshots["capture screenshots"]
    validation_prompt["validation_prompt"]
    validation_llm["validation_llm\nreview model"]
    validation_correction_blender["apply corrections"]
  end

  T1(["final_validated_correction ✓"])
  T2(["final_latest_valid ✓"])
  T3(["fail_generation ✗"])

  Start -->|"has image"| caption_prompt
  caption_prompt --> caption_llm
  caption_llm --> generation_prompt
  Start -->|"text only"| generation_prompt
  generation_prompt --> code_generation_llm
  code_generation_llm --> run_blender
  run_blender -->|"script error"| repair_llm
  repair_llm --> run_blender
  run_blender -->|"all retries fail"| T3
  run_blender -->|"GLB produced"| capture_validation_screenshots
  capture_validation_screenshots --> validation_prompt
  validation_prompt --> validation_llm
  validation_llm -->|"pass"| T1
  validation_llm -->|"minor fix"| validation_correction_blender
  validation_correction_blender --> T1
  validation_llm -->|"best effort"| T2
          

flowchart TD
  EditCall["edit tool call\n(code_artifact, description)"]
  ExtractConv["extract _nova3d_conversation_id\nfrom code_artifact"]
  Submit["POST /run/state/{workflow}\n{code_artifact, description, llm, provider}"]
  Poll{"GET /status/{workflow_id}\nevery 3s"}
  FetchResult["GET /result/{workflow_id}"]
  UpdateArtifact["embed conversation_id\nback into new code_artifact"]
  PersistEdit["POST /conversations/{id}/messages\nPOST /conversations/{id}/workflow-links"]
  Return["return {\n  glb_url, parts,\n  updated_code_artifact,\n  conversation_url\n}"]

  EditCall --> ExtractConv
  ExtractConv --> Submit
  Submit --> Poll
  Poll -->|"running"| Poll
  Poll -->|"terminal"| FetchResult
  FetchResult --> UpdateArtifact
  UpdateArtifact --> PersistEdit
  PersistEdit --> Return
          

flowchart LR
  Gen["generate_3d\nsucceeds"]
  Conv["POST /conversations\n{title, source: mcp}"]
  Snapshot["PATCH /conversations/{id}\n{conversation_metadata: {nova3d_chat_snapshot}}"]
  AppendUser["POST /conversations/{id}/messages\nuser message (prompt text)"]
  AppendAsst["POST /conversations/{id}/messages\nassistant message (model_url, code_artifact, joints)"]
  LinkWF["POST /conversations/{id}/workflow-links\n{workflow_id, message_id, relation_type}"]
  WebApp["web app /chat/{id}\nshows full generation history"]

  Gen --> Conv
  Conv --> Snapshot
  Snapshot --> AppendUser
  AppendUser --> AppendAsst
  AppendAsst --> LinkWF
  LinkWF --> WebApp
          

flowchart TD
  Panel["Blender 3D View Panel\nnova3d_prompt, model selector"]
  Operator["NOVA3D_OT_generate\n(main thread invoke)"]
  EncodeImages["encode reference images\nbpy → base64 data URLs"]
  Params["GenerationParams\n(immutable, assembled on main thread)"]
  Thread["GenerationJob.start()\ndaemon thread"]
  Timer["wm.event_timer_add(0.25s)\nstart modal"]

  subgraph Background ["Background thread (GenerationJob)"]
    Readiness["GET /readiness\ncheck service up"]
    Credits["GET /balance\ncheck credit budget"]
    Session["POST /conversations\ncreate session"]
    Submit["POST /run/state/sketch_to_3d_v2\nstart workflow"]
    PollBG{"GET /status/{id}\nevery poll interval"}
    FetchBG["GET /result/{id}"]
    Download["download GLB + code.py\nto project folder"]
    WriteMeta["write meta.json\n(durable project record)"]
    QueueDone["queue.put('done', {glb_path, code_text})"]
    UVMaps["generate UV maps\n(separate workflow loop)"]
    QueueFinished["queue.put('finished')"]
  end

  subgraph MainThread ["Main thread (modal tick every 0.25s)"]
    DrainQueue["drain queue\n(queue.get_nowait)"]
    ImportGLB["bpy: import GLB\ncreate text datablock"]
    RefreshUI["tag_redraw\nupdate status line"]
    Teardown["remove timer\nwm.nova3d_running = False"]
  end

  Panel -->|"nova3d.generate"| Operator
  Operator --> EncodeImages
  EncodeImages --> Params
  Params --> Thread
  Params --> Timer
  Thread --> Readiness
  Readiness --> Credits
  Credits --> Session
  Session --> Submit
  Submit --> PollBG
  PollBG -->|"queue.put('status')"| DrainQueue
  PollBG --> PollBG
  PollBG -->|"terminal"| FetchBG
  FetchBG --> Download
  Download --> WriteMeta
  WriteMeta --> QueueDone
  QueueDone -->|"'done' event"| ImportGLB
  ImportGLB --> UVMaps
  UVMaps --> QueueFinished
  QueueFinished --> Teardown
  Timer --> DrainQueue
  DrainQueue --> RefreshUI
          

flowchart TD
  ChatInput["User types prompt\nor attaches image"]
  GenerationDraft["GenerationDraftsNotifier\nstore request keyed by conversationId"]
  Navigate["navigate to /chat/{conversationId}"]
  Seed["MessagesNotifier.seed()\noptimistic placeholder message"]
  SendGen["sendGeneration(request)"]
  CreditCheck["ensurePaidCreditBudget\nGET estimate + GET wallet"]
  StartWF["CadService.startGeneration()\nPOST /run/state/sketch_to_3d_v2"]
  RunWorkflow["runWorkflow(workflowId)\npolls GET /status every few seconds"]
  Upsert["_upsert(message)\nupdate state + persist local cache"]
  Sync["persistMessagesSnapshot\nPATCH /conversations/{id}"]
  FinalMsg["final message with modelUrl\nstops isStreaming"]
  Viewer["3D viewer renders GLB\nuvMaps.js applies UV atlases"]

  ChatInput --> GenerationDraft
  GenerationDraft --> Navigate
  Navigate --> Seed
  Seed --> SendGen
  SendGen --> CreditCheck
  CreditCheck -->|"insufficient"| FinalMsg
  CreditCheck -->|"ok"| StartWF
  StartWF --> RunWorkflow
  RunWorkflow -->|"status update"| Upsert
  Upsert --> Sync
  RunWorkflow -->|"completed"| FinalMsg
  FinalMsg --> Viewer