ThothII/docs/architecture/thothii-runtime.architecture.json

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "ThothII Runtime Architecture",
    "locale": "en",
    "output": "thothii-runtime.html",
    "quality_profile": "showcase",
    "viewBox": [1360, 800]
  },
  "components": [
    {
      "id": "reviewer",
      "type": "external",
      "label": "User / Reviewer",
      "sublabel": "Browser",
      "pos": [20, 300],
      "size": [145, 72]
    },
    {
      "id": "frontend",
      "type": "frontend",
      "label": "Frontend",
      "sublabel": "React 18 + Vite",
      "tag": "in-memory transcript",
      "pos": [205, 295],
      "size": [165, 82]
    },
    {
      "id": "backend",
      "type": "backend",
      "label": "Backend",
      "sublabel": "Fastify + TypeScript",
      "tag": "session bridge",
      "pos": [410, 295],
      "size": [175, 82]
    },
    {
      "id": "pi",
      "type": "backend",
      "label": "Pi",
      "sublabel": "RPC process per session",
      "tag": "inside core",
      "pos": [625, 295],
      "size": [170, 82]
    },
    {
      "id": "harness",
      "type": "backend",
      "label": "tht / Harness",
      "sublabel": "8-phase NL→SQL workflow",
      "tag": "workflow owner",
      "pos": [835, 295],
      "size": [190, 82]
    },
    {
      "id": "workspace",
      "type": "database",
      "label": "Workspace Repository",
      "sublabel": "sessions + phase artifacts",
      "tag": "source of truth",
      "pos": [1065, 295],
      "size": [205, 82]
    },
    {
      "id": "auth",
      "type": "security",
      "label": "Authentication",
      "sublabel": "local registry or OIDC",
      "pos": [410, 70],
      "size": [170, 76]
    },
    {
      "id": "modelProvider",
      "type": "external",
      "label": "AI Model Provider",
      "sublabel": "installation-selected APIs",
      "pos": [615, 70],
      "size": [190, 76]
    },
    {
      "id": "catalog",
      "type": "database",
      "label": "Metadata Catalog",
      "sublabel": "PostgreSQL + Kysely",
      "tag": "backend-owned",
      "pos": [410, 545],
      "size": [180, 82]
    },
    {
      "id": "embedding",
      "type": "backend",
      "label": "Embedding Service",
      "sublabel": "Ollama",
      "pos": [800, 545],
      "size": [170, 76]
    },
    {
      "id": "qdrant",
      "type": "database",
      "label": "Vector Store",
      "sublabel": "Qdrant",
      "pos": [1010, 545],
      "size": [160, 76]
    },
    {
      "id": "dwh",
      "type": "external",
      "label": "Data Warehouse",
      "sublabel": "external, read-only",
      "pos": [1070, 70],
      "size": [180, 82]
    }
  ],
  "boundaries": [
    {
      "kind": "region",
      "label": "Local Docker Compose runtime",
      "wraps": ["frontend", "backend", "pi", "harness", "catalog", "embedding", "qdrant"],
      "pad": 26
    },
    {
      "kind": "security-group",
      "label": "core container",
      "wraps": ["pi", "harness"],
      "pad": 18
    },
    {
      "kind": "security-group",
      "label": "operator-controlled persisted state",
      "wraps": ["workspace"],
      "pad": 18
    }
  ],
  "connections": [
    {
      "id": "reviewerInput",
      "from": "reviewer",
      "to": "frontend",
      "label": "question / gate decision",
      "variant": "emphasis",
      "labelAt": [185, 391]
    },
    {
      "id": "restRequests",
      "from": "frontend",
      "to": "backend",
      "label": "REST",
      "variant": "emphasis"
    },
    {
      "id": "sseEvents",
      "from": "backend",
      "to": "frontend",
      "label": "SSE: text · info · widget",
      "variant": "dashed",
      "labelAt": [390, 415]
    },
    {
      "id": "piRpc",
      "from": "backend",
      "to": "pi",
      "label": "JSON-RPC stdio",
      "variant": "emphasis",
      "labelAt": [605, 391]
    },
    {
      "id": "gateCommands",
      "from": "pi",
      "to": "harness",
      "label": "phase / gate commands",
      "variant": "emphasis",
      "labelAt": [815, 391]
    },
    {
      "id": "persistArtifacts",
      "from": "harness",
      "to": "workspace",
      "label": "artifacts + decision ledger",
      "variant": "emphasis",
      "labelAt": [1045, 391]
    },
    {
      "id": "authenticate",
      "from": "auth",
      "to": "backend",
      "label": "local session / OIDC callback",
      "variant": "security",
      "fromSide": "bottom",
      "toSide": "top"
    },
    {
      "id": "sessionModel",
      "from": "pi",
      "to": "modelProvider",
      "label": "session model API",
      "fromSide": "top",
      "toSide": "bottom",
      "labelAt": [755, 185]
    },
    {
      "id": "catalogState",
      "from": "backend",
      "to": "catalog",
      "label": "catalog CRUD + runs",
      "fromSide": "bottom",
      "toSide": "top"
    },
    {
      "id": "metadataModel",
      "from": "backend",
      "to": "modelProvider",
      "label": "short-lived LiteLLM calls",
      "variant": "dashed"
    },
    {
      "id": "readOnlySql",
      "from": "harness",
      "to": "dwh",
      "label": "introspection + read-only SQL"
    },
    {
      "id": "embedRequests",
      "from": "harness",
      "to": "embedding",
      "label": "embedding requests",
      "fromSide": "bottom",
      "toSide": "top",
      "labelAt": [830, 490]
    },
    {
      "id": "vectorAccess",
      "from": "harness",
      "to": "qdrant",
      "label": "index + vector retrieval",
      "fromSide": "bottom",
      "toSide": "top",
      "labelAt": [1165, 475]
    }
  ],
  "cards": [
    {
      "dot": "cyan",
      "title": "Primary session path",
      "items": [
        "The browser sends questions and reviewer decisions over REST; the backend returns text, information, and widget descriptors over SSE.",
        "One Pi RPC process drives each active session and delegates deterministic phase operations to tht / Harness."
      ]
    },
    {
      "dot": "emerald",
      "title": "State ownership",
      "items": [
        "Harness owns the eight-phase workflow and persists session_manifest.yaml, phase artifacts, and review_decisions.jsonl.",
        "Backend owns the separate installation-local metadata catalog; the live frontend transcript is not persisted."
      ]
    },
    {
      "dot": "rose",
      "title": "Trust boundaries",
      "items": [
        "Catalog DB, Qdrant, and Ollama stay inside Compose; workspace state is operator controlled and mounted into core.",
        "The DWH and AI provider remain external endpoints; DWH access is constrained to introspection, tests, bounded samples, and read-only SQL."
      ]
    }
  ]
}