🏗️ DeepSeek Reasonix — Architecture Analysis

flowchart TB
  subgraph "User Interface"
    CLI["CLI Entry\nsrc/cli/index.ts"]
    TUI["Ink TUI\nsrc/cli/ui/App.tsx\n(~1984 LOC)"]
    DASH["Dashboard SPA\nReact + Express\nport :3100"]
  end

  subgraph "Core Engine"
    LOOP["CacheFirstLoop\nsrc/loop.ts\n(1052 LOC)"]
    CM["ContextManager\nsrc/context-manager.ts\n(345 LOC)"]
    REPAIR["ToolCallRepair\nsrc/repair/"]
    PROMPT["Prompt Builder\nsrc/code/prompt.ts\n+ prompt-fragments.ts"]
  end

  subgraph "Tool System"
    TOOLS["ToolRegistry\nsrc/tools.ts"]
    FS["Filesystem\nread/write/edit/search"]
    SHELL["Shell\nrun_command + jobs"]
    SUB["Subagents\nspawn_subagent"]
    MCP_BRIDGE["MCP Bridge\nstdio + SSE"]
    WEB["Web\nsearch + fetch"]
  end

  subgraph "Infrastructure"
    CLIENT["DeepSeek Client\nsrc/client.ts\nfetch + SSE streaming"]
    SESSION["Session Store\nJSONL persistence"]
    MEMORY["Memory Store\nUser / Project / Runtime"]
    TOKENIZER["DeepSeek V3 Tokenizer\nPorted from Python"]
  end

  CLI --> TUI
  TUI --> LOOP
  LOOP --> CM
  LOOP --> REPAIR
  LOOP --> PROMPT
  LOOP --> TOOLS
  TOOLS --> FS
  TOOLS --> SHELL
  TOOLS --> SUB
  TOOLS --> MCP_BRIDGE
  TOOLS --> WEB
  LOOP --> CLIENT
  LOOP --> SESSION
  LOOP --> MEMORY
  LOOP --> TOKENIZER
  DASH --> LOOP

flowchart TB
  subgraph "Layer 1: Shared Fragments"
    TUI["TUI_FORMATTING_RULES\n• Table formatting\n• Code blocks\n• No ASCII art"]
    NEG["NEGATIVE_CLAIM_RULE\n• Cite or shut up\n• search_content FIRST"]
    ESC["escalationContract(modelId)\n• ESCALATION_CONTRACT\n• <<<NEEDS_PRO>>> marker"]
  end

  subgraph "Layer 2: Identity + Rules"
    ID["Identity Block\n• You are Reasonix Code\n• Don't infer from workspace"]
    CITE["Citation Rules\n• File paths with line ranges\n• Broken paths = red strikethrough"]
    AUDIT["Audit Rails (6 rules)\n• Auto-preview limits\n• Flag→consumer trace\n• No fabricated %"]
  end

  subgraph "Layer 3: Tool Guidance"
    PICK["Tool Selection\n• submit_plan vs ask_choice\n• todo_write"]
    PLAN_MODE["Plan Mode\n• Bounced writes\n• submit_plan required"]
    SUBAGENT["Subagent Delegation\n• Default: don't delegate\n• Skill index with tags"]
  end

  subgraph "Layer 4: Edit Protocol"
    EDIT["SEARCH/REPLACE Format\n• Read before edit enforced\n• Exact whitespace match\n• Edit gate routes review/auto"]
    WHEN["When to Edit\n• Only on explicit change ask\n• Analyze → tools + prose"]
  end

  subgraph "Layer 5: Memory Stack"
    UM["User Memory\n~/.reasonix/memory/"]
    PM["Project Memory\nREASONIX.md"]
    SM["Skill Memos\n@reasonix/core-utils"]
  end

  subgraph "Output"
    FINAL["CODE_SYSTEM_PROMPT\nBuilt per-session by\ncodeSystemBase(modelId)\nwith real model name"]
  end

  TUI --> ID
  NEG --> CITE
  ESC --> PICK
  ID --> PICK
  CITE --> AUDIT
  AUDIT --> PLAN_MODE
  PICK --> SUBAGENT
  PLAN_MODE --> EDIT
  SUBAGENT --> WHEN
  EDIT --> FINAL
  WHEN --> FINAL
  UM --> FINAL
  PM --> FINAL
  SM --> FINAL

