// docs/architecture/sruja-platform.sruja
// Complete architecture of the Sruja platform
// This file describes the Sruja platform architecture using Sruja DSL
//
// Note: This file is written as a comprehensive blueprint and is intended to be
// validated with `sruja lint`.

import { * } from 'sruja.ai/stdlib'

// Actors
Architect = person "Software Architect" {
  description "Uses Sruja to design and document systems"
  doc "book/src/docs/concepts/person.md"
}

Developer = person "Developer" {
  description "Uses Sruja CLI and VS Code extension for development"
  doc "book/src/docs/concepts/person.md"
}

Contributor = person "Contributor" {
  description "Contributes to Sruja development"
  doc "book/src/docs/concepts/person.md"
}

GitHub = system "GitHub" {
  description "Source control, issues, pull requests, and releases"
  tags ["external"]
}

GitHubActions = system "GitHub Actions" {
  description "CI/CD workflows for building, testing, and releasing artifacts"
  tags ["external", "ci"]
}

CratesIo = system "crates.io" {
  description "Rust package registry for publishing and installing the Sruja CLI crate"
  tags ["external", "registry"]
}

VSCodeMarketplace = system "VS Code Marketplace" {
  description "Distribution channel for installing and updating the VS Code extension"
  tags ["external", "distribution"]
}

OpenVSX = system "Open VSX Registry" {
  description "Alternative distribution channel for VS Code-compatible extensions"
  tags ["external", "distribution"]
}

SrujaWebsite = system "sruja.ai" {
  description "Public website for documentation and installation entry points"
  tags ["external", "docs"]
}

