// docs/architecture/context-pipeline.sruja
// Context engineering architecture for the current Sruja implementation

person = kind "Person"
system = kind "System"
container = kind "Container"
component = kind "Component"

overview {
  summary "Sruja context engineering pipeline"
  audience "Developers using Sruja with AI coding assistants"
  scope "Reviewed repo truth, scanned evidence, task-scoped context, and editor workflows"
}

Developer = person "Developer" {
  description "Uses Sruja to keep architecture truth in sync with code and AI-assisted changes"
}

AICodingAssistants = system "AI Coding Assistants" {
  description "External assistants that consume Sruja context during coding and review"

  Cursor = container "Cursor / VS Code AI" {
    technology "Editor extension"
    description "Editor-native assistant that consumes markdown context and focused diagrams"
  }

  Copilot = container "GitHub Copilot" {
    technology "Editor extension"
    description "Editor-native assistant that consumes copied context packs and markdown summaries"
  }

  ChatGPT = container "ChatGPT" {
    technology "Web or API"
    description "General-purpose assistant that can consume exported markdown or JSON context"
  }

  Claude = container "Claude" {
    technology "Web or API"
    description "General-purpose assistant that can consume exported markdown or JSON context"
  }
}

DeveloperWorkspace = system "Developer Workspace" {
  description "Repository where architecture truth, docs, and code evolve together"

  Repo = container "Repository" {
    technology "Multi-language codebase"
    description "Working tree that contains code, repo.sruja, docs, skills, and generated context artifacts"
  }
}