flowchart TB
  START(["User submits prompt"])
  
  subgraph "Turn Setup"
    RESET["resetStorm()\nFresh intent = clean slate"]
    LOAD["loadSessionMessages()\nRestore from JSONL"]
    HEAL["healLoadedMessages()\nFix tool call pairing"]
    CHECK["Budget check\nRefuse if over cap"]
  end
  
  subgraph "Iteration Loop"
    BUILD["Build messages:\nprefix + log + scratch"]
    STREAM["streamModelResponse()\nSSE from DeepSeek API"]
    THINK["Strip/retain reasoning\nthinking mode handling"]
    REPAIR["ToolCallRepair.process()\nscavenge→truncation→storm"]
  end
  
  subgraph "Dispatch Phase"
    DISPATCH["dispatchToolCallsChunked()\nParallel-safe chunking"]
    RUN["runOne(call)\nToolRegistry.dispatch()"]
    APPEND["appendAndPersist(msg)\nLog + session JSONL"]
  end
  
  subgraph "Post-Turn"
    COMPACT["decideAfterUsage()\nFold if ratio > 75%"]
    BUDGET["updateBudget()\nWarn at 80%, stop at 100%"]
  end

  START --> RESET --> LOAD --> HEAL --> CHECK
  CHECK --> BUILD --> STREAM --> THINK --> REPAIR
  REPAIR -->|has tool calls| DISPATCH
  REPAIR -->|no tool calls| COMPACT
  DISPATCH --> RUN --> APPEND
  APPEND -->|more iter cycles| BUILD
  APPEND -->|turn done| COMPACT
  COMPACT -->|fold| HEAL
  COMPACT -->|carry on| DONE(["Await next user input"])
  COMPACT -->|exit summary| FORCE(["forceSummaryAfterIterLimit()"])

flowchart TB
  CALLS["Repaired Tool Calls\n(repairedCalls[])"]
  
  subgraph "Chunking Logic (dispatchToolCallsChunked)"
    CHECK{"REASONIX_TOOL_DISPATCH\n=== 'serial'?"}
    SERIAL["Serial Mode\nOne call per chunk"]
    GROUP["Group parallel-safe calls\nup to REASONIX_PARALLEL_MAX (default 3)\nStop at first non-parallel-safe"]
    BARRIER["Serial Barrier\nNon-parallel-safe call\nruns alone"]
  end
  
  subgraph "Execution"
    RACE["Promise.allSettled()\nRace chunk in parallel"]
    ORDER["Yield results\nin DECLARED ORDER\n(not completion order)"]
    APPEND["Append tool messages\nto AppendOnlyLog"]
  end

  CALLS --> CHECK
  CHECK -->|yes| SERIAL
  CHECK -->|no| GROUP
  GROUP --> BARRIER
  SERIAL --> RACE
  BARRIER --> RACE
  RACE --> ORDER --> APPEND
  APPEND -->|more calls| CHECK
  APPEND -->|done| NEXT(["Return to agent loop"])

flowchart TB
  USAGE["After turn response\nUsage.promptTokens"]

  subgraph "Threshold Decision (decideAfterUsage)"
    FST{"> 80%?\nFORCE_SUMMARY_THRESHOLD"}
    AGGR{"> 78%?\nHISTORY_FOLD_AGGRESSIVE"}
    NORM{"> 75%?\nHISTORY_FOLD_THRESHOLD"}
    PRE{"> 90% at turn start?\nTURN_START_FOLD_THRESHOLD"}
  end

  subgraph "Fold Execution"
    PINS["Extract pinned skills\n(collectPinnedSkills)"]
    SUMMARIZE["Summarize head messages\nv4-flash + effort=high\n15s timeout"]
    REWRITE["rewriteSession()\nReplace head with summary\n+ pinned skill bodies\n+ recent tail"]
  end

  FST -->|yes| EXIT(["Exit with summary\nforceSummaryAfterIterLimit()"])
  FST -->|no| AGGR
  AGGR -->|yes| AGG_FOLD(["Aggressive fold\ntailBudget = 10% ctxMax"])
  AGGR -->|no| NORM
  NORM -->|yes| NORM_FOLD(["Normal fold\ntailBudget = 20% ctxMax"])
  NORM -->|no| CARRY(["Carry on"])
  PRE -->|yes| PRE_FOLD(["Pre-iter fold\nbefore turn starts"])

  AGG_FOLD --> PINS
  NORM_FOLD --> PINS
  PRE_FOLD --> PINS
  PINS --> SUMMARIZE --> REWRITE

flowchart TB
  subgraph "Transport Layer"
    STDIO["StdioTransport\nSubprocess spawn\nJSON-RPC over stdin/stdout"]
    SSE["SseTransport\nHTTP GET /sse event stream\nPOST for client→server"]
    STREAM_HTTP["StreamableHttpTransport\nStreaming HTTP with\nupgrade path"]
  end

  subgraph "Client"
    CONNECT["McpClient.connect()\nHandshake + initialize"]
    TOOLS["listTools()\n→ ToolSpec[] registered\nin ToolRegistry"]
    CALL["callTool(name, args)\n→ result string\ncapped at maxResultTokens"]
  end

  subgraph "Registry"
    CATALOG["catalog.ts\nMCP server directory"]
    MARKETPLACE["marketplace-overlay/\nCurated server list\nwith i18n (zh-CN.json)"]
    SPEC["spec.ts\nMCP schema validation"]
  end

  STDIO --> CONNECT
  SSE --> CONNECT
  STREAM_HTTP --> CONNECT
  CONNECT --> TOOLS --> CALL
  CATALOG --> MARKETPLACE
  SPEC --> CONNECT