// Main System with nested containers and components
Sruja = system "Sruja Platform" {
  description "Context engineering platform that helps AI-assisted teams generate, validate, and maintain architecture as code from repo evidence"
  tags ["platform", "architecture-as-code"]
  doc "skills/sruja-architecture/references/REFERENCE.md"

  CLI = container "Sruja CLI" {
    technology "Rust, clap"
    description "Command-line interface for Sruja operations"
    tags ["cli", "backend"]

    CommandSurface = component "Command Surface" {
      description "User-facing command interface for orchestrating scan, drift, export, critique, and proposal workflows"
      technology "Rust, crates/sruja-cli"
    }

    WorkflowSteps = component "Workflow Steps" {
      description "Flow-bearing command steps (sync, drift, focus/context export, critique, propose) that cross core boundaries"
      technology "Rust, crates/sruja-cli"
    }
  }

  Diagnostics = container "Diagnostics" {
    technology "Rust, crates/sruja-diagnostics"
    description "Diagnostic codes, spans, and JSON/text formatting"
    tags ["core"]
  }

  Language = container "Language Engine" {
    technology "Rust"
    description "DSL parsing, AST, and language processing"
    tags ["core", "parser"]

    Lexer = component "Lexer" {
      description "Tokenizes Sruja DSL input"
      technology "Rust, crates/sruja-language"
    }

    Parser = component "Parser" {
      description "Parses tokens into Abstract Syntax Tree"
      technology "Rust, crates/sruja-language"
    }

    AST = component "AST Builder" {
      description "Builds and manages Abstract Syntax Tree"
      technology "Rust, crates/sruja-language"
    }

    Printer = component "Printer" {
      description "Formats and prints AST back to DSL"
      technology "Rust, crates/sruja-language"
    }
  }

  Engine = container "Validation Engine" {
    technology "Rust"
    description "Validates architecture models against rules"
    tags ["validation", "rules"]

    Validator = component "Validator" {
      description "Orchestrates validation rules execution"
      technology "Rust, crates/sruja-engine"
    }

    Scorer = component "Scorer" {
      description "Calculates architecture health scores"
      technology "Rust, crates/sruja-engine"
    }

    Rules = component "Validation Rules" {
      description "Unique ID, valid refs, cycles, orphans, causal/feedback loop integrity"
      technology "Rust, crates/sruja-engine"
    }

    Resolver = component "Reference Resolver" {
      description "Resolves and validates references"
      technology "Rust, crates/sruja-engine"
    }
  }

  Export = container "Export System" {
    technology "Rust"
    description "Exports architecture models to various formats"
    tags ["export"]

    MermaidExporter = component "Mermaid Exporter" {
      description "Exports to Mermaid diagram format"
      technology "Rust, crates/sruja-export"
    }

    ViewGenerator = component "View Generator" {
      description "Generates views and diagrams"
      technology "Rust, crates/sruja-export"
    }
  }

  WASM = container "WASM Bindings" {
    technology "Rust, wasm-bindgen, crates/sruja-wasm"
    description "WASM module for in-editor and docs preview (lint/export without a local CLI)"
    tags ["wasm", "core"]
  }

  Graph = container "Knowledge Graph" {
    technology "Rust, crates/sruja-graph"
    description "Graph algorithms and queries (centrality, coupling, SCC, etc.)"
    tags ["context"]
  }

  Scan = container "Repository Scanner" {
    technology "Rust, Tree-sitter, crates/sruja-scan"
    description "Multi-language repository scanning and dependency graph extraction"
    tags ["context"]
  }

  Diff = container "Drift / Diff" {
    technology "Rust, crates/sruja-diff"
    description "Drift detection and delta computation between declared and discovered architecture"
    tags ["context"]
  }

  Intent = container "Intent" {
    technology "Rust, crates/sruja-intent"
    description "Intent vs reality comparisons and intent parsing (ADRs)"
    tags ["context"]
  }

  Report = container "Reports" {
    technology "Rust, crates/sruja-cli"
    description "Compliance report DTOs and rendering (inlined into the CLI)"
    tags ["context"]
  }

  Agent = container "Agentic Memory" {
    technology "Rust, crates/sruja-agent"
    description "Persistent learning and guardrails for AI agents"
    tags ["context", "agent"]

    Memory = component "Agentic Memory Store" {
      description "Learning entries persisted at .sruja/agent_memory.json"
      technology "Rust, crates/sruja-agent"
    }
  }

  Extract = container "Source Extraction" {
    technology "Rust, crates/sruja-extract"
    description "Source code extraction utilities for scanning pipeline"
    tags ["context"]
  }

  GraphCore = container "Graph Core" {
    technology "Rust, crates/sruja-graph-core"
    description "Core graph types and primitives shared across graph-dependent crates"
    tags ["core"]
  }

  LSP = container "IDE Support" {
    technology "TypeScript (extension/), WASM (crates/sruja-wasm)"
    description "VS Code language features and preview powered by the WASM build (no standalone Rust LSP server crate)"
    tags ["lsp", "ide"]

    DiagnosticsAdapter = component "Diagnostics Adapter" {
      description "Error and warning reporting"
      technology "TypeScript, WASM"
    }

    Completion = component "Completion" {
      description "Code completion support"
      technology "TypeScript"
    }

    Hover = component "Hover" {
      description "Hover information"
      technology "TypeScript"
    }

    Definition = component "Definition" {
      description "Go to definition support"
      technology "TypeScript"
    }
  }

  Stdlib = container "Standard Library" {
    technology "Sruja DSL"
    description "Standard C4 element definitions and styles"
    tags ["stdlib", "core"]

    CoreElements = component "Core Elements" {
      description "Standard C4 element kinds (person, system, container, component, etc.)"
      technology "Sruja DSL, lib/"
    }

    Styles = component "Styles" {
      description "Standard styling definitions"
      technology "Sruja DSL, lib/"
    }
  }

  Book = container "Documentation Site (mdBook)" {
    technology "Rust, mdBook"
    description "Docs site and courses built from markdown; published as a static site"
    tags ["docs"]
  }

  VSCode = container "VS Code Extension" {
    technology "TypeScript, VS Code API"
    description "VS Code language support"
    tags ["frontend", "ide"]

    LanguageSupport = component "Language Support" {
      description "Syntax highlighting and language features"
      technology "VS Code API"
    }

    Preview = component "Preview" {
      description "Diagram preview"
      technology "VS Code Webview"
    }
  }

  // Container relationships
  CLI -> Language "Invokes parse/format"
  CLI -> Engine "Invokes validation"
  CLI -> Export "Invokes export"
  CLI -> Diagnostics "Formats diagnostics"
  CLI -> Scan "Scans repositories"
  CLI -> Graph "Runs graph queries"
  CLI -> Diff "Computes drift"
  CLI -> Intent "Evaluates intent vs reality"
  CLI -> Report "Generates reports"
  CLI -> Agent "Records and queries learnings"
  CLI -> Extract "Extracts source context"
  CLI -> GraphCore "Uses graph primitives"

  // Component relationships within containers
  Language.Lexer -> Language.Parser "Provides tokens"
  Language.Parser -> Language.AST "Builds AST"
  Language.AST -> Language.Printer "Formats"
  Language -> Stdlib "Uses"
  Language -> Diagnostics "Reports via"

  CLI.CommandSurface -> Language "Parses DSL"
  CLI.CommandSurface -> Engine "Runs validation"
  CLI.CommandSurface -> Export "Generates exports"
  CLI.CommandSurface -> Diagnostics "Emits"

  CLI.WorkflowSteps -> Scan "Refreshes evidence / builds task context"
  CLI.WorkflowSteps -> Graph "Traverses blast radius"
  CLI.WorkflowSteps -> Diff "Computes drift and deltas"
  CLI.WorkflowSteps -> Intent "Runs critique and intent alignment"
  CLI.WorkflowSteps -> Diagnostics "Emits"

  Language.Parser -> Engine "Validates AST"
  Language.AST -> Export "Exports"
  Engine -> Diagnostics "Reports via"
  Export -> Diagnostics "Reports via"

  Export.ViewGenerator -> Export.MermaidExporter "Generates diagrams"
  Export.ViewGenerator -> Diagnostics "Reports via"
  Export.MermaidExporter -> Diagnostics "Reports via"

  Engine.Validator -> Engine.Rules "Executes"
  Engine.Validator -> Engine.Resolver "Uses"
  Engine.Scorer -> Engine.Validator "Uses"

  Engine -> Export "Validates before export"

  WASM -> Language "Parses"
  WASM -> Engine "Validates"
  WASM -> Export "Exports"
  WASM -> Diagnostics "Reports via"

  LSP -> Language "Parses"
  LSP -> Engine "Validates"
  LSP -> Diagnostics "Reports via"
  LSP -> LSP.DiagnosticsAdapter "Publishes diagnostics"
  LSP.DiagnosticsAdapter -> Diagnostics "Formats via"

  LSP.Completion -> Language "Uses AST"
  LSP.Hover -> Language "Uses AST"
  LSP.Definition -> Language "Resolves symbols"

  Language -> Stdlib.CoreElements "Uses"
  Language -> Stdlib.Styles "Uses"

  VSCode.LanguageSupport -> LSP "Connects to"
  VSCode.Preview -> WASM "Renders diagrams"

  Scan -> Graph "Populates"
  Diff -> Graph "Reads"
  Diff -> Scan "Compares"
  Intent -> Diff "Compares"
  Graph -> GraphCore "Uses"
  Scan -> Extract "Uses"
  Agent.Memory -> Diagnostics "Reports via"
}