ContextEngineering = system "Sruja Context Engineering" {
  description "Runtime and editor workflow that turns repo truth plus code evidence into usable AI context"

  RepoTruth = container "Repo Truth" {
    technology "Sruja DSL, repo.sruja"
    description "Reviewed architecture truth committed with the repository"

    BaselineModel = component "Baseline Model" {
      description "Reviewed Sruja model used as the truth source for drift and review"
    }

    KnowledgeLinks = component "Knowledge Links" {
      description "Element-linked docs, ADR references, and knowledge files opened from the editor"
    }
  }

  EvidencePipeline = container "Evidence Pipeline" {
    technology "Rust, crates/sruja-scan + crates/sruja-graph"
    description "Scans source code and manifests to build evidence for context engineering"

    RepositoryScanner = component "Repository Scanner" {
      description "Discovers components, dependencies, and structural signals from code and manifests"
    }

    RepoMap = component "Repo Map" {
      description "Builds concise repository summaries for discovery prompts and AI workflows"
    }

    DependencyGraph = component "Dependency Graph" {
      description "Produces graph data used for drift, impact, and task-scoped context slicing"
    }
  }

  Analysis = container "Analysis and Drift" {
    technology "Rust, crates/sruja-diff + crates/sruja-intent"
    description "Compares reviewed truth, scanned evidence, and intent artifacts"

    DriftEngine = component "Drift Engine" {
      description "Computes reviewed, drifted, or unknown truth status from code evidence and repo truth"
    }

    IntentComparer = component "Intent Comparer" {
      description "Cross-checks ADRs and other intent artifacts against the declared architecture"
    }

    ImpactAnalyzer = component "Impact Analyzer" {
      description "Computes blast radius and change risk for a target component or boundary"
    }
  }

  ContextArtifacts = container "Context Artifacts" {
    technology "JSON, .sruja/context.json, repo.bundle.json, system.index.json"
    description "Caches context locally and publishes it for multi-repo retrieval"

    RepoContextCache = component "Repo Context Cache" {
      description "Stores fresh evidence, truth status, and baseline metadata in .sruja/context.json"
    }

    RepoBundle = component "Repo Bundle" {
      description "Publishes baseline truth and evidence to repo.bundle.json for federation"
    }

    SystemIndex = component "System Index" {
      description "Composes repo bundles into a federated system-wide index for cross-repo retrieval"
    }
  }

  CLI = container "CLI Commands" {
    technology "Rust, crates/sruja-cli"
    description "Commands that refresh evidence, review drift, export context, critique changes, and publish federation artifacts"

    SyncCommand = component "Sync Command" {
      description "Runs sruja sync -r . to refresh evidence and write .sruja/context.json"
    }

    StatusCommand = component "Status Command" {
      description "Runs sruja status -r . to report baseline, truth status, and context freshness"
    }

    ReviewCommand = component "Review Command" {
      description "Runs sruja review -r . to summarize drift and suggest repo.sruja updates"
    }

    ContextExportCommand = component "Context Export Command" {
      description "Runs sruja ai-context -r . to export task-scoped architecture context for AI tools"
    }

    PublishCommand = component "Publish Command" {
      description "Runs sruja publish -r . -o repo.bundle.json for federation"
    }

    ComposeCommand = component "Compose Command" {
      description "Runs sruja compose -i <input> -o system.index.json for federated retrieval"
    }

    FocusCommand = component "Focus Command" {
      description "Runs sruja focus --file <path> to generate task-scoped briefing with blast radius and AI instructions"
    }

    CritiqueCommand = component "Critique Command" {
      description "Runs sruja critique to perform adversarial architectural review of proposed/changed files"
    }

    ProposeCommand = component "Propose Command" {
      description "Runs sruja propose create/list/approve for architectural change proposal lifecycle"
    }

    ContextScoreCommand = component "Context Score Command" {
      description "Runs sruja context-score -r . to compute AI-readiness score (0-100) across 5 dimensions"
    }

    IngestCommand = component "Ingest Command" {
      description "Runs sruja ingest <path> to import external context (ADRs, design docs) into .sruja/context/"
    }

    ComplianceCommand = component "Compliance Command" {
      description "Runs sruja compliance -r . to check structural drift + intent + policy violations"
    }
  }

  AgentMemory = container "Agentic Memory" {
    technology "Rust, crates/sruja-agent"
    description "Persistent learning and guardrails for AI agents"

    AgentMemoryStore = component "Agent Memory Store" {
      description "Learning entries persisted at .sruja/agent_memory.json with guardrail advice for future agents"
    }
  }

  Extension = container "VS Code Extension" {
    technology "TypeScript, extension/, WASM"
    description "Editor experience that exposes Sruja context engineering inside VS Code-compatible editors"

    CliBridge = component "CLI Bridge" {
      description "Invokes sync, status, review, and drift commands from editor commands"
    }

    ContextPackBuilder = component "Context Pack Builder" {
      description "Builds a copyable context pack from open files, diagnostics, skills, and cached repo context"
    }

    DocsThread = component "Docs Thread" {
      description "Shows linked docs and references for the currently selected architecture element"
    }
  }

  AIOutputs = container "AI Context Outputs" {
    technology "Markdown, JSON, Mermaid"
    description "Formats architecture context into outputs that AI tools and humans can consume quickly"

    MarkdownContext = component "Markdown Context" {
      description "Prompt-ready markdown for AI chats, review threads, and copied context packs"
    }

    JsonContext = component "JSON Context" {
      description "Structured machine-readable context for tools, automation, and integrations"
    }

    FocusedDiagrams = component "Focused Diagrams" {
      description "Mermaid slices and sequence views derived from the reviewed architecture"
    }
  }
}

ContextEngineering.RepoTruth -> ContextEngineering.Analysis "Provides reviewed truth"
ContextEngineering.EvidencePipeline -> ContextEngineering.Analysis "Provides fresh evidence"
ContextEngineering.Analysis -> ContextEngineering.ContextArtifacts "Writes truth state"
ContextEngineering.ContextArtifacts -> ContextEngineering.AIOutputs "Provides cached and federated context"
ContextEngineering.Extension -> ContextEngineering.CLI "Invokes repo commands"
ContextEngineering.CLI -> ContextEngineering.AIOutputs "Exports task-scoped context"
ContextEngineering.AIOutputs -> AICodingAssistants "Delivers architecture context"
ContextEngineering -> DeveloperWorkspace "Writes repo context artifacts and editor outputs"

ContextEngineering.RepoTruth.BaselineModel -> ContextEngineering.Analysis.DriftEngine "Defines reviewed architecture"
ContextEngineering.RepoTruth.KnowledgeLinks -> ContextEngineering.Extension.DocsThread "Provides linked docs"

