10. System Architecture

Glitchpad uses ports and adapters. The shared shell and renderer registry depend on value contracts. Rust document services implement native source, detection, metadata, save, and recovery ports. Desktop and Android adapters implement platform acquisition and persistence. Renderers cannot import host adapters or invoke arbitrary Tauri APIs.

flowchart TB
  desktop["Desktop acquisition adapters"] --> host["Tauri host and scoped commands"]
  android["Kotlin Android document bridge"] --> host
  host --> core["Rust document core"]
  core --> source["Source handles and revisions"]
  core --> detection["Detection and text profiles"]
  core --> metadata["Metadata normalization"]
  core --> persistence["Save and recovery"]
  source --> session["TypeScript session service"]
  detection --> session
  metadata --> session
  persistence --> session
  session --> shell["React shell and compact tabs"]
  session --> registry["Renderer registry"]
  registry --> markdown["Markdown renderer"]
  registry --> text["Text and source renderer"]
  registry --> image["Image renderer"]
  registry --> pdf["PDF renderer"]
  registry --> office["DOCX and ODT renderers"]

Dependency rulesCopy Anchor Link

• glitchpad-core MUST NOT depend on Tauri, React, WebView, or platform UI packages.
• Renderer modules MAY depend on shared TypeScript contracts and renderer-specific workers; they MUST NOT depend on Tauri invocation or native plugin packages.
• The host MAY depend on glitchpad-core and Tauri plugins approved through capability files.
• Android Kotlin code MUST expose the same source operations and error classes as desktop adapters.
• The shell MUST obtain commands from renderer capabilities and MUST NOT branch on file extensions.
• Renderer modularity is internal architecture and does not create a public plugin contract.

Open flowCopy Anchor Link

flowchart TB
  request["Dialog, drop, association, command line, or Android intent"] --> acquire["Host acquires scoped source handle"]
  acquire --> identity{"Existing stable identity?"}
  identity -->|Yes| focus["Focus existing tab"]
  identity -->|No| evidence["Read bounded identification evidence"]
  evidence --> detect["Detect format and text profile"]
  detect --> select{"Safe renderer registered?"}
  select -->|No| unsupported["Show unsupported or malformed result"]
  select -->|Yes| open["Open renderer with bounded byte provider"]
  open --> content["Publish first content and capabilities"]
  content --> enrich["Continue metadata and navigation work asynchronously"]