// User relationships
Architect -> Sruja.CLI "Uses"
Architect -> Sruja.VSCode "Writes DSL"
Architect -> Sruja.Book "Reads docs"

Developer -> Sruja.CLI "Runs quickstart/sync/context/drift/critique/focus"
Developer -> Sruja.VSCode "Writes code"
Developer -> CratesIo "Installs CLI from"
Developer -> VSCodeMarketplace "Installs extension from"

Contributor -> Sruja "Contributes to"
Contributor -> GitHub "Opens pull requests"

GitHub -> GitHubActions "Triggers workflows"
GitHubActions -> Sruja.CLI "Builds and tests"
GitHubActions -> CratesIo "Publishes sruja-cli"
GitHubActions -> VSCodeMarketplace "Publishes extension"
GitHubActions -> OpenVSX "Publishes extension"
Book -> SrujaWebsite "Publishes to"
GitHubActions -> SrujaWebsite "Deploys docs"

// Requirements
R1 = requirement functional "Must support full C4 model hierarchy"
R2 = requirement performance "Parsing must be < 100ms for typical files"
R3 = requirement portability "Core must compile to WASM"
R4 = requirement functional "Must export to JSON format"

Language -> R1 "Satisfies"
Engine -> R1 "Satisfies"
Language -> R2 "Satisfies"
Engine -> R2 "Satisfies"
WASM -> R3 "Satisfies"
Export -> R4 "Satisfies"

// Architecture Decision Records
ADR001 = adr "Rust for Core and CLI" {
  status "Accepted"
  context "Need a single language for parser, engine, and CLI with WASM support."
  decision "Use Rust (crates: sruja-language, sruja-engine, sruja-cli, sruja-export)."
  consequences "Gain: WASM, single toolchain, type-safe AST. Trade-off: Ecosystem different from previous Go stack"
}

ADR002 = adr "WASM for IDE and Docs Preview" {
  status "Accepted"
  context "We need fast, deterministic lint/export in-editor and in the docs site without requiring a local CLI installation."
  decision "Compile the Rust core to WASM (crates/sruja-wasm) and bundle it in the VS Code extension; optionally embed the same WASM in the mdBook site."
  consequences "Gain: Zero-setup preview and diagnostics. Trade-off: Maintain WASM/native parity and bundle size."
}