ContextEngineering.EvidencePipeline.RepositoryScanner -> ContextEngineering.EvidencePipeline.RepoMap "Summarizes repository"
ContextEngineering.EvidencePipeline.RepositoryScanner -> ContextEngineering.EvidencePipeline.DependencyGraph "Builds dependency graph"
ContextEngineering.EvidencePipeline.DependencyGraph -> ContextEngineering.Analysis.DriftEngine "Provides fresh evidence"
ContextEngineering.EvidencePipeline.DependencyGraph -> ContextEngineering.Analysis.ImpactAnalyzer "Provides change graph"
ContextEngineering.EvidencePipeline.RepoMap -> ContextEngineering.CLI.ContextExportCommand "Provides concise repo summary"

ContextEngineering.Analysis.DriftEngine -> ContextEngineering.ContextArtifacts.RepoContextCache "Updates truth status"
ContextEngineering.CLI.SyncCommand -> ContextEngineering.EvidencePipeline.RepositoryScanner "Refreshes evidence"
ContextEngineering.CLI.SyncCommand -> ContextEngineering.Analysis.DriftEngine "Recomputes truth status"
ContextEngineering.CLI.SyncCommand -> ContextEngineering.ContextArtifacts.RepoContextCache "Writes cache"
ContextEngineering.CLI.StatusCommand -> ContextEngineering.ContextArtifacts.RepoContextCache "Reads cache"
ContextEngineering.CLI.ReviewCommand -> ContextEngineering.ContextArtifacts.RepoContextCache "Reads cached evidence"
ContextEngineering.CLI.ReviewCommand -> ContextEngineering.Analysis.DriftEngine "Summarizes drift"
ContextEngineering.CLI.ReviewCommand -> ContextEngineering.Analysis.IntentComparer "Checks declared intent"
ContextEngineering.CLI.ContextExportCommand -> ContextEngineering.RepoTruth.BaselineModel "Reads reviewed DSL"
ContextEngineering.CLI.ContextExportCommand -> ContextEngineering.EvidencePipeline.DependencyGraph "Slices impacted area"
ContextEngineering.CLI.ContextExportCommand -> ContextEngineering.Analysis.ImpactAnalyzer "Requests blast radius"
ContextEngineering.CLI.ContextExportCommand -> ContextEngineering.AIOutputs.MarkdownContext "Formats markdown"
ContextEngineering.CLI.ContextExportCommand -> ContextEngineering.AIOutputs.JsonContext "Formats json"
ContextEngineering.CLI.PublishCommand -> ContextEngineering.ContextArtifacts.RepoBundle "Writes bundle"
ContextEngineering.CLI.ComposeCommand -> ContextEngineering.ContextArtifacts.SystemIndex "Builds system index"
ContextEngineering.CLI.FocusCommand -> ContextEngineering.RepoTruth.BaselineModel "Reads reviewed DSL"
ContextEngineering.CLI.FocusCommand -> ContextEngineering.EvidencePipeline.DependencyGraph "Traverses blast radius"
ContextEngineering.CLI.FocusCommand -> ContextEngineering.Analysis.ImpactAnalyzer "Requests impact"
ContextEngineering.CLI.CritiqueCommand -> ContextEngineering.Analysis.IntentComparer "Adversarial review"
ContextEngineering.CLI.CritiqueCommand -> ContextEngineering.Analysis.DriftEngine "Compares changes"
ContextEngineering.CLI.ProposeCommand -> ContextEngineering.RepoTruth.BaselineModel "Modifies DSL"
ContextEngineering.CLI.ProposeCommand -> ContextEngineering.Analysis.DriftEngine "Validates proposals"
ContextEngineering.CLI.ContextScoreCommand -> ContextEngineering.ContextArtifacts.RepoContextCache "Reads evidence"
ContextEngineering.CLI.IngestCommand -> ContextEngineering.RepoTruth.KnowledgeLinks "Imports external docs"
ContextEngineering.CLI.ComplianceCommand -> ContextEngineering.Analysis.DriftEngine "Checks structural drift"
ContextEngineering.CLI.ComplianceCommand -> ContextEngineering.Analysis.IntentComparer "Checks intent alignment"
ContextEngineering.AgentMemory.AgentMemoryStore -> ContextEngineering.CLI.FocusCommand "Provides guardrail advice"
ContextEngineering.CLI.ReviewCommand -> ContextEngineering.AgentMemory.AgentMemoryStore "Records learnings"
ContextEngineering.AgentMemory -> ContextEngineering.CLI "Persists agent learning"

