Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

AI coding harness for repo structure.

Sruja scans your codebase, reports structural problems AI edits tend to introduce, and gives agents bounded context via MCP (focus, drift state, verify-task). Optional repo.sruja is reviewed CI intent — not required on day one.

New here? Install the CLI, register MCP, install sruja-harness — Quick start (~5 min). Add sruja-architecture only when you want versioned architecture in Git.

The Problem

How does your AI know the real architecture today?

Your approachProblems
Raw model contextEasy to miss boundaries, invent dependencies, or forget prior decisions
Drawings in Miro/LucidChartManual updates, easy to forget, drifts from code
Wiki pagesInconsistent, hard to maintain, no validation

Sound familiar? You're not alone. Most teams struggle with this.

The Solution

Deterministic harness plus optional architecture-as-code.

With Sruja (Tier 1):

  • Structural scan and drift — no .sruja required
  • focus / MCP briefings before the host agent edits
  • verify-task after edits (lint, tests, drift when applicable)
  • Optional: sruja-architecture skill → reviewed repo.sruja in Git
  • Diagrams and docs are Tier-2 exports, not the source of truth

Sruja is not a replacement for Cursor or Copilot — it is the guardrail layer beside them.

How This Helps

Before SrujaWith Sruja
AI guesses from partial contextAI works from repo evidence
Architecture lives in stale diagramsArchitecture lives in versioned repo.sruja
Hard to catch generated mistakesValidation catches syntax, drift, and structural issues
Hard to brief agents consistentlyTask-scoped context is reusable
Diagrams become the truthDiagrams are exported from reviewed truth

Key Concepts

Architecture as Code: Instead of drawing boxes, you define structure in code. AI writes it, you validate it, and everyone uses the same source.

Validation: Like lint for code, sruja lint checks for:

  • Circular dependencies
  • Orphaned components
  • Missing connections
  • Rule violations

C4 Model: Sruja uses the C4 approach, which organizes architecture into levels:

  • Person: Users, external systems
  • System: Major boundaries (e.g., "Order System")
  • Container: Deployable units (e.g., "API Service")
  • Component: Internal parts (e.g., "Payment Module")

This hierarchy makes architecture clear and understandable.

Who is Sruja For?

Students & Learners

  • Understand system design through production-ready examples from fintech, healthcare, and e-commerce
  • Use AI skills to generate architecture and explore patterns without manual DSL writing
  • Real-world scenarios that prepare you for interviews and real projects

Software Architects

  • Review architecture changes against evidence and intent
  • Prevent architectural drift through automated validation
  • Scale guardrails across multiple teams without turning every review into archaeology
  • Document decisions with ADRs (Architecture Decision Records)

Product Teams

  • Link requirements to architecture - see how features map to technical components
  • Track SLOs and metrics alongside your architecture
  • Align technical decisions with business goals and user needs
  • Communicate architecture to stakeholders (export to Markdown/Mermaid when needed)

DevOps Engineers

  • Integrate into CI/CD - validate architecture on every commit
  • Automate documentation generation from architecture files
  • Model deployments - Blue/Green, Canary, multi-region strategies
  • Refresh evidence so AI assistants and reviewers see current repo context

Example

Here's a simple example to get you started:

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

App = system "My App" {
    Web = container "Web Server"
    DB = database "Database"
}

User = person "User"

User -> App.Web "Visits"
App.Web -> App.DB "Reads/Writes"

view index {
    include *
}

For production-ready examples with real-world patterns, see our Examples page featuring:

  • Banking systems (fintech)
  • E-commerce platforms
  • Healthcare platforms (HIPAA-compliant)
  • Multi-tenant SaaS platforms

Next Steps