ADR003 = adr "JSON as Primary Export Format" {
  status "Accepted"
  context "Need a format that can be consumed by various tools and frontend applications"
  decision "Use JSON as the primary export format produced by Rust exporters, with Markdown and Mermaid exports generated from the same validated model."
  consequences "Gain: Interoperability and consistent outputs across CLI and WASM. Trade-off: Maintain compatibility guarantees for JSON schema versions."
}

// Policies
CodeStyle = policy "Rust code must be formatted with rustfmt" {
  category "quality"
  enforcement "required"
}

NoCycles = policy "No cyclic dependencies between systems" {
  category "structural"
  enforcement "strict"
}

// Flows
AuthoringFlow = flow "Authoring Architecture" {
  step Architect -> Sruja.VSCode "Writes DSL"
  step Sruja.VSCode -> Sruja.WASM "Validates and exports diagram"
  step Sruja.VSCode -> Sruja.LSP "Optional IDE language features"
}

CICDFlow = flow "CI/CD Verification" {
  step Developer -> Sruja.CLI "Pushes code"
  step Sruja.CLI -> Sruja.Engine "Runs lint"
  step Sruja.CLI -> Sruja.Export "Runs export json"
  step Sruja.CLI -> Sruja.Export "Generates artifacts"
}

DailyDevFlow = flow "Daily Development Loop" {
  step Developer -> Sruja.CLI.WorkflowSteps "Runs: sruja sync -r ."
  step Sruja.CLI.WorkflowSteps -> Sruja.Scan "Scans repo"
  step Sruja.CLI.WorkflowSteps -> Sruja.Diff "Detects drift"
  step Developer -> Sruja.CLI.WorkflowSteps "Runs: sruja ai-context -r . --file <file> --intent <intent> -f json"
  step Sruja.CLI.WorkflowSteps -> Sruja.Scan "Builds task-scoped context"
  step Developer -> Sruja.CLI.WorkflowSteps "Runs: sruja drift -r . --violations-only"
  step Developer -> Sruja.CLI.WorkflowSteps "Runs: sruja focus --file <path>"
  step Sruja.CLI.WorkflowSteps -> Sruja.Graph "Traverses blast radius"
  step Developer -> Sruja.CLI.WorkflowSteps "Runs: sruja critique --staged"
  step Sruja.CLI.WorkflowSteps -> Sruja.Intent "Adversarial review"
}

ReleaseFlow = flow "Release & Distribution" {
  step Contributor -> GitHub "Merges changes"
  step GitHub -> GitHubActions "Triggers release workflows"
  step GitHubActions -> CratesIo "Publishes sruja-cli"
  step GitHubActions -> VSCodeMarketplace "Publishes extension"
  step GitHubActions -> OpenVSX "Publishes extension"
  step GitHubActions -> SrujaWebsite "Deploys docs"
  step Developer -> CratesIo "Installs CLI"
  step Developer -> VSCodeMarketplace "Installs extension"
}

// Views
view index {
  title "Sruja Platform Overview"
  include *
}

view backend of Sruja {
  title "Backend Components"
  description "Rust core and LSP components"
  include "Sruja.CLI Sruja.Diagnostics Sruja.Language Sruja.Engine Sruja.Export Sruja.WASM Sruja.LSP Sruja.Stdlib Sruja.Scan Sruja.Graph Sruja.GraphCore Sruja.Extract Sruja.Diff Sruja.Intent Sruja.Report Sruja.Agent"
}

view interfaces of Sruja {
  title "Developer Interfaces"
  description "How developers interact with Sruja"
  include "Sruja.CLI Sruja.VSCode Sruja.Book VSCodeMarketplace OpenVSX CratesIo"
}

view validation of Sruja.Engine {
  title "Validation Rules"
  description "Engine components"
  include "Sruja.Engine.Validator Sruja.Engine.Scorer Sruja.Engine.Rules Sruja.Engine.Resolver"
}

view exporters of Sruja.Export {
  title "Export Formats"
  description "Export components"
  include "Sruja.Export.MermaidExporter Sruja.Export.ViewGenerator"
}

view dataflow of Sruja {
  title "Data Processing Flow"
  description "How DSL is processed through the system"
  include "Sruja.Language Sruja.Engine Sruja.Export"
}

view release of Sruja {
  title "Release & Distribution"
  description "How Sruja artifacts ship to users"
  include "GitHub GitHubActions CratesIo VSCodeMarketplace OpenVSX SrujaWebsite Sruja.CLI Sruja.VSCode Sruja.Book"
}