ContextEngineering.ContextArtifacts.RepoContextCache -> ContextEngineering.ContextArtifacts.RepoBundle "Supplies repo context"
ContextEngineering.RepoTruth.BaselineModel -> ContextEngineering.ContextArtifacts.RepoBundle "Supplies reviewed truth"
ContextEngineering.ContextArtifacts.RepoBundle -> ContextEngineering.ContextArtifacts.SystemIndex "Feeds federation"
ContextEngineering.CLI.ContextExportCommand -> ContextEngineering.ContextArtifacts.SystemIndex "Reads federated slice when present"

ContextEngineering.Extension.CliBridge -> ContextEngineering.CLI.SyncCommand "Invokes"
ContextEngineering.Extension.CliBridge -> ContextEngineering.CLI.StatusCommand "Invokes"
ContextEngineering.Extension.CliBridge -> ContextEngineering.CLI.ReviewCommand "Invokes"
ContextEngineering.Extension.ContextPackBuilder -> ContextEngineering.RepoTruth.BaselineModel "Reads active .sruja truth"
ContextEngineering.Extension.ContextPackBuilder -> ContextEngineering.ContextArtifacts.RepoContextCache "Reads cached repo context"
ContextEngineering.Extension.ContextPackBuilder -> ContextEngineering.AIOutputs.MarkdownContext "Packages editor context"
ContextEngineering.Extension.DocsThread -> ContextEngineering.AIOutputs.FocusedDiagrams "Opens focused views"

ContextEngineering.AIOutputs.MarkdownContext -> AICodingAssistants.Cursor "Provides prompt-ready context"
ContextEngineering.AIOutputs.MarkdownContext -> AICodingAssistants.Copilot "Provides prompt-ready context"
ContextEngineering.AIOutputs.JsonContext -> AICodingAssistants.ChatGPT "Provides structured context"
ContextEngineering.AIOutputs.JsonContext -> AICodingAssistants.Claude "Provides structured context"
ContextEngineering.AIOutputs.FocusedDiagrams -> AICodingAssistants.Cursor "Provides visual architecture slice"

Developer -> DeveloperWorkspace.Repo "Edits code and architecture"
Developer -> ContextEngineering.CLI.SyncCommand "Runs"
Developer -> ContextEngineering.CLI.ContextExportCommand "Runs"
Developer -> ContextEngineering.CLI.PublishCommand "Runs for federation"
Developer -> ContextEngineering.CLI.ComposeCommand "Runs for federation"
Developer -> ContextEngineering.CLI.FocusCommand "Runs for task briefing"
Developer -> ContextEngineering.CLI.CritiqueCommand "Runs before commit"
Developer -> ContextEngineering.CLI.ContextScoreCommand "Runs to check AI-readiness"
Developer -> ContextEngineering.Extension.CliBridge "Uses in editor"
Developer -> ContextEngineering.Extension.ContextPackBuilder "Copies context for AI"
Developer -> ContextEngineering.Extension.DocsThread "Browses references"
Developer -> AICodingAssistants.Cursor "Requests architecture-aware changes"
Developer -> AICodingAssistants.Copilot "Requests architecture-aware changes"
AICodingAssistants.Cursor -> DeveloperWorkspace.Repo "Suggests code and doc edits"
AICodingAssistants.Copilot -> DeveloperWorkspace.Repo "Suggests code and doc edits"

view index {
  title "Context Engineering Overview"
  include *
}

view editor {
  title "Editor and AI Workflow"
  include "Developer ContextEngineering.Extension ContextEngineering.CLI ContextEngineering.AIOutputs ContextEngineering.AgentMemory AICodingAssistants DeveloperWorkspace"
}
