Sruja – Architecture intelligence for the AI era.

Architecture intelligence for the AI era. Use AI to generate and maintain architecture as code; validate and export to Markdown and Mermaid. A backend tool for the SDLC—not a diagramming product.

Why Sruja?

The Problem

Most architecture tools make you choose:

• Visual-only tools (Draw.io) – no code, no version control, hard to maintain
• Code-only tools (Mermaid, PlantUML) – no validation, manual diagram updates
• Stale diagrams – architecture drifts from reality, documentation gets outdated

Our Solution

Sruja gives you a code-first architecture tool:

Who It's For

• Engineering teams who need architecture as part of their SDLC
• Tech leads who want to enforce architectural standards
• Platform engineers building guardrails for distributed teams
• AI agents that need to reason about system architecture

How We Work

1. Define your architecture in .sruja files
2. Validate with built-in checks (cycles, orphans, unique IDs)
3. Export to JSON, Markdown, or Mermaid diagrams
4. Integrate into CI/CD, docs, and your IDE workflow

We're ultra simple – minimal surface area, no unnecessary apps or frameworks – and highly functional – what we ship works reliably for its scope.

Stack

• Rust – CLI, engine, LSP, WASM (single language for core)
• VS Code extension – Edit .sruja files with syntax highlighting and diagnostics
• Docs – This book (mdBook, Rust-based; no TypeScript/Node)

New here? Install the sruja-architecture skill first (1 minute), then let your AI generate architecture for you. For a single entry point to docs, tutorials, and courses, use Navigate. The left sidebar lists everything; press / or S to search.

See Quick start to install the AI skill and create your first .sruja file. For a single entry point to docs, tutorials, and courses, use Navigate. The left sidebar lists everything; press / or S to search.

Sruja "Show diagram" in code blocks: Run make wasm from the repo root once, then run make book-serve (or ./serve.sh from the book directory) so the WASM files are copied into the book output.

Navigate

New here? Do Quick start first (about 5 min), then the Beginner path (2–3 hours). Everything else is below.

Use one entry point below. The sidebar always lists the full structure.

Quick Start

Get architecture from code in 5 minutes.

You don't write .sruja files. Your AI does it for you. Here's how:

Step 1: Install the AI skill (1 minute)

This teaches your AI editor how to generate Sruja files. The skill will guide you to install the CLI when needed.

npx skills add https://github.com/sruja-ai/sruja --skill sruja-architecture

Supported editors: Cursor, GitHub Copilot, Claude, Continue.dev

Step 2: Generate your architecture file (2 minutes)

Open your AI editor and ask it to generate your architecture:

Use sruja-architecture skill. Analyze my codebase, generate a repo.sruja file, 
then run sruja lint and fix any errors until it passes.

What happens:

1. The skill runs sruja discover to understand your code structure (installs CLI if needed)
2. Asks you 2-3 questions if anything is unclear (e.g., "What's this service for?")
3. Generates a repo.sruja file with your architecture
4. Runs sruja lint to check for errors
5. Fixes any errors automatically

Result: You now have a repo.sruja file in your project root!

Step 3: Validate it (optional)

The skill already validated your file, but you can check manually:

sruja lint repo.sruja

If it says "✅ All checks passed", you're good!

If you see errors, just ask your AI: "Fix these errors."

What's Next?

You have architecture in code. Now what?

Generate diagrams for documentation:

sruja export mermaid repo.sruja > architecture.mmd
sruja export markdown repo.sruja > ARCHITECTURE.md

Keep it in sync:

When you change your code, run:

sruja drift -r .

This shows you what changed and if your architecture needs updating.

Learn more:

• Beginner path – 7 steps to go deeper
• System Design 101 – Learn patterns
• Examples – Real-world architectures

Quick Reference

Common Questions

"What if the command isn't found?"

The CLI isn't on your PATH. Try:

# Add to PATH
export PATH="$HOME/.local/bin:$PATH"

# Or restart your terminal

"My editor doesn't support skills."

You can still use Sruja manually:

• Run sruja discover to get JSON output
• Create repo.sruja by hand (see Language spec)
• Use sruja lint to validate

But AI makes it much easier—consider using Cursor or installing skills.sh.

"What's the difference between quickstart and discover?"

• quickstart – Quick overview, human-readable output (great for first look)
• discover – Detailed JSON output (used by AI for generation)

Option A – install script (downloads from GitHub Releases):

curl -fsSL https://sruja.ai/install.sh | bash

Option B – from Git (requires Rust):

cargo install sruja-cli --git https://github.com/sruja-ai/sruja

Option C – build from source:

git clone https://github.com/sruja-ai/sruja.git && cd sruja
make build

Ensure the sruja binary is on your PATH (install script uses ~/.local/bin by default).

Create a .sruja file

This is the minimal style (explicit kinds, no import). For the full Getting Started guide using stdlib imports, see Getting Started. Both styles are valid; use whichever you prefer.

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

User = person "User" {}
App = system "My App" {
  Web = container "Web Server" { technology "Node.js" }
}
User -> App.Web "visits"

Validate and export

sruja lint example.sruja
sruja export json example.sruja
sruja export markdown example.sruja

VS Code

Install the Sruja extension for syntax, diagnostics, and optional diagram preview in the editor.

Next: Beginner path builds on this in 7 steps (2–3 hours). For a longer "first architecture" walkthrough with a view and stdlib import, see Getting started (full).

VS Code extension

The Sruja VS Code extension provides:

• Syntax highlighting for .sruja files
• Diagnostics (errors, warnings) via the language server
• WASM-based diagram preview – render diagrams from your DSL in the editor (no web server)

Install from the VS Code Marketplace or build from source in extension/.

Introduction

Architecture intelligence for the AI era.

Sruja uses AI to analyze your code and generate architecture as code—so it never drifts from reality.

New here? Do Quick start (about 5 min), then the Beginner path (2–3 hours). You don't write .sruja files manually—your AI does it for you.

The Problem

How do you document architecture today?

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

The Solution

Architecture as code.

With Sruja:

• AI analyzes your codebase automatically
• You get a repo.sruja file (architecture definition)
• Validate it automatically in CI/CD
• Export diagrams when needed (not as the source)

You don't learn a new language. You ask your AI to generate the file, and it handles the syntax.

How This Helps

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

• Enforce architectural standards with policy-as-code
• Prevent architectural drift through automated validation
• Scale governance across multiple teams without manual reviews
• 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
• Track infrastructure - map logical architecture to physical deployment

Example

Here's a simple example to get you started:

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

• New to Sruja? Start with Getting Started
• Use AI: Install the skill in your editor and let AI generate architecture from your codebase
• Need examples? Check out Real-World Examples
• Ready to build? Use the VS Code extension for diagram preview

Getting Started

Architecture from your code—no DSL learning required.

Your AI writes and maintains .sruja files. You just need to know what to ask for.

Prerequisites

• AI editor – Cursor, Copilot, Claude, Continue.dev, etc.
• AI skill – Install first: npx skills add https://github.com/sruja-ai/sruja --skill sruja-architecture (see Install as a Skill)
• Sruja CLI – Needed when the skill runs discover/lint/drift; the skill will guide you to install it if missing (curl -fsSL https://sruja.ai/install.sh | bash)

Step 1: Gather evidence (or let the skill do it)

When you use the sruja-architecture skill, it runs discovery for you. Discovery is not just a file list—under the hood the CLI runs Tree-sitter on your code to build a graph of components and their dependency relations (who imports whom, which modules call which). That graph is the evidence the skill uses.

If you want to run discovery yourself (e.g. to inspect the summary), run:

cd your-project
sruja discover --context -r . --format json

What this does: Scans your repo with Tree-sitter, builds the component/dependency graph, then outputs a summary of that graph (so the AI can scope and ask targeted questions). The skill prefers .sruja/context.json and .sruja/graph.json when present (e.g. after sruja sync or the extension's Refresh repo context); when missing, it runs discover for you—no need to run a command first. For the full graph on demand: sruja scan -r . -o graph.json, or use the graph written by sync at .sruja/graph.json.

Summary output includes:

• Component and edge counts (from the Tree-sitter graph)
• Primary language and framework
• Inferred architecture style (monolith / microservices)
• Suggested areas (top-level path segments for scoping)

Example summary (actual schema):

{
  "repo": "my-app",
  "scan_scope": { "included": [], "excluded": [] },
  "components": 42,
  "edges": 58,
  "primary_language": "TypeScript",
  "framework": "React",
  "architecture_style": "monolith",
  "domain": null,
  "suggested_areas": ["src", "lib", "apps"]
}

The full graph is written by sruja sync to .sruja/graph.json. You can also produce it on demand with sruja scan -r . -o graph.json.

Step 2: Generate Architecture with AI

In your AI editor, run:

Use sruja-architecture. Analyze the discovery output:
[JSON from step 1],
identify systems, containers, and their relationships,
generate repo.sruja using C4 context and container levels,
then run `sruja lint` and fix until it passes.

What your AI will do:

1. Analyze the JSON output from discovery
2. Ask questions if scope is unclear (e.g., "What's this service for?")
3. Generate repo.sruja with your architecture
4. Validate it with sruja lint
5. Fix any errors automatically

What repo.sruja Looks Like

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

// External actors
MobileApp = person "Mobile App" {
  description "Customer-facing mobile application"
}

// Main system
MyApp = system "My Application" {
  description "Handles user requests and processing"

  // Containers (deployable units)
  API = container "API Service" {
    technology "Node.js + Express"
    description "RESTful API for mobile and web clients"
  }

  Worker = container "Background Worker" {
    technology "Node.js + Bull"
    description "Processes async jobs (emails, reports)"
  }

  // Datastores
  Database = database "Primary DB" {
    technology "PostgreSQL"
    description "Stores user data and transactions"
  }

  Cache = database "Redis Cache" {
    technology "Redis"
    description "Caches frequently accessed data"
  }
}

// Relationships (how things connect)
MobileApp -> MyApp.API "HTTPS requests"
MyApp.API -> MyApp.Database "SQL queries"
MyApp.API -> MyApp.Cache "Redis get/set"
MyApp.Worker -> MyApp.Database "SQL queries"

Key concepts:

• person – External actors (users, systems calling you)
• system – Major boundary (your entire application)
• container – Deployable unit (API, worker, web frontend)
• database – Data storage or cache
• -> – Relationship with protocol description

Step 3: Validate

After the AI generates repo.sruja, validate it:

sruja lint repo.sruja

What this checks:

• Syntax errors – Invalid structure or keywords
• Circular dependencies – A depends on B, B depends on A
• Orphan elements – Something with no connections
• Missing fields – Required information not provided

Fix errors: Paste the lint output to your AI and say: "Fix these errors."

Step 4: Export for Documentation

Export Markdown

sruja export markdown repo.sruja > ARCHITECTURE.md

Creates a readable document you can share with your team.

Export Mermaid Diagram

sruja export mermaid repo.sruja > ARCHITECTURE.mmd

Creates a diagram you can:

• Open in Mermaid Live Editor
• Import into VS Code with the extension
• Add to documentation

Export JSON

sruja export json repo.sruja > ARCHITECTURE.json

Machine-readable format for tools and automation.

Understanding C4 Levels

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

Recommended: Start with Person + System + Container levels. Add components only when you need more detail.

Common Questions

"When should I use stdlib imports?"

Always. It saves time by providing standard types (person, system, container, etc.) so you don't define them manually.

"What if discovery doesn't find my code?"

1. Check your language is supported (JavaScript, Python, Go, Rust, Java)
2. Make sure you're in the correct directory
3. Try sruja quickstart -r . to see what's detected

"How detailed should repo.sruja be?"

Start minimal. Only model what you actually need:

• External actors calling your system
• Major containers (services, apps)
• Key datastores

Add more detail only when it provides value.

"Can I edit repo.sruja manually?"

Yes, but it's easier to let AI do it. If you do edit manually:

• Run sruja lint before committing
• Validate syntax with the extension

Next Steps

• Beginner Path: Beginner Path – 7 steps to go deeper
• Examples: Examples Gallery – Real-world architectures
• Language Reference: Language Specification – Complete DSL guide

Quick Reference

How Sruja Works

Sruja is built to be a tool for the AI SDLC process: architecture in code that fits into your lifecycle—IDE, CI/CD, and documentation. We are not a diagramming product; we provide parse, validate, export, and optional preview.

The Sruja Platform

The platform consists of several key components working together:

1. Parser & engine: Rust crates for parsing, validation, and export (sruja-language, sruja-engine, sruja-export).
2. CLI: Command-line interface for local development and CI/CD (sruja-cli).
3. WASM: Rust core compiled to WebAssembly for the docs book and VS Code (sruja-wasm).
4. LSP: Language server for VS Code (sruja-lsp).
5. Docs: This site—built with mdBook from the book/ directory.

Architecture Diagram

Explore the Sruja architecture itself using the interactive viewer below. This diagram is defined in Sruja DSL!

<!-- partial -->
import { * } from 'sruja.ai/stdlib'


RootSystem = system "The Sruja Platform" {
  tags ["root"]
}

User = person "Architect/Developer" {
	description "Uses Sruja to design and document systems"
}

Sruja = system "Sruja Platform" {
	description "Tools for defining, visualizing, and analyzing software architecture"

	CLI = container "Sruja CLI" {
		technology "Rust"
		description "Command-line interface (crates/sruja-cli)"
	}

	Engine = container "Core Engine" {
		technology "Rust"
		description "Validation and export (crates/sruja-engine, sruja-export)"

		Validation = component "Validation Engine" {
			technology "Rust"
			description "Validates AST against rules (crates/sruja-core/src/engine/rules)"
		}

		Scorer = component "Scoring Engine" {
			technology "Rust"
			description "Calculates architecture health score (crates/sruja-core/src/engine/scorer)"
		}

		Policy = component "Policy Engine" {
			technology "Rust"
			description "Enforces custom policies (future: OPA/Rego)"
		}

		Scorer -> Validation "uses results from"
		Validation -> Policy "checks against"
	}

	Language = container "Language Service" {
		technology "Rust"
		description "Parser and AST (crates/sruja-language); LSP (crates/sruja-lsp)"
	}

	WASM = container "WASM Module" {
		technology "Rust/WASM"
		description "WebAssembly build (crates/sruja-wasm)"
	}

	VSCode = container "VS Code Extension" {
		technology "TypeScript"
		description "Editor extension (extension/)"
	}

	Book = container "Documentation" {
		technology "mdBook"
		description "This site (book/)"
	}

	// Internal Dependencies
	CLI -> Language "parses DSL using"
	CLI -> Engine "validates using"
	CLI -> WASM "builds"

	WASM -> Language "embeds"
	WASM -> Engine "embeds"

	VSCode -> Language "uses LSP"
	VSCode -> WASM "uses for LSP and preview"

	Book -> WASM "uses for diagram blocks"
}

User -> Sruja.CLI "runs commands"
User -> Sruja.VSCode "writes DSL"
User -> Sruja.Book "reads docs"

BrowserSystem = system "Web Browser" {
	description "User's web browser environment"
  tags ["external"]
	LocalStore = database "Local Storage"
}

// ADRs
ADR001 = adr "Use WASM for Client-Side Execution" {
	status "Accepted"
	context "We need to run validation and parsing in the browser and VS Code without a backend server."
	decision "Compile the Rust core engine to WebAssembly."
	consequences "Ensures consistent logic across all platforms but increases build complexity."
}

// Deployment
deployment Production "Production Environment" {
  node GitHubPages "GitHub Pages" {
    containerInstance RootSystem
  }
}

GitHubSystem = system "GitHub Platform" {
  description "Source control, CI/CD, and hosting"
  Actions = container "GitHub Actions" {
    technology "YAML/Node"
    description "CI/CD workflows"
  }
  Pages = container "GitHub Pages" {
    technology "Static Hosting"
    description "Hosts documentation site"
  }
  Releases = container "GitHub Releases" {
    technology "File Hosting"
    description "Hosts CLI binaries"
  }
  Actions -> Pages "deploys to"
  Actions -> Releases "publishes to"
}


User -> GitHubSystem "pushes code to"


// Component Stories
CLIStory = story "Using the CLI" {
  User -> Sruja.CLI "runs validate"
  Sruja.CLI -> Sruja.Language "parses DSL"
  Sruja.CLI -> Sruja.Engine "validates"
  Sruja.CLI -> User "reports diagnostics"
}

VSCodeStory = story "Using VS Code" {
  User -> Sruja.VSCode "edits .sruja file"
  Sruja.VSCode -> Sruja.WASM "LSP and preview"
  Sruja.WASM -> Sruja.VSCode "diagnostics and diagram"
  Sruja.VSCode -> User "shows errors and preview"
}

CIDev = scenario "Continuous Integration (Dev)" {
  User -> GitHubSystem "pushes to main"
  GitHubSystem -> GitHubSystem.Actions "triggers CI"
  GitHubSystem.Actions -> Sruja "builds & tests"
  GitHubSystem.Actions -> GitHubSystem.Pages "deploys dev site"
}

ReleaseProd = scenario "Production Release" {
  User -> GitHubSystem "merges PR to prod"
  GitHubSystem -> GitHubSystem.Actions "triggers release"
  GitHubSystem.Actions -> GitHubSystem.Pages "deploys prod site"
  GitHubSystem.Actions -> Sruja.VSCode "publishes extension"
  GitHubSystem.Actions -> GitHubSystem.Releases "publishes CLI binaries"
}

view index {
  title "Complete System View"
  include *
}

Key Components

Core Engine (Rust)

The sruja-language and sruja-engine crates form the foundation. They define the DSL grammar, parse input files into an AST (Abstract Syntax Tree), and run validation rules (like cycle detection and layer enforcement).

WebAssembly (WASM)

The Rust core is compiled to WebAssembly (sruja-wasm). The same parsing and validation logic runs in:

• VS Code Extension: For local preview without needing a CLI binary.
• Documentation site: For "Show diagram" in code blocks (like the one above).

CLI & CI/CD

The sruja CLI (sruja-cli) is a static binary that wraps the core engine. It supports:

• Local development: sruja fmt, sruja lint, sruja export.
• CI/CD: Validate and export architecture in pipelines.
• Export: sruja export json, sruja export mermaid, sruja export markdown, sruja export context, sruja export dsl.

Architecture Intelligence

Sruja provides architecture intelligence across four progressive layers:

┌─────────────────────────────────────────────────────────────┐
│  Layer 4: Intent                                            │
│  "What did we intend vs what exists?"                       │
│  Commands: sruja drift -a, sruja intent check               │
├─────────────────────────────────────────────────────────────┤
│  Layer 3: Semantic                                          │
│  "What does this mean? (vocabulary, patterns)"              │
│  Commands: sruja analyze --semantic                         │
├─────────────────────────────────────────────────────────────┤
│  Layer 2: Structural                                        │
│  "What exists? (components, deps, metrics)"                 │
│  Commands: sruja scan, sruja quickstart, sruja discover    │
├─────────────────────────────────────────────────────────────┤
│  Layer 1: Syntactic                                         │
│  "Is the DSL valid?"                                        │
│  Commands: sruja lint                                       │
└─────────────────────────────────────────────────────────────┘

Each layer builds on the previous:

• Syntactic: Is the .sruja file valid? (lint)
• Structural: What components and dependencies exist? (scan, discover)
• Semantic: What patterns and relationships mean? (analyze)
• Intent: Does reality match declared architecture? (drift, intent check)

AI Skill Multiplies Intelligence

The sruja-architecture skill enhances all four layers:

Install the skill to unlock AI-powered architecture intelligence:

npx skills add https://github.com/sruja-ai/sruja --skill sruja-architecture

Examples & Patterns

Theory is good, but code is better. Below are production-grade Sruja models that you can copy, paste, and adapt.

Every example here follows our "FAANG-level" quality standards:

1. Clear Requirements: Functional & Non-functional.
2. Proper Hierarchies: Context -> Container -> Component.
3. Real Tech Stacks: No generic "Database" boxes.

1. Banking System (Fintech)

Note

Ideally Suited For: Highly regulated industries requiring audit trails, security policies, and strict latency SLAs.

Scenario: A regional bank needs to modernize its legacy mainframe interactions while providing a slick mobile experience.

Why review this example?

• Security: Uses policy blocks for PCI-DSS.
• Hybrid Cloud: Connects modern Cloud Containers to an on-premise "Mainframe" System.
• Complexity: Models the "Legacy Core" vs "Modern Interface" pattern often seen in enterprise.

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


// --- REQUIREMENTS ---
// We start with the 'Why'. These drive the architecture.
R1 = requirement functional "Customers must be able to view balances"
R2 = requirement functional "Customers can transfer money internally"
R3 = requirement security "All PII must be encrypted at rest (PCI-DSS)"
R4 = requirement stability "99.99% Availability (Target: <52m downtime/year)"

// --- ACTORS ---
Customer = person "Banking Customer" {
    description "A holder of one or more accounts"
}

// --- SYSTEMS ---
BankingSystem = system "Internet Banking Platform" {
    description "Allows customers to view information and make payments."

    // Containers (Deployable units)
    WebApp = container "Single Page App" {
        technology "React / TypeScript"
    }

    MobileApp = container "Mobile App" {
        technology "Flutter"
    }

    API = container "Main API Gateway" {
        technology "Java / Spring Boot"
        description "Orchestrates calls to core services"
    }

    Database = container "Main RDBMS" {
        technology "PostgreSQL"
        tags ["database", "storage"]
    }

    // Relationships
    WebApp -> API "Uses (JSON/HTTPS)"
    MobileApp -> API "Uses (JSON/HTTPS)"
    API -> Database "Reads/Writes (JDBC)"
}

// --- EXTERNAL SYSTEMS ---
Mainframe = system "Legacy Core Banking" {
    tags ["external"] // This is outside our scope of control
    description "The heavy iron that stores the actual money."
}

EmailSystem = system "Email Service" {
    tags ["external"]
    description "SendGrid / AWS SES"
}

// --- INTEGRATIONS ---
Customer -> BankingSystem.WebApp "Views dashboard"
BankingSystem.API -> Mainframe "Syncs transactions (XML/SOAP)"
BankingSystem.API -> EmailSystem "Sends alerts"

view index {
include *
}

👉 Deep Dive this Architecture using our Course

2. Global E-Commerce Platform

Note

Ideally Suited For: High-scale B2C applications. Focuses on caching, asynchronous processing, and eventual consistency.

Scenario: An Amazon-like store preparing for Black Friday traffic spikes.

Why review this example?

• Scalability: Explains how to handle high reads (Product Catalog) vs transactional writes (Checkout).
• Async Messaging: Shows usages of Queues/Topics (Apache Kafka) to decouple services.
• Caching: Strategic placement of Redis caches.

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


R1 = requirement scale "Handle 100k concurrent users"
R2 = requirement performance "Product pages load in <100ms"

ShopScale = system "E-Commerce Platform" {

    // --- EDGE LAYER ---
    CDN = container "Content Delivery Network" {
        technology "Cloudflare"
        description "Caches static assets and product images"
    }

    LoadBalancer = container "Load Balancer" {
        technology "NGINX"
    }

    // --- SERVICE LAYER ---
    Storefront = container "Storefront Service" {
        technology "Node.js"
        description "SSR for SEO-friendly product pages"
    }

    Checkout = container "Checkout Service" {
        technology "Rust"
        description "Handles payments and inventory locking"
    }

    // --- DATA LAYER ---
    ProductCache = container "Product Cache" {
        technology "Redis Cluster"
        description "Stores hot product data"
    }

    MainDB = database "Product Database" {
        technology "MongoDB"
        description "Flexible schema for diverse product attributes"
    }

    OrderQueue = queue "Order Events" {
        technology "Kafka"
        description "Async order processing pipeline"
    }

    // --- FLOWS ---
    CDN -> LoadBalancer "Forwards dynamic requests"
    LoadBalancer -> Storefront "Routes traffic"
    Storefront -> ProductCache "Read-through cache"
    Storefront -> MainDB "Cache miss / heavy query"

    // The Checkout Flow
    Checkout -> OrderQueue "Publishes 'OrderCreated'"
}

view index {
include *
}

What Next?

• New to Sruja? Try Getting started.
• Need more depth? See Courses and Tutorials.

Beginner Path: Use AI Skills for Architecture

Don't learn a language—use AI to generate and maintain architecture.

If you just did Quick Start, you have the CLI and skill installed. These 7 steps show how to use AI to maintain your architecture effectively.

Tip

Track your progress: Check off each step as you complete it. Takes ~2–3 hours total.

Step 1: Generate Your First Architecture ⏱️ 20–30 min

What you'll do: Let AI analyze your code and create repo.sruja

Instructions:

1. Open your project in your AI editor
2. Run this prompt:

Use sruja-architecture. Run `sruja discover --context -r . --format json`,
gather evidence, identify systems and containers,
generate repo.sruja with C4 context and container levels,
then run `sruja lint` and fix until it passes.

3. Wait for AI to ask 2-3 questions
4. Answer the questions (be specific: "Production database is PostgreSQL")
5. Review the generated repo.sruja file

Success check: You have a repo.sruja file that passes sruja lint

What you learned:

• How AI analyzes your codebase
• What questions it asks
• What a valid repo.sruja looks like

Step 2: Understand What Was Generated ⏱️ 15–20 min

What you'll do: Read and understand your AI-generated architecture

Instructions:

1. Open repo.sruja in your editor
2. Read it section by section:
   • person entries = external actors
   • system entries = your major boundaries
   • container entries = deployable units
   • -> lines = relationships
3. Run sruja tree repo.sruja to see structure visually
4. Ask AI to explain:

Read repo.sruja and explain:
1. What systems are defined?
2. How do containers connect?
3. What external actors use this system?

Success check: You can explain your architecture in plain English

What you learned:

• C4 structure (person → system → container)
• How to read relationships
• What each component does

Step 3: Validate and Fix Errors ⏱️ 15–20 min

What you'll do: Learn to validate and fix issues with AI help

Instructions:

1. Run sruja lint repo.sruja
2. If you see errors, copy them to clipboard
3. Ask AI:

I got these lint errors. Fix them in repo.sruja:
[paste errors here]

Common errors:

4. Re-run sruja lint until clean

Success check: sruja lint repo.sruja shows "All checks passed"

What you learned:

• How validation works
• Common architecture errors
• How to ask AI to fix issues

Step 4: Make a Specific Change ⏱️ 20–30 min

What you'll do: Direct AI to add or modify something specific

Instructions:

Think of a change you want. Examples:

• Add component: "Add a logging service container"
• Add relationship: "Connect the new logger to all existing containers"
• Modify description: "Update the API container description to say it handles webhooks"

Then ask AI:

Use sruja-architecture. Read repo.sruja and:
[your change here]
Then run sruja lint and fix any errors.

Success check: Your change is added and sruja lint passes

What you learned:

• How to make targeted updates
• To validate after each change
• That iteration is normal (AI can refine it)

Step 5: Export for Your Team ⏱️ 10–15 min

What you'll do: Share architecture with stakeholders

Instructions:

1. Export Markdown:

sruja export markdown repo.sruja > ARCHITECTURE.md

2. Export diagram:

sruja export mermaid repo.sruja > ARCHITECTURE.mmd

3. Open ARCHITECTURE.md and review
4. Open ARCHITECTURE.mmd in Mermaid Live Editor

Success check: You can send ARCHITECTURE.md to your team and they understand it

What you learned:

• Different export formats
• How to share architecture
• That diagrams are output, not the source

Step 6: Detect and Fix Drift ⏱️ 20–30 min

What you'll do: Keep architecture in sync as code changes

Instructions:

1. Make a small change to your actual code

   • Add a new function
   • Rename a file
   • Move a module

2. Run drift detection:

sruja drift -r . --format json

3. Ask AI:

Use sruja-architecture. Here's drift output:
[paste JSON]
Analyze what changed and update repo.sruja to match current code.

4. Review the changes AI made
5. Run sruja lint repo.sruja

Success check: sruja drift shows no issues (or you've addressed them)

What you learned:

• How to detect changes over time
• To let AI update architecture automatically
• That architecture stays in sync with code

Step 7: Explore Patterns with AI ⏱️ 15–20 min

What you'll do: Use AI as an architecture advisor

Instructions:

Pick a pattern and ask AI to explain it:

Monolith:

Use sruja-architecture. Explain the monolith pattern:
When to use it, pros/cons, and show an example in Sruja syntax.

Microservices:

Use sruja-architecture. Explain microservices:
When to split, trade-offs, and generate an example architecture.

Event-driven:

Use sruja-architecture. Show me an event-driven architecture
with Kafka, producers, and consumers. Explain trade-offs.

Success check: You understand different patterns and when to use them

What you learned:

• Architectural patterns
• When each pattern makes sense
• That AI can be your advisor, not just generator

Tips for Success

Common Mistakes to Avoid

❌ Don't: "Generate full architecture for everything"

✅ Do: Start with context + container levels, add components when needed

❌ Don't: Guess at missing information

✅ Do: Ask targeted questions, list what's unknown

❌ Don't: Skip validation

✅ Do: Always run sruja lint after AI edits

❌ Don't: Model for completeness

✅ Do: Model what evidence supports—minimal is better

What's Next?

Go deeper:

• System Design 101 – Module 1 – Learn architecture concepts
• Skill Reference – What the skill knows

Practice:

• Try different codebases (your own or open-source examples)
• Practice making specific changes
• Compare different patterns with AI

Connect:

• GitHub Discussions – Ask questions, share patterns
• Community – See how others use Sruja

Quick Reference

Remember: You're not learning a language. You're learning how to:

1. Guide AI with clear requests
2. Validate results
3. Iterate and refine
4. Use AI as an advisor

The skill handles the syntax—you handle the thinking.

Frequently Asked Questions

New to Sruja? Start here.

Installation

Do I need to know programming to use Sruja?

Not really. You need:

• Basic comfort with terminals (running commands)
• A codebase to document (any language)
• An AI editor (Cursor, Copilot, Claude, etc.)

You don't write the .sruja files manually—your AI does it.

What editors work with Sruja?

AI editors with skill support:

• Cursor ✅ (built-in support)
• GitHub Copilot ✅ (requires skills.sh)
• Claude ✅ (requires skills.sh)
• Continue.dev ✅ (requires skills.sh)
• Any editor with skills.sh support

Manual use:

• VS Code with Sruja extension (syntax highlighting, preview)
• Terminal (run commands manually, write .sruja by hand)

What's the difference between the CLI and the skill?

You need both: CLI for validation, skill for generation.

Can I use Sruja without an AI editor?

Yes, but it's more work.

You can:

• Run sruja discover and manually create .sruja files
• Use the VS Code extension for syntax highlighting
• Write .sruja by hand using the language reference

However, AI makes it 10x easier. Consider using Cursor or installing skills.sh for your current editor.

Workflow

How long does it take to generate architecture?

First time: 5-10 minutes

• AI analyzes code
• AI asks 2-3 questions
• AI generates and validates

Updates: 2-5 minutes

• AI reads existing file
• AI makes your change
• AI validates

With practice: Most updates are 1-2 minutes

What information does AI need from me?

Usually just 2-3 questions:

1. System boundaries: "What are the main systems?"
2. External actors: "Who or what calls your system?"
3. Deployment: "How is this deployed?"

The AI gets everything else from your code.

What if I don't know the answer to a question?

That's fine! Tell your AI:

I don't know the answer to "What's the deployment model?"
Please assume [state your best guess or leave as TODO].

The AI can generate a TODO or make reasonable assumptions, which you can refine later.

Files and Syntax

What's the difference between repo.sruja and architecture.sruja?

They're the same thing, just different names.

• repo.sruja – Recommended for new projects
• architecture.sruja – Supported for backward compatibility

Use whichever you like—Sruja detects both.

Where should I put repo.sruja?

Repository root (same folder as package.json, pom.xml, etc.)

Example structure:

my-project/
├── src/
├── package.json
├── README.md
└── repo.sruja          ← Put it here

Can I have multiple .sruja files?

Yes. Common patterns:

• One file per system: user-service.sruja, order-service.sruja
• One per module: auth.sruja, api.sruja, db.sruja
• Nested: arch/repo.sruja, arch/services.sruja

Sruja will detect any .sruja file when you run commands.

Do I need to import from stdlib?

Recommended: yes.

import { * } from 'sruja.ai/stdlib' gives you standard types:

• person, system, container, database, queue
• Without needing to define them manually

You can still define types manually (see Quick Start), but imports save time.

Validation

What does sruja lint check?

Run sruja lint repo.sruja before committing changes.

What if I see errors?

Copy and paste to AI:

Fix these lint errors in repo.sruja:
[paste errors]

Common fixes:

Can I ignore lint errors?

Not recommended. Lint errors indicate real issues:

• Your architecture might not match reality
• Team members might misunderstand the design
• Documentation might be incomplete

Fix errors or add a comment explaining why it's okay.

Using with AI

How specific should I be with prompts?

More specific = better results.

❌ Too vague:

Improve my architecture.

✅ Specific:

Add error handling to the API container.
Update the description to mention rate limiting.

What if AI generates something wrong?

Don't panic. This is normal.

1. Tell AI: "This isn't quite right. Here's what I want: [describe]"
2. Or: "Undo that change. Try again with these constraints: [list]"
3. Or: Make the change yourself, then ask AI to validate

Validation catches mistakes, and iteration is expected.

Can AI handle large codebases?

Yes. Sruja scales:

• Small (10-100 files): Full analysis in seconds
• Medium (100-1000 files): Full analysis in 1-2 minutes
• Large (1000+ files): May take several minutes

AI can handle any size—it just processes more data for larger projects.

Comparison to Other Tools

How is Sruja different from diagramming tools (Miro, LucidChart)?

Think of it this way: Diagrams are like screenshots—great for viewing, but not the source.

How is Sruja different from architecture frameworks (Spring, DDD)?

Sruja doesn't replace frameworks—it documents them.

• Frameworks (Spring, DDD, Clean Architecture) – Guide how to write code
• Sruja – Documents what your code actually does

You can use both: Sruja documents your Spring-based microservices architecture.

AI and Architecture

Why do I need the Sruja skill when I can just ask AI for architecture?

AI proposes; Sruja grounds, validates, and persists.

Without Sruja, AI can suggest architecture, but it's:

• Ungrounded: AI may invent components or dependencies that don't exist in your code
• Ephemeral: You get ad-hoc text or diagrams with no single source of truth

The Sruja skill gives AI:

• Real evidence (from your codebase) to reason about
• Validation (lint, drift) to ensure accuracy
• Persistence (repo.sruja as a first-class artifact in your repo)

Three pillars:

1. Grounding — The skill feeds the model real data (discover, context, graph) so it reasons on what's actually in the codebase, not on guesses. Without Sruja, the model can hallucinate modules and edges.
2. Validation and sync — The skill uses sruja lint (valid DSL), sruja drift (declared vs actual), and intent check. So you get architecture that is valid and stays in sync with code, not a one-off diagram.
3. Persistence and reuse — Architecture lives as repo.sruja in the repo: versionable, exportable, comparable over time. The model without Sruja gives ad-hoc text or Mermaid; with Sruja, the output is a first-class artifact the whole team and CI can use.

Think of it this way: AI is the architect proposing designs. Sruja is the structural engineer providing real data, validating plans, and making sure the blueprint is saved in your repo.

Language Support

What programming languages does Sruja support?

What if my language isn't listed?

Try it! Run:

sruja discover -r . --format json

If you see reasonable output, Sruja can analyze it. If not, please open an issue.

Troubleshooting

"sruja: command not found"

The CLI isn't on your PATH.

Try:

# Check if installed
which sruja

# Add to PATH (if using install script)
export PATH="$HOME/.local/bin:$PATH"

# Or restart your terminal

Skill not loading in my editor

Common causes:

1. Didn't restart editor after installing
2. Editor doesn't support skills.sh
3. Typed wrong skill name

Fixes:

• Restart your editor
• Try: npx skills list to see installed skills
• Check editor has skills.sh support

"Command fails: directory not found"

You're in the wrong folder.

Make sure:

# You should be IN your project
cd your-project

# Not AT the Sruja repo
# ❌ Wrong: cd ~/sruja
# ✅ Right: cd ~/my-project

Discovery shows nothing

Possible causes:

1. No supported files – Empty directory or wrong language
2. Wrong directory – Not in the project root
3. Language limitation – Partial support for that language

Try:

# See what's detected
sruja discover -r . --format json

# Try quickstart for better visibility
sruja quickstart -r .

Best Practices

Start small

✅ Do:

• Get person + system + container levels working first
• Add components only when needed
• Model what evidence supports

❌ Don't:

• Model everything you can think of
• Add components "for completeness"
• Over-complicate simple systems

Validate often

✅ Do:

• Run sruja lint after each AI edit
• Check before committing
• Fix errors before calling it "done"

❌ Don't:

• Skip validation to "save time"
• Commit known errors with a TODO

Iterate with AI

✅ Do:

• Treat first attempt as draft, not final
• Provide feedback: "Good, but add X"
• Ask AI to refine specific parts

❌ Don't:

• Expect perfection on first try
• Give up if it's not exactly right
• Start over from scratch instead of refining

Document decisions

✅ Do:

• Add descriptions to components
• Note why you chose a pattern
• Explain trade-offs

❌ Don't:

• Leave components unlabeled
• Assume everyone knows your intent

Getting Help

Where can I ask questions?

• GitHub Discussions: https://github.com/sruja-ai/sruja/discussions
• Documentation: Getting Started or Beginner Path
• Examples: Examples Gallery

How do I report a bug?

1. Check if it's already reported: https://github.com/sruja-ai/sruja/issues
2. If not, create a new issue with:
   • Steps to reproduce
   • What you expected
   • What actually happened
   • Your environment (OS, editor, language)

How do I contribute?

See Contributing Guide for guidelines.

Quick Command Reference

Key Takeaways

1. You don't learn a language—you guide AI
2. Validation is your friend—run lint often
3. Start minimal—add detail only when needed
4. Iterate—refine with feedback
5. Use AI as advisor—ask about patterns and trade-offs

The skill handles syntax. You handle thinking.

Overview

Use overview to provide a concise system description shown in docs/exports.

Syntax

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


overview {
title "E‑Commerce Platform"
summary "Web, API, and DB supporting browse, cart, and checkout"
}

view index {
include *
}

Guidance

• Keep summary short and practical; avoid marketing language.
• Use overview at architecture root; prefer description inside elements for details.

Architecture

The architecture block is the root element of a Sruja model. It represents the entire scope of what you are modeling.

Syntax

Explicit Block (Recommended for large projects)

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


// ... define systems, persons, etc. here

view index {
include *
}

Minimal Example

For simple examples, you can use a minimal structure:

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


MySystem = system "My System"
User = person "User"

Purpose

• Scope Boundary: Everything inside is part of the model.
• Naming: Gives a name to the overall architecture.

The C4 Model

Sruja is built on the C4 model, a hierarchical approach to software architecture diagrams. If you are new to architecture-as-code, it helps to understand these four levels of abstraction.

Think of it like Google Maps for your code: you can zoom out to see the whole world (System Context), or zoom in to see individual streets (Code).

The 4 Levels

1. System Context (Level 1)

"The Big Picture"

This is the highest level of abstraction. It shows your software system as a single box, and how it interacts with users and other systems (like functional dependencies, email systems, or payment gateways).

• Goal: What is the system, who uses it, and how does it fit into the existing IT landscape?
• Audience: Everyone (Technical & Non-Technical).

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


App = system "My App"
User = person "Customer"
Stripe = system "Payment Gateway"

User -> App "Uses"
App -> Stripe "Process Payments"

2. Container (Level 2)

"The High-Level Technical Building Blocks"

Note: In C4, a "Container" is NOT a Docker container. It represents a deployable unit—something that runs separately. Examples include:

• A Single-Page Application (SPA)

• A Mobile App

• A Server-side API application

• A Database

• A File System

• Goal: What are the major technical choices? How do they communicate?

• Audience: Architects, Developers, Ops.

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


App = system "My App" {
    Web = container "React App"
    API = container "Rust Service"
    DB = database "PostgreSQL"
}

3. Component (Level 3)

"The Internals"

Zooming into a Container to see the major structural building blocks. In an API, these might be your controllers, services, or repositories.

• Goal: How is the container structured?
• Audience: Developers.

4. Code (Level 4)

"The Details"

The actual classes, interfaces, and functions. Sruja focuses mainly on Levels 1, 2, and 3, as Level 4 is best managed by your IDE.

Key Relationships

The power of C4 is in the Hierarchical nature.

• A System defines the boundary.
• Containers live inside a System.
• Components live inside a Container.

When you define a relationship at a lower level (e.g., API -> DB), Sruja automatically understands the relationship at higher levels (e.g., App -> DB is implied).

Why use C4?

1. Shared Vocabulary: "Component" and "Service" often mean different things to different teams. C4 standardizes this.
2. Zoom Levels: Avoids the "one giant messy diagram" problem. You can view the system at the level of detail relevant to you.

System

A System represents a software system, which is the highest level of abstraction in the C4 model. A system delivers value to its users, whether they are human or other systems.

Syntax

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


ID = system "Label/Name" {
description "Optional description"

// Link to ADRs
adr ADR001

// ... contains containers
}

Example

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


BankingSystem = system "Internet Banking System" {
description "Allows customers to view accounts and make payments."
}

Container

A Container represents an application or a data store. It is something that needs to be running in order for the overall software system to work.

Note: In C4, "Container" does not mean a Docker container. It means a deployable unit like:

• Server-side web application (e.g., Java Spring, ASP.NET Core)
• Client-side web application (e.g., React, Angular)
• Mobile app
• Database schema
• File system

Syntax

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


ID = container "Label/Name" {
technology "Technology Stack"
tags ["tag1", "tag2"]
// ... contains components
}

Example

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


BankingSystem = system "Internet Banking System" {
WebApp = container "Web Application" {
  technology "Java and Spring MVC"
  tags ["web", "frontend"]
}
}

Scaling Configuration

Containers can define horizontal scaling properties using the scale block:

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


API = container "API Service" {
technology "Rust, Axum"
scale {
  min 3
  max 10
  metric "cpu > 80%"
}
}

Scale Block Fields

• min (optional): Minimum number of replicas
• max (optional): Maximum number of replicas
• metric (optional): Scaling metric trigger (e.g., "cpu > 80%", "memory > 90%")

This helps document your auto-scaling strategy and can be used by deployment tools.

Component

A Component is a grouping of related functionality encapsulated behind a well-defined interface. Components reside inside Containers.

Syntax

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


ID = component "Label/Name" {
technology "Technology"
// ... items
}

Example

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


AuthController = component "Authentication Controller" {
technology "Spring MVC Rest Controller"
description "Handles user login and registration."
}

Person

A Person represents a human user of your software system (e.g., "Customer", "Admin", "Employee").

Syntax

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


ID = person "Label" {
  description "Optional description"
  tags ["tag1", "tag2"]
}

Example

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


Customer = person "Bank Customer" {
  description "A customer of the bank with personal accounts."
}

Relations

Relations describe how elements interact with each other. They are the lines connecting the boxes in your diagram.

Syntax

<!-- partial -->
import { * } from 'sruja.ai/stdlib'


// Relations use element IDs
Source -> Destination "Label"
// When referring to nested elements, use fully qualified names:
System.Container -> System.Container.Component "Label"

Or with a technology/protocol:

<!-- partial -->
Source -> Destination "Label" {
technology "HTTPS/JSON"
}

Example

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


BankingSystem = system "Internet Banking System" {
WebApp = container "Web Application"
DB = database "Database"
}

User = person "User"

User -> BankingSystem.WebApp "Visits"
BankingSystem.WebApp -> BankingSystem.DB "Reads Data"

Use clear, unique IDs to reference relation endpoints.

See Also

• Scenario
• Validation

Views

Define views to customize what elements appear and how they render.

Syntax

person = kind "Person"
system = kind "System"
container = kind "Container"
database = kind "Database"

App = system "Application" {
  WebApp = container "Web App"
  API = container "API"
  DB = database "Database"
}

User = person "User"

User -> App.WebApp "Uses"
App.WebApp -> App.API "Calls"
App.API -> App.DB "Reads/Writes"

view api_focus of App {
  title "API Focus"
  include App.API App.DB
  exclude App.WebApp
}

styles {
  element "Database" { shape "cylinder" color "#3b82f6" }
  relationship "Calls" { color "#ef4444" }
}

view index {
  include *
}

Guidance

• Use include to spotlight critical paths; use exclude to reduce noise.
• Keep view names descriptive (e.g., "API Focus", "Data Flow").
• Use view styles for legibility: color important relations, reshape data stores.

Related

• relations for edges
• style block for global defaults

Validation

Sruja validates your model to catch issues early.

Common Checks

• Unique IDs within scope
• Valid references (relations connect existing elements)
• Cycles (informational; feedback loops are valid)
• Layering violations (dependencies must flow downward)
• External boundary checks
• Simplicity guidance (non‑blocking)

Example

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


User = person "User"
App = system "App" {
  WebApp = container "Web App"
  API = container "API"
  DB = database "Database"
}

// Valid relations (qualified cross-scope)
User -> App.WebApp "Uses"
App.WebApp -> App.API "Calls"
App.API -> App.DB "Reads/Writes"

view index {
include *
}

Run sruja validate locally or in CI to enforce these rules.

See Also

• Layering
• Scenario

Deployment

The Deployment view allows you to map your software containers to infrastructure. This corresponds to the C4 Deployment Diagram.

Deployment Node

A Deployment Node is something like physical hardware, a virtual machine, a Docker container, a Kubernetes pod, etc. Nodes can be nested.

Syntax

<!-- partial -->
deployment "Environment" {
    node "Node Name" {
        // ...
    }
}

Infrastructure Node

An Infrastructure Node represents infrastructure software that isn't one of your containers (e.g., DNS, Load Balancer, External Database Service).

Syntax

<!-- partial -->
node "App Server" {
    containerInstance WebApp
}

Container Instance

A Container Instance represents a runtime instance of one of your defined Containers running on a Deployment Node.

Syntax

<!-- partial -->
containerInstance ContainerID {
    instanceId 1 // Optional
}

Example

<!-- partial -->
deployment "Production" {
    node "AWS" {
        node "US-East-1" {
            node "App Server" {
                containerInstance WebApp
            }
            node "Database Server" {
                containerInstance DB
            }
        }
    }
}

Requirements

Use requirement to capture functional, performance, security, and constraint requirements. Requirements are declared at the architecture root only.

Syntax

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


// Requirements using flat syntax
R1 = requirement functional "Support 10k concurrent users"
R2 = requirement performance "p95 < 200ms for /checkout"
R3 = requirement security "PII encrypted at rest"
R4 = requirement constraint "Only PostgreSQL managed service"
R5 = requirement nonfunctional "System must be maintainable"

view index {
  include *
}

Guidance

• Keep requirement titles concise and testable.
• Reference requirements in ADRs and scenarios where relevant.
• Validate with sruja lint to surface unmet or conflicting requirements.
• Declarations at system/container/component level are deprecated and ignored by exporters and UI.

Related

• scenario for behavior walkthroughs
• slo for targets and windows
• adr for decision records

Scenario

Scenarios describe behavioral flows as ordered steps. They focus on interactions rather than data pipelines.

Syntax

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


Customer = person "Customer"
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API"
  DB = database "Database"
}

// Scenarios using flat syntax
CheckoutFlow = scenario "User Checkout" {
  step Customer -> Shop.WebApp "adds items to cart"
  step Shop.WebApp -> Shop.API "submits cart"
  step Shop.API -> Shop.DB "validates and reserves stock"
  step Shop.API -> Shop.WebApp "returns confirmation"
  step Shop.WebApp -> Customer "displays success"
}

// 'story' is an alias for 'scenario'
LoginStory = story "User Login" {
  step Customer -> Shop.WebApp "enters credentials"
  step Shop.WebApp -> Shop.API "validates user"
}

view index {
  include *
}

Aliases & Semantics

Sruja provides three keywords that are structurally identical (sharing the same underlying AST definition and syntax) but convey different semantic intent:

• scenario: Models behavioral flows (e.g., Use Cases, User Journeys).
• story: An alias for scenario (e.g., User Stories).
• flow: Models data movement (e.g., Data Flow Diagrams).

While the syntax is the same, using the appropriate keyword helps readers understand the nature of the interaction being modeled.

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


Customer = person "Customer"
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API"
  DB = database "Database"
}

// Scenario: User behavior
Checkout = scenario "User Checkout" {
  Customer -> Shop.WebApp "adds items to cart"
  Shop.WebApp -> Shop.API "submits cart"
}

// Flow: Data flow
OrderProcess = flow "Order Processing" {
  Customer -> Shop "Order Details"
  Shop -> Shop.API "Processes"
  Shop.API -> Shop.DB "Save Order"
}

When to use:

• Use scenario for user journeys, business processes, and behavioral flows
• Use flow for data pipelines, ETL processes, and system-to-system data flows

Tips

• Keep step labels short and action‑oriented
• Use fully qualified names when referring outside the current context
• Use scenario or story for behavior; use flow for data flows; use relations for structure

See Also

• Layering
• Validation

Architecture Decision Records (ADR)

Sruja allows you to capture Architecture Decision Records (ADRs) directly within your architecture model. This keeps the "why" close to the "what".

Syntax

Defining an ADR

You can define an ADR with a full body describing the context, decision, and consequences.

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


ADR001 = adr "Use PostgreSQL" {
status "Accepted"
context "We need a relational database with strong consistency guarantees."
decision "We will use PostgreSQL 15."
consequences "Good ecosystem support, but requires managing migrations."
}

Linking ADRs

You can link an ADR to the elements it affects (System, Container, Component) by referencing its ID inside the element's block.

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


Backend = system "Backend API" {
// Link to the ADR (via metadata in future)
}

Optional Title

The title is optional if you are just referencing an ADR or if you want to define it later.

adr = kind "ADR"
ADR003 = adr "Deferred Decision"

Fields

• ID: Unique identifier (e.g., ADR001).
• Title: Short summary of the decision.
• Status: Current status (e.g., Proposed, Accepted, Deprecated).
• Context: The problem statement and background.
• Decision: The choice made.
• Consequences: The pros, cons, and implications of the decision.

Policy

Policies define architectural rules, standards, and constraints that your system must follow. They help enforce best practices, compliance requirements, and organizational standards directly in your architecture model.

Syntax

<!-- partial -->
PolicyID = policy "Description" {
  category "category-name"
  enforcement "required" // "required" | "recommended" | "optional"
  description "Detailed description"
  metadata {
    // Additional metadata
  }
}

Simple Policy

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


SecurityPolicy = policy "Enforce TLS 1.3 for all external communications"

view index {
  include *
}

Policy Fields

• ID: Unique identifier for the policy (e.g., SecurityPolicy, GDPR_Compliance)
• Description: Human-readable description of the policy
• category (optional): Policy category (e.g., "security", "compliance", "performance")
• enforcement (optional): Enforcement level ("required", "recommended", "optional")
• description (optional): Detailed description within the policy body
• metadata (optional): Additional metadata key-value pairs

Example: Security Policies

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


TLSEnforcement = policy "All external communications must use TLS 1.3" {
  category "security"
  enforcement "required"
}

EncryptionAtRest = policy "Sensitive data must be encrypted at rest" {
  category "security"
  enforcement "required"
}

BankingApp = system "Banking App" {
  API = container "API Service"
  CustomerDB = database "Customer Database"
}

view index {
  include *
}

Example: Compliance Policies

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


HIPAACompliance = policy "Must comply with HIPAA regulations" {
  category "compliance"
  enforcement "required"
  description "All patient data must be encrypted and access logged"
}

DataRetention = policy "Medical records retained for 10 years" {
  category "compliance"
  enforcement "required"
}

view index {
  include *
}

Policy Categories

Common policy categories include:

• security: Security standards and practices
• compliance: Regulatory and legal requirements
• performance: Performance standards and SLAs
• observability: Monitoring, logging, and metrics requirements
• architecture: Architectural patterns and principles
• data: Data handling and privacy requirements

Enforcement Levels

• required: Policy must be followed (non-negotiable)
• recommended: Policy should be followed (best practice)
• optional: Policy is a guideline (suggested)

Benefits

• Documentation: Policies are part of your architecture, not separate documents
• Validation: Can be validated against actual implementations
• Communication: Clear standards for development teams
• Compliance: Track regulatory and organizational requirements
• Governance: Enforce architectural decisions and patterns

Note on Rules

The rule keyword inside policies is not yet implemented. For now, policies serve as documentation and can be validated manually or through external tooling.

See Also

• Architecture
• System
• Requirements
• ADR

Syntax Reference

Elements

<!-- partial -->
import { * } from 'sruja.ai/stdlib'


ID = person "Label"
ID = system "Label" { ... }
ID = container "Label" { ... }
ID = database "Label" { ... }
ID = queue "Label" { ... }
ID = component "Label" { ... }

Relations

<!-- partial -->
Source -> Target "Label"
// Use fully qualified names when referring to nested elements:
System.Container -> System.API "Label"
System.Container.Component -> System.API.Component "Label"

Metadata

overview {
  summary "Syntax Reference Overview"
}

MySystem = system "MySystem" {
  metadata {
    team "Platform"
    tier "critical"
  }
}

Deployment

<!-- partial -->
deployment Prod {
  node Cloud {
    node Region {
      node Service {
        containerInstance Web
      }
    }
  }
}

Architecture Patterns

Request/Response

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


App = system "App" {
Web = container "Web"
API = container "API"
DB = database "Database"
}

App.Web -> App.API "Calls"
App.API -> App.DB "Reads/Writes"

view index {
include *
}

Event-Driven

<!-- partial -->
import { * } from 'sruja.ai/stdlib'


Orders = system "Order System" {
OrderSvc = container "Order Service"
PaymentSvc = container "Payment Service"
}

Orders.OrderSvc -> Orders.PaymentSvc "OrderCreated event"
Orders.PaymentSvc -> Orders.OrderSvc "PaymentConfirmed event"

view index {
include *
}

Saga

<!-- partial -->
import { * } from 'sruja.ai/stdlib'


Orders = system "Order System" {
OrderSvc = container "Order Service"
InventorySvc = container "Inventory Service"
PaymentSvc = container "Payment Service"
}

CreateOrderSaga = scenario "Order Creation Saga" {
Orders.OrderSvc -> Orders.InventorySvc "Reserves stock"
Orders.InventorySvc -> Orders.OrderSvc "Confirms reserved"
Orders.OrderSvc -> Orders.PaymentSvc "Charges payment"
Orders.PaymentSvc -> Orders.OrderSvc "Confirms charged"
}

view index {
include *
}

CQRS

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


App = system "App" {
CommandAPI = container "Command API"
QueryAPI = container "Query API"
ReadDB = database "Read Database"
WriteDB = database "Write Database"
}

App.CommandAPI -> App.WriteDB "Writes"
App.QueryAPI -> App.ReadDB "Reads"

view index {
include *
}

RAG (Retrieval-Augmented Generation)

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


AIQA = system "AI Q&A" {
Indexer = container "Indexer"
Retriever = container "Retriever"
Generator = container "Generator"
VectorDB = database "Vector Store"
}

AIQA.Indexer -> AIQA.VectorDB "Writes embeddings"
AIQA.Retriever -> AIQA.VectorDB "Searches"
AIQA.Generator -> AIQA.Retriever "Fetches contexts"

See book/valid-examples/pattern-rag-pipeline.sruja for a production-ready model.

Agentic Orchestration

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


AgentSystem = system "Agent System" {
Orchestrator = container "Agent Orchestrator"
Planner = container "Planner"
Executor = container "Executor"
Tools = container "Tooling API"
Memory = database "Long-Term Memory"
}

AgentSystem.Orchestrator -> AgentSystem.Planner "Plans tasks"
AgentSystem.Orchestrator -> AgentSystem.Executor "Executes steps"
AgentSystem.Executor -> AgentSystem.Tools "Calls tools"
AgentSystem.Executor -> AgentSystem.Memory "Updates state"

view index {
include *
}

See book/valid-examples/pattern-agentic-ai.sruja for a complete agent graph.

Sruja Cheatsheet

Elements

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

User = person "User"
App = system "App" {
  Web = container "Web"
  API = container "API"
  DB = database "DB"
}
User -> App.Web "Uses"
App.Web -> App.API "Calls"
App.API -> App.DB "Reads/Writes"

view index {
  include *
}

Tip

The import { * } from 'sruja.ai/stdlib' line provides all standard kinds. You can also declare kinds manually if needed: person = kind "Person", system = kind "System", etc.

Component

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

App = system "App" {
  Web = container "Web" {
    Cart = component "Cart"
  }
}

Scenario

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

User = person "User"

App = system "App" {
  Web = container "Web"
  API = container "API"
  DB = database "Database"
}

scenario Checkout "Checkout Flow" {
  User -> App.Web "adds items"
  App.Web -> App.API "validates"
  App.API -> App.DB "stores order"
}

Deployment

<!-- partial -->
deployment Prod {
  node Cloud {
    node Region {
      node Service {
        containerInstance App.Web
      }
    }
  }
}

Try it

Use the VS Code extension to paste these snippets into a .sruja file and see the diagram preview.

Sruja Adoption Guide

Using Sruja in your repo

For a short, practical guide (install CLI, add to your project, CI, AI, multi-repo), see Using Sruja in your project. The rest of this adoption guide helps you evaluate fit and plan rollout.

Is Sruja Right for Your Organization?

Quick Self-Assessment

Answer these questions to determine if Sruja addresses your needs:

Architecture & Documentation Pain Points

• Do your architecture diagrams become outdated within weeks?
• Do engineers spend significant time maintaining documentation?
• Is there confusion about "the latest architecture diagram"?
• Do new engineers struggle to understand system architecture?
• Are architectural decisions lost when senior engineers leave?

If 3+ are "Yes" → Sruja can help

Compliance & Governance Needs

• Do you need to comply with regulations (HIPAA, SOC2, PCI-DSS, GDPR)?
• Are compliance audits time-consuming and risky?
• Do you struggle to prove architectural controls meet requirements?
• Are security policies documented but not enforced?
• Do you need to demonstrate compliance to auditors?

If 2+ are "Yes" → Sruja's policy-as-code is valuable

Technical Architecture Challenges

• Do you have microservices that need governance?
• Are you experiencing architectural drift (implementation vs. design)?
• Do you need to enforce service boundaries and dependencies?
• Are circular dependencies causing issues?
• Do you need to generate infrastructure from architecture?

If 2+ are "Yes" → Sruja's validation and enforcement help

DevOps & Engineering Culture

• Do you use Git/GitOps workflows?
• Do you have CI/CD pipelines?
• Do you value "everything as code" (IaC, GitOps)?
• Do you want architecture changes in PR reviews?
• Do you need architecture to integrate with Terraform/Istio/etc.?

If 3+ are "Yes" → Sruja fits your workflow

Organization Size & Maturity

Sruja is ideal for:

• ✅ Startups (10-50 engineers): Fast scaling, need consistency
• ✅ Scale-ups (50-200 engineers): Managing complexity, compliance needs
• ✅ Enterprises (200+ engineers): Governance, compliance, knowledge management

Sruja may not be ideal if:

• ❌ You have < 5 engineers (overhead may outweigh benefits)
• ❌ You don't use version control or CI/CD
• ❌ You prefer visual-only tools (no code/DSL)
• ❌ You have no compliance or governance requirements

Decision Framework

Step 1: Define Your Goals

What problem are you trying to solve?

Action: Rank your top 3 goals. Sruja should address at least 2.

Step 2: Calculate Value & ROI

Note: Sruja is free and open source. This ROI calculation measures time savings and value, not purchase cost.

Quick Value Calculator:

Time Savings = (Engineers × Hours/Week × 0.7) × 50 weeks × $100/hour
Onboarding Savings = (New Engineers/Year × 2 weeks × 0.5) × $150k/year ÷ 50
Risk Reduction = Compliance Failures Avoided × $100k

Total Value = Time Savings + Onboarding + Risk Reduction

Example (10 senior engineers, 20 new engineers/year):

• Time: 10 × 4 hours × 0.7 × 50 × $100 = $140k/year
• Onboarding: 20 × 2 × 0.5 × $150k ÷ 50 = $60k/year
• Risk: 1 failure avoided = $100k (one-time)
• Total Value: $200k+ per year

ROI: Since Sruja is free, ROI is essentially infinite - you get value with zero cost.

Step 3: Assess Technical Fit

Evaluate your technical stack:

Action:

• If you need Git/CI/CD integration → ✅ Ready now
• If you need Terraform/Istio/OPA → 🚧 On roadmap (see Roadmap Discussions) — you can pilot with current features now

Evaluation Process

Phase 1: Discovery (Week 1)

Activities:

1. Review Sruja documentation
2. Install CLI: curl -fsSL https://sruja.ai/install.sh | bash (or from Git: cargo install sruja-cli --git https://github.com/sruja-ai/sruja; or build from source: git clone https://github.com/sruja-ai/sruja.git && cd sruja && make build)
3. Model a simple existing system
4. Install VS Code extension for syntax highlighting and diagnostics

Deliverable: Understanding of Sruja capabilities

Phase 2: Proof of Concept (Weeks 2-4)

Activities:

1. Model 1-2 real systems in Sruja
2. Integrate validation into CI/CD
3. Document architecture decisions as ADRs
4. Measure time savings

Success Criteria:

• Can model systems accurately
• Validation catches real issues
• Team sees value
• Time savings measurable

Deliverable: PoC report with value estimate

Phase 3: Pilot (Months 2-3)

Activities:

1. Roll out to 1-2 teams
2. Establish best practices
3. Create internal documentation
4. Measure compliance improvements

Success Criteria:

• Architecture stays current
• Compliance validation working
• Team adoption > 80%
• Positive value demonstrated

Deliverable: Pilot report with go/no-go recommendation

Decision Checklist

Must-Have Requirements

• Problem Fit: Sruja addresses 2+ of your top goals
• Value Positive: Calculated value > $100k/year (or equivalent time savings)
• Technical Fit: Git/CI/CD integration available (or roadmap acceptable)
• Team Readiness: Team comfortable with code-based tools
• Leadership Support: Time allocated for adoption (no budget needed - Sruja is free)

Nice-to-Have Requirements

• Advanced features needed (Terraform, Istio, OPA)
• Compliance requirements (HIPAA, SOC2, PCI-DSS)
• Large team (100+ engineers)
• Microservices architecture

Decision Matrix

Decision Rule:

• > 4.0: Strong fit → Proceed with pilot
• 3.5-4.0: Good fit → Consider pilot
• < 3.5: Weak fit → Reassess or wait

Common Concerns & Objections

"We already have architecture documentation"

Response: Sruja doesn't replace documentation — it makes it executable. Your documentation becomes code that:

• Stays current (version-controlled)
• Validates automatically
• Enforces policies
• Integrates with DevOps

"Our team isn't technical enough for a DSL"

Response: Sruja's DSL is designed for all developers:

• 1st-year CS students productive in 10 minutes
• Progressive disclosure (simple → advanced)
• Rich error messages guide users
• VS Code extension with full LSP support (autocomplete, go-to-definition, rename, find references, and more) - see VS Code Extension Guide

"We don't have compliance requirements"

Response: Sruja provides value beyond compliance:

• Faster onboarding (50% reduction)
• Reduced documentation time (20-30%)
• Architectural validation (prevents drift)
• Knowledge preservation

"The roadmap features we need aren't ready"

Response:

• Core features (validation, CI/CD) are available now
• Roadmap features (Terraform, Istio, OPA) are planned for Phase 2-3 (see Roadmap Discussions)
• You can start with core features and add advanced later
• Early adoption gives you influence on roadmap priorities

Success Metrics

Track These KPIs

Next Steps

Immediate Actions

1. Complete Self-Assessment (above)
2. Calculate Value (Step 2)
3. Try Sruja (see Getting Started)
4. Join Community (GitHub Discussions)

Decision Timeline

• Week 1: Self-assessment and value calculation
• Week 2-4: Proof of concept
• Month 2-3: Pilot program
• Month 4+: Full rollout (if successful)

Resources

• Getting Started: Getting Started Guide
• Executive Overview: Executive Overview
• Adoption Playbook: Adoption Playbook
• Decision Framework: Quick Decision Framework

Open Source & Community Support

Sruja is free and open source (Apache 2.0 licensed), developed by and for the community. You can:

• Use it freely: No licensing fees or restrictions
• Contribute: Submit PRs, report issues, suggest features
• Extend it: Build custom validators, exporters, and integrations
• Join the community: Participate in GitHub Discussions, share use cases, and learn from others

Professional Services

While Sruja is open source and free to use, professional consulting services are available for organizations that need:

• Implementation support: Help rolling out Sruja across teams and systems
• Best practices guidance: Establish architectural governance patterns and workflows
• Custom integrations: Integrate Sruja with existing CI/CD, infrastructure, and monitoring tools
• Training: Team training on Sruja DSL, validation patterns, and architectural modeling
• Custom development: Build custom validators, exporters, or platform integrations

Contact the team through GitHub Discussions to discuss your needs.

Future Platform Vision

Sruja is designed to evolve into a comprehensive platform for architectural governance:

• Live System Review: Compare actual runtime behavior against architectural models to detect drift and violations.
• Gap Analysis: Automatically identify missing components, undocumented dependencies, and architectural gaps.
• Continuous Validation: Monitor production systems against architectural policies and constraints in real-time.
• Compliance Monitoring: Track and report on architectural compliance across services and deployments.

These capabilities are planned for future releases. The current open source foundation provides the building blocks for this evolution, and community feedback helps shape the roadmap.

Note: This guide helps you evaluate whether Sruja is the right fit for your organization and how to adopt it successfully.

Ready to evaluate Sruja? Start with the Self-Assessment above.

Adoption Playbook

Week 1: Baseline & CI

• Create a minimal architecture.sruja covering core systems.
• Add sruja fmt and sruja lint to CI; fail on violations.
• Export docs: sruja export markdown architecture.sruja.

Week 2: Targets & Guardrails

• Add slo and scale for critical paths.
• Encode constraints and conventions; publish to teams.
• Introduce views for API/Data/Auth focus.

Week 3: Governance & Evolution

• Add policy pages for security/operability.
• Document decisions with adr blocks; track evolution with slo values (target vs current).
• Use Git for automatic change tracking (git log, git diff, version tags).
• Wire linting to PR checks; require green builds.

CI Example (GitHub Actions)

name: sruja
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Lint DSL
        run: sruja lint architecture.sruja
      - name: Export Docs
        run: sruja export markdown architecture.sruja

Success Metrics

• Review cycle time ↓
• Incident rate for architecture errors ↓
• Consistency across services ↑

Note: Sruja is free and open source (Apache 2.0 licensed). Need help with implementation? Professional consulting services are available. Contact the team through GitHub Discussions to learn more.

Using Sruja in Your Project

This guide is for teams and organizations that want to use Sruja in their own repositories to enhance their code: architecture-as-code, validation in CI, and AI-assisted generation with consistent rules.

What you get

• Architecture as code – .sruja files in Git; no separate diagram tool to keep in sync.
• Validation – sruja lint catches undefined refs, circular dependencies, missing fields, orphans.
• AI-friendly – Rules and skills so Cursor, Copilot, etc. generate valid Sruja and better architecture.
• CI – Fail PRs when architecture is invalid; optional export to Markdown/JSON/Mermaid for docs.

1. Install (your machine and/or CI)

CLI

Option A – install script (downloads from GitHub Releases):

curl -fsSL https://sruja.ai/install.sh | bash

Option B – from Git (requires Rust):

cargo install sruja-cli --git https://github.com/sruja-ai/sruja

Option C – build from source:

git clone https://github.com/sruja-ai/sruja.git && cd sruja && make build

Ensure the install directory is on your PATH (install script uses ~/.local/bin by default; Option B uses ~/.cargo/bin; Option C uses target/release).

Check:

sruja --help
sruja lint --help

VS Code extension

Install Sruja Language Support from the VS Code Marketplace (or Open VSX). You get syntax highlighting, LSP diagnostics, and optional diagram preview for .sruja files.

2. Add Sruja to your repo (5 minutes)

Step 1: Create or add architecture

# From your repo root
sruja init my-service
# Creates: my-service.sruja, .cursorrules, .copilot-instructions.md, .architecture-skill.md

Or add a single file, e.g. architecture.sruja or docs/architecture.sruja, and define your systems/containers/relationships (see Language specification and the Examples Gallery).

Step 2: AI editor integration (so AI-generated code follows rules)

The files created by sruja init are enough for most teams:

• .cursorrules – Cursor uses this for Sruja DSL rules.
• .copilot-instructions.md – GitHub Copilot uses this.
• .architecture-skill.md – Short pointer; optional full skill: npx skills add sruja-ai/sruja --skill sruja-architecture.

Commit these so everyone (and CI) has the same setup. See AI editor integration in the repo for details.

Step 3: Validate in CI

In your repo you don't have the Sruja monorepo, so install the CLI in CI from Git, then run lint.

GitHub Actions example:

name: Validate Sruja

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]
  paths:
    - '**/*.sruja'

jobs:
  sruja:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable

      - name: Install Sruja CLI
        run: cargo install sruja-cli --git https://github.com/sruja-ai/sruja --locked

      - name: Lint all .sruja files
        run: |
          find . -name '*.sruja' -not -path './target/*' | while read f; do
            echo "Linting $f"
            sruja lint "$f"
          done

Use --locked so the install matches the lockfile in the Sruja repo for reproducible CI.

Optional – export docs in CI:

      - name: Export architecture to Markdown
        run: |
          for f in $(find . -name '*.sruja' -not -path './target/*'); do
            out="${f%.sruja}.md"
            sruja export markdown "$f" > "$out" || true
          done
      - name: Upload architecture docs
        uses: actions/upload-artifact@v4
        with:
          name: architecture-docs
          path: '**/*.sruja.md'

3. How this enhances your code

4. Using Sruja across multiple repos

• Per-repo – Each repository that owns a service or app can have its own .sruja file(s). Add the same CI job (install CLI from Git + sruja lint) and the same AI files (e.g. copy .cursorrules and .copilot-instructions.md from a template or run sruja init once and commit).
• Central docs repo – Some teams keep a single "docs" or "architecture" repo with one or more .sruja files and run Sruja CI there; link to exported Markdown/JSON from other repos. Other repos don't need the CLI unless they also own architecture files.
• Shared rules – Use the same sruja-architecture skill (npx skills add sruja-ai/sruja --skill sruja-architecture) across repos so AI and humans share the same patterns and trade-offs.

5. Where to go next

• Language specification – Language specification (full DSL reference in this book)
• AI editors and catching bugs – AI editor integration in the repo
• Reviewing AI-generated code – Reviewing AI-generated code in the repo
• Adoption and rollout – Adoption guide and Adoption playbook in this book
• Examples – Examples Gallery (canonical book-backed examples)

Sruja is open source. To report issues or suggest improvements, use GitHub Issues or Discussions.

Sruja Design Philosophy: The Unified Intuitive DSL

Objective

Create a modeling language that empowers all developers - from students to enterprise architects - to design systems with confidence, while naturally guiding them toward simplicity and preventing over-engineering.

Core Principles:

1. Start simple, stay simple: A 1st-year CS student should be productive in 10 minutes, and advanced developers should be guided away from unnecessary complexity.
2. Empower, don't restrict: The language should enable all developers, not limit them, but guide them toward good design.
3. Approachability first: Complex concepts should be available but not encouraged unless truly needed.
4. Prevent over-engineering: The language itself should make simple designs easier than complex ones.
5. Systems thinking made simple: Enable holistic system understanding through intuitive syntax, without requiring complex theory.

Methodology Analysis

The "Unified" Proposal

We need a set of keywords that map to these concepts without forcing the user to learn the specific theory first. The language should support progressive disclosure: simple concepts first, advanced concepts when needed.

1. Grouping (The "Container")

Problem: Different methodologies use different terms for logical boundaries.

Decision:

• module: Primary keyword for logical grouping. Familiar to Python/JS/Go developers.
• container: For C4-style technical containers (deployment units).

Rationale: module is the most universal term. Students learn "modules" in their first programming course.

2. The "Thing" (Data Structure)

Problem: Entity vs Value Object vs Table vs Struct - all represent "data" but with different semantics.

Decision: data is the unified keyword.

Rules:

• If data has an id field → Implicitly an Entity (has identity)
• If data has no id → Implicitly a Value Object (value-based)
• If data is in a datastore → Implicitly a database table
• If data is in an api → Implicitly a request/response schema

Rationale: Students understand "data" immediately. The semantics emerge from context, not explicit keywords.

3. The "Action" (Behavior/Event)

Problem: Different types of actions need different modeling approaches.

Decision:

• api: Explicit API endpoints (students understand "API")
• event: Events (something that happened)
• Component behavior: Implicit (components contain behavior)

Rationale: Students learn APIs early. Events are intuitive ("something happened").

4. Relationships

Problem: How to model connections between elements?

Decision: Use arrow syntax -> for relationships.

User -> ShopAPI.WebApp "Uses"
ShopAPI.WebApp -> ShopAPI.Database "Reads/Writes"
Order -> Payment "Triggers"

Rationale: Arrows are universal. Everyone understands "A -> B" means "A relates to B".

Proposed Syntax: "The Universal Model"

Level 1: Beginner (C4 Style)

// Element kinds
person = kind "Person"
system = kind "System"
container = kind "Container"

// Elements
user = person "End User"

shop = system "Shop API" {
    webApp = container "Web Application" {
        technology "React"
    }

    db = container "PostgreSQL Database" {
        technology "PostgreSQL 14"
    }
}

// Relationships
user -> shop.webApp "Uses"
shop.webApp -> shop.db "Reads/Writes"

Level 2: Intermediate (Detailed Architecture)

// Element kinds
system = kind "System"
container = kind "Container"
component = kind "Component"
database = kind "Database"

// Architecture
ShopAPI = system "Shop API" {
    WebApp = container "Web Application" {
        technology "React"
        Cart = component "Shopping Cart"
        Checkout = component "Checkout Service"
    }

    API = container "API Gateway" {
        technology "Node.js"
    }

    DB = database "PostgreSQL Database" {
        technology "PostgreSQL 14"
    }
}

// Relationships
ShopAPI.WebApp -> ShopAPI.API "Calls"
ShopAPI.API -> ShopAPI.DB "Reads/Writes"

Level 3: Advanced (Governance + Operations)

// Element kinds
person = kind "Person"
system = kind "System"
container = kind "Container"
database = kind "Database"

// Elements
Customer = person "Customer"

Shop = system "E-commerce Shop" {
    description "High-performance e-commerce platform"

    API = container "API Gateway" {
        technology "Node.js"
        slo {
            latency {
                p95 "200ms"
                p99 "500ms"
            }
        }
        scale {
            min 3
            max 10
        }
    }

    DB = database "PostgreSQL" {
        technology "PostgreSQL 14"
    }
}

// Governance
R1 = requirement functional "Must support 10k concurrent users"
SecurityPolicy = policy "Encrypt all data" category "security" enforcement "required"

// Relationships
Customer -> Shop.API "Uses"
Shop.API -> Shop.DB "Reads/Writes"

Key Design Decisions

1. Progressive Disclosure

• Beginner: Start with system, container, component (C4)
• Intermediate: Add module, data, api, event (Unified)
• Advanced: Use all features together for complex architectures

Rationale: Students can start simple and learn advanced concepts when needed.

2. Arrays: DOD-Style Syntax

Support [] syntax (e.g., items OrderItem[]) instead of just implied relationships.

Rationale: Very familiar to programmers. Makes data structures explicit.

3. Unified data Keyword

The data keyword represents data structures. The presence of an id field indicates an entity with identity.

Rationale: Reduces cognitive load. Students can model data structures without learning complex theory.

4. Explicit api Keyword

Model APIs alongside data to connect "Backend" to "Database".

Rationale: Students understand "APIs". This bridges the gap between data modeling and API design.

5. Context-Aware Semantics

The same keyword (data) means different things in different contexts:

• In a module: Domain model
• In a datastore: Database table
• In an api: Request/response schema
• In a component: Internal data structure

Rationale: One keyword, multiple interpretations based on context. Reduces vocabulary size.

Preventing Over-Engineering: Simplicity by Design

How Sruja Guides Toward Simplicity

1. Start Simple

• Use system for technical/deployment modeling (C4 style)
• Use module for logical grouping when needed
• Keep it simple - don't add complexity unless necessary

2. Progressive Disclosure

• Start with basic C4 concepts: system, container, component
• Add module, data, api, event when you need more detail
• Use only what you need for your use case

3. Natural Constraints

• system syntax is straightforward for deployment modeling
• The language guides you to use the right level of detail
• Simple designs are easier to write than complex ones

4. Validation & Guidance (Future)

• Warn if over-engineering simple systems
• Help users choose the right level of detail
• Guide toward simplicity

5. Clear Mental Models

• system = "How is this deployed?" (Physical/Technical)
• module = "How is this organized?" (Logical grouping)
• Keep it focused on what you're actually modeling

Missing Concepts & Future Considerations

Currently Missing (but important):

1. Constraints/Validation: How to express "email must be valid", "age > 0"?
2. Relationships with Cardinality: User -> Order[1:*] (one-to-many)?
3. Inheritance/Polymorphism: How to model "Payment extends Transaction"?
4. Enums: status: OrderStatus where OrderStatus = [PENDING, COMPLETED, CANCELLED]
5. Optional Fields: email?: string vs email string
6. Defaults: status string = "PENDING"
7. Computed Fields: total: float = items.sum(price * qty)

Recommendations:

• Add enum keyword for enumerations
• Support ? for optional fields: email? string
• Support = for defaults: status string = "PENDING"
• Consider constraint keyword for validation rules
• Consider relationship syntax: User -> Order[1:*]
• ✅ flow and scenario/story already implemented for flow thinking (DFD and BDD-style)

Migration Path

From C4 to Sruja:

<!-- partial -->
// C4: System Context
system "E-Commerce System" {
    // C4: Container
    container "Web Application" {
        // C4: Component
        component "Order Controller"
    }
}

From Data Modeling to Sruja:

<!-- partial -->
// Data structures
module Orders {
    data Order {
        id string
        items OrderItem[]
    }

    data OrderItem {
        product_id string
        qty int
    }

    data ShippingAddress {
        street string
        city string
    }
}

From ER to Sruja:

<!-- partial -->
datastore Database {
    data User {
        id string
        email string
    }

    data Order {
        id string
        user_id string  // Foreign key relationship
    }
}

Systems Thinking: Simple and Intuitive

Goal: Empower developers to think about systems holistically - understanding how parts interact, boundaries, and emergent behavior - without requiring complex theory.

Core Systems Thinking Concepts (Simplified)

Systems thinking is about understanding:

1. Parts and Relationships: How components connect and interact
2. Boundaries: What's inside vs outside the system
3. Flows: How information/data moves through the system
4. Feedback Loops: How actions create reactions
5. Context: The environment the system operates in

How Sruja Makes Systems Thinking Simple

1. Parts and Relationships (Already Built-In)

<!-- partial -->
system ShopAPI {
    container WebApp
    container Database
}

ShopAPI.WebApp -> ShopAPI.Database "Reads/Writes"

Simple Insight: Just draw boxes and connect them with arrows. The relationships show how parts interact.

2. Boundaries (Natural in Sruja)

<!-- partial -->
system ShopAPI {  // Inside boundary
    container WebApp
}

person User  // Outside boundary
User -> ShopAPI "Uses"

Simple Insight: system defines the boundary. person and external systems are outside. Clear and intuitive.

3. Flows (Built-In Flow Syntax)

<!-- partial -->
// Data Flow Diagram (DFD) style — use scenario
scenario OrderProcess "Order Processing" {
    Customer -> Shop.WebApp "Order Details"
    Shop.WebApp -> Shop.Database "Save Order"
    Shop.Database -> Shop.WebApp "Confirmation"
}

// User Story/Scenario style
story Checkout "User Checkout Flow" {
    User -> ECommerce.CartPage "adds item to cart"
    ECommerce.CartPage -> ECommerce "clicks checkout"
    ECommerce -> Inventory "Check Stock"
}

// Or using simple qualified relationships
Customer -> Shop.WebApp "Submits Order"
Shop.WebApp -> Shop.OrderService "Processes"
Shop.OrderService -> Shop.PaymentService "Charges"

Simple Insight: Use flow for data flows (DFD), story/scenario for user stories, or simple relationships for basic flows. Events show what happens: event OrderPlaced.

4. Feedback Loops (Cycles in Relationships)

<!-- partial -->
// Simple feedback: User action triggers system response
User -> System "Requests"
System -> User "Responds"

// System feedback: Component A affects Component B, which affects A
ComponentA -> ComponentB "Updates"
ComponentB -> ComponentA "Notifies"

// Event-driven cycles: Service A triggers Service B, which triggers A
ServiceA -> ServiceB "Sends Event"
ServiceB -> ServiceA "Responds with Event"

// Mutual dependencies: Microservices that call each other
OrderService -> PaymentService "Charges Payment"
PaymentService -> OrderService "Confirms Payment"

Simple Insight: When arrows form a cycle, that's a feedback loop. The system responds to itself. Cycles are valid in many architectures:

• Feedback loops: User interactions, system responses
• Event-driven patterns: Services triggering each other via events
• Mutual dependencies: Microservices that need to communicate bidirectionally
• Bidirectional flows: API <-> Database (read/write operations)

Note: Sruja allows cycles - they're a natural part of system design. The validator will inform you about cycles but won't block them, as they're often intentional architectural patterns.

5. Context (Persons and External Systems)

<!-- partial -->
person Customer "End User"
person Admin "System Administrator"

system PaymentGateway "Third-party service" {
  tags ["external"]
}

Customer -> ShopAPI "Uses"
ShopAPI -> PaymentGateway "Processes payments"

Simple Insight: person and external show the context - who/what the system interacts with.

Progressive Systems Thinking

Beginner: Just model the parts and connections

// Element kinds
system = kind "System"
container = kind "Container"

// Elements
myApp = system "MyApp" {
    frontend = container "Frontend"
    backend = container "Backend"
}

// Relationships
myApp.frontend -> myApp.backend "Calls"

Intermediate: Add flows and events

<!-- partial -->
// Simple qualified relationships
user -> myApp.frontend "Clicks"
myApp.frontend -> myApp.backend "Sends request"
myApp.backend -> myApp.database "Saves"

// DFD-style — use scenario
```sruja
<!-- partial -->
scenario OrderFlow "Order Processing" {
    user -> myApp.frontend "Submits"
    myApp.frontend -> myApp.backend "Processes"
    myApp.backend -> myApp.database "Stores"
}

Advanced: Model feedback loops and system behavior

<!-- partial -->
// Feedback loop: User action -> System response -> User sees result
story CompleteOrder "Order Completion Flow" {
    user -> shop.system "Submits"
    shop.system -> shop.database "Stores"
    shop.system -> user "Confirms"
}

// Complex flow with multiple steps — use scenario
scenario PaymentFlow "Payment Processing" {
    orders.orderService -> orders.paymentGateway "Charge"
    orders.paymentGateway -> orders.orderService "Confirms"
    orders.orderService -> user "Notifies"
}

Key Principle: No Jargon Required

• Don't say: "Model the feedback loop using systems thinking principles"
• Do say: "Use flow or story to show how data/actions move through the system"
• Don't say: "Define the system boundary using context mapping"
• Do say: "Use system to show what's inside, person to show who uses it"
• Don't say: "Create a DFD (Data Flow Diagram)"
• Do say: "Use flow to show how data moves between components"

Result: Developers naturally think in systems without learning theory first. The syntax guides them to see:

• How parts connect (relationships: ->)
• What's inside vs outside (boundaries: system vs person/external)
• How things flow (flow for data flows, story/scenario for user stories, or simple -> relationships)
• How actions create reactions (cycles in relationships, feedback in flows)

Additional Design Philosophy Assessment

After assessing various design philosophies (Event-Driven Architecture, Hexagonal Architecture, CQRS, BDD, Reactive Systems, etc.) through a strict lens of "does this help developers learn system design?", we found:

✅ Accepted: Simple & Valuable

1. ✅ Flows and Scenarios: Already implemented! flow for data flows (DFD), scenario/story for user stories (BDD-style Given-When-Then)
2. Optional Fields: Practical data modeling (email? string)
3. Enums: Practical data modeling (status: OrderStatus)

❌ Rejected: Too Complex or Unnecessary

• Hexagonal Architecture (Ports & Adapters) - Too abstract
• Clean Architecture / Layers - Too theoretical
• CQRS - Too specialized, can use existing api
• Advanced Event-Driven - Current event is sufficient
• Reactive Systems - Too complex
• Actor Model - Too specialized
• GraphQL/Protocol Buffers - Technology-specific
• Semantic Web - Overkill
• SOLID (as syntax) - Principles, not syntax

Note: Systems thinking is accepted - but implemented simply through existing syntax (relationships, boundaries, flows). No new keywords needed.

Key Finding: Most "advanced" concepts should be rejected. Only 3 simple additions are recommended, and everything else can wait until developers master the basics. Systems thinking is naturally supported through intuitive syntax.

Conclusion

By using system, module, data, api, and event, we cover 90% of use cases with words that a 1st-year CS student already knows.

Key Success Metrics:

• ✅ Can a beginner model a simple system in 10 minutes? Yes (C4 style)
• ✅ Can an intermediate model data + APIs? Yes (Unified style)
• ✅ Can an advanced user model complex architectures? Yes (Extended features)
• ✅ Does it prevent over-engineering? Yes (simplicity by design)
• ✅ Is it approachable for all developers? Yes (progressive disclosure)

Next Steps:

1. Add enum support
2. Add optional fields (? syntax)
3. Add relationship cardinality
4. Add constraint/validation syntax
5. ✅ flow and scenario/story already implemented - enhance documentation and examples
6. Improve error messages for beginners
7. Add validation rules to guide simplicity

Key Principle: Less is more. Don't add complexity unless it clearly helps developers learn system design better. The goal is to build confidence through simplicity, not complexity through features.

Glossary

Quick reference for technical terms and concepts used throughout Sruja documentation.

A

ADR (Architecture Decision Record)

A document that captures an important architectural decision made along with its context and consequences. In Sruja, ADRs are defined using the adr keyword and can be linked to specific architecture elements.

Example:

ADR001 = adr "Use Microservices" {
  status "Accepted"
  context "Need to scale independently"
  decision "Adopt microservices architecture"
  consequences "Increased complexity but better scalability"
}

Architecture-as-Code

The practice of defining software architecture using code (text-based DSL) instead of static diagrams. This enables version control, validation, and automated documentation generation.

C

C4 Model

A hierarchical model for visualizing software architecture, created by Simon Brown. It consists of four levels:

• Level 1 (Context): System context diagram showing the system and its users
• Level 2 (Container): Container diagram showing high-level technical building blocks
• Level 3 (Component): Component diagram showing internal structure of containers
• Level 4 (Code): Code-level diagram (typically managed by IDEs, not Sruja)

Sruja is based on the C4 model and automatically generates C4-compliant diagrams.

Component

A structural element within a container that represents a major building block. Components are optional and provide additional detail when needed.

Example:

App = system "App" {
  API = container "API" {
    Auth = component "Authentication"
    Payment = component "Payment Processing"
  }
}

Container

A deployable unit within a system. In C4 terminology, a container is NOT a Docker container, but rather any separately deployable unit like:

• Web applications
• Mobile apps
• Server-side applications
• Databases
• File systems

Example:

App = system "E-commerce" {
  Web = container "React App"
  API = container "Node.js API"
  DB = database "PostgreSQL"
}

D

Database

A type of container that represents a data store. In Sruja, databases are defined using the database keyword.

Example:

DB = database "PostgreSQL"

Note: Sruja also supports datastore as an alias, but database is the recommended term.

DSL (Domain-Specific Language)

A programming language specialized for a particular domain. Sruja DSL is a text-based language specifically designed for defining software architecture.

E

Element

Any architectural construct in Sruja: person, system, container, component, database, queue, etc. Elements are the building blocks of your architecture model.

K

Kind

A type definition for elements. Kinds can be imported from the standard library (import { * } from 'sruja.ai/stdlib') or declared manually for custom types.

Example:

// Using stdlib (recommended)
import { * } from 'sruja.ai/stdlib'

// Or declaring manually
microservice = kind "Microservice"

M

Metadata

Additional information attached to elements, such as team ownership, tier, or custom tags. Metadata helps with governance and organization.

Example:

App = system "My App" {
  metadata {
    team "Platform"
    tier "critical"
  }
}

P

Person

An actor or user of the system. Persons are defined at the context level and represent external users or roles.

Example:

User = person "Customer"
Admin = person "Administrator"

Q

Queue

A message queue or event stream used for asynchronous communication between containers.

Example:

EventQueue = queue "Kafka Topic"

R

Relation

A connection between two elements, showing how they interact. Relations are defined using the -> operator.

Example:

<!-- partial -->
User -> App.Web "Visits"
App.Web -> App.API "Calls"

Requirement

A functional or non-functional requirement that can be linked to architecture elements using tags. Requirements help trace business needs to technical implementation.

Example:

R001 = requirement "User Authentication" {
  description "Users must be able to log in securely"
  tags ["App.Web", "App.API"]
}

S

Scenario

A sequence of interactions that describe how users or systems interact to accomplish a goal. Scenarios help document user flows and system behavior.

Example:

<!-- partial -->
scenario Checkout "Checkout Flow" {
  User -> App.Web "adds items to cart"
  App.Web -> App.API "validates cart"
  App.API -> App.DB "stores order"
}

System

The highest-level element in C4 Level 1. A system represents a software system that delivers value to its users.

Example:

ECommerce = system "E-commerce Platform" {
  description "Online shopping platform"
}

stdlib (Standard Library)

The Sruja standard library that provides common element kinds (person, system, container, database, etc.). Importing from stdlib is the recommended way to use standard types.

Example:

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

T

Tag

A label that can be attached to elements, requirements, or ADRs to enable filtering, grouping, and traceability.

Example:

App = system "My App" {
  tags ["production", "critical"]
}

V

View

A diagram perspective that shows a subset of the architecture. Views can be explicit (defined with view blocks) or implicit (automatically generated by Sruja).

Example:

view index {
  title "Complete System View"
  include *
}

Related Resources

• C4 Model Documentation
• DSL Syntax Reference
• Getting Started Guide

Documentation Style Guide

Goals

• Align with the Diátaxis framework: Tutorials, How‑to Guides, Reference, Explanation
• Improve clarity, consistency, and task‑orientation
• Raise quality to industry standards (Stripe, React, Kubernetes, MDN)

Front Matter

• Required: title, summary
• Recommended: prerequisites, learning_objectives, estimated_time, difficulty, tags, last_updated

Headings

• Use Title Case for H1/H2/H3
• Keep headings unique; avoid duplicates within a page

Code Blocks

• Always specify language fences: bash, sh, json, yaml, go, ts, tsx, md, sruja
• Prefer copy‑ready commands; avoid interactive prompts where possible

Admonitions

• Use standard callouts: Note, Tip, Warning
• Keep callouts short and action‑oriented

Links

• Prefer descriptive link text (not raw URLs)
• Cross‑link to Reference and Examples when teaching a concept or task

Images & Diagrams

• Include small screenshots or diagram previews for expected outcomes
• Use alt text that describes the intent and context

Tutorials

• Structure: Overview → Prerequisites → Steps → Outcome → Troubleshooting → Next Steps
• Include at least one end‑to‑end task with an expected output

How‑to Guides

• Task‑oriented and concise
• Structure: Purpose → Steps → Validation → References

Reference

• Precise, complete, and skimmable tables/lists
• Avoid narrative; link outward to tutorials for workflows

Explanation

• Conceptual background, rationale, trade‑offs
• Link to reference for details and to tutorials for practice

Quality Gates

• Markdown lint for headings, lists, links
• Link checking for external and internal links
• Optional accessibility lint (alt text, heading levels)

Review Checklist

• Front matter present and complete
• Headings consistent and unique
• Code fences have language tags
• Cross‑links added to relevant Reference/Examples
• Outcome preview or screenshot included where appropriate

Sruja Community

Welcome to the Sruja community! Sruja is an open source project built by and for developers who care about software architecture. Whether you're here to learn, contribute, or get help, we're glad you're here.

Join the Conversation

💬 GitHub Discussions

For longer-form discussions, feature requests, and Q&A:

GitHub Discussions

GitHub Discussions is ideal for:

• Feature proposals and RFCs
• Technical discussions
• Sharing tutorials and examples
• Asking detailed questions

🐛 GitHub Issues

Found a bug or have a feature request?

Open an Issue

Ways to Contribute

Sruja is an open source project, and we welcome contributions of all sizes! There are many ways to contribute, even if you're not a developer.

No Code Required

Documentation

• Fix typos or improve clarity
• Add examples and tutorials
• Translate documentation
• Write blog posts or courses

Testing & Feedback

• Test new features and report bugs
• Share your use cases
• Provide feedback on design decisions
• Help improve error messages

Community

• Answer questions in Discussions
• Help newcomers get started
• Share your Sruja projects and experiences

Beginner-Friendly Code

Small Improvements

• Add test cases
• Fix small bugs
• Improve error messages
• Add examples to book/valid-examples/ and a matching page under book/src/examples/
• Improve CLI help text

Documentation Code

• Add code examples
• Update API documentation
• Create tutorials

More Advanced Contributions

Features & Enhancements

• Implement new features
• Add new export formats
• Add validation rules
• Improve tooling and developer experience

Core Development

• Work on the language parser
• Enhance the validation engine
• Build platform integrations
• Develop plugins and extensions

Getting Started with Contributions

🎯 First Time Contributing?

Start here: Contribution Guide

This step-by-step guide walks you through:

• Finding your first issue
• Setting up your development environment
• Making and submitting changes
• Getting help when stuck

Quick Links

• 💡 Contribution Ideas: Browse Good First Issues
• 🐛 Find Issues: Good First Issues
• 📖 Full Guide: Contribution Guide
• 📝 Content Guide: Documentation Style Guide

Contribution Workflow

1. Fork and Branch: Fork the repo and create a topic branch
2. Implement: Make your changes and test locally
3. Commit: Follow Conventional Commits
4. Pull Request: Open a PR with a clear description
5. Review: Address feedback and iterate
6. Merge: Once approved, your contribution is merged!

For detailed instructions, see the Contribution Guide.

Roadmap & Transparency

Sruja is developed transparently with community input. Our roadmap is public and open for discussion.

Current Roadmap

View Roadmap Discussions

The roadmap outlines our path to v1.0, including:

• Advanced Governance & Compliance: Policy as code, architectural guardrails
• Production Reality & Data Flow: Service mesh integration, runtime verification
• Extensibility & Ecosystem: Plugin system, DevOps integrations
• Platform Evolution: Live system review, gap detection, violation monitoring

Shaping the Roadmap

Your feedback shapes the roadmap! We welcome:

• Feature requests via GitHub Discussions
• Use case sharing to prioritize features
• RFCs (Request for Comments) for major changes
• Community voting on priorities

Community Expectations

We're committed to maintaining a welcoming and respectful community. When participating:

• Be respectful and constructive: Treat everyone with kindness
• Provide actionable feedback: Help others improve their contributions
• Prefer documented decisions: Link to ADRs or issues when relevant
• Start small: You can always contribute more later!

Recognition

We value all contributions, big and small. Contributors are recognized through:

• GitHub contributor list
• Release notes (for significant contributions)
• Community highlights in discussions

Professional Services

While Sruja is open source and free to use, professional consulting services are available for organizations that need:

• Implementation support: Help rolling out Sruja across teams
• Best practices guidance: Establish architectural governance patterns
• Custom integrations: Integrate with existing CI/CD and infrastructure
• Training: Team training on Sruja DSL and architectural modeling
• Custom development: Build custom validators, exporters, or integrations

Contact the team through GitHub Discussions to discuss your needs.

Resources

Documentation

• Getting Started: Install and create your first model
• Concepts: Learn Sruja's core concepts
• Reference: Language syntax and patterns
• Tutorials: Step-by-step guides

Development

• Repository: Code, issues, and discussions

Community

• GitHub Discussions: Longer-form discussions
• GitHub Issues: Bug reports and feature requests

Get Involved Today

Ready to contribute? Here are some quick ways to get started:

1. Join Discussions and introduce yourself
2. Star the repository on GitHub to show your support
3. Fix a typo in the documentation
4. Add an example to book/valid-examples/ and a matching page under book/src/examples/
5. Share your use case in GitHub Discussions

Every contribution, no matter how small, helps make Sruja better for everyone. Thank you for being part of the community!

Questions? Reach out on GitHub Discussions. We're here to help!

Courses

Structured courses to learn architecture-as-code with Sruja, from fundamentals to production patterns.

Start with Systems Thinking 101 or System Design 101 if you're new; use the Beginner path to combine courses with tutorials and challenges.

Systems Thinking 101

Learn to model systems holistically with Sruja. Master the five core systems thinking concepts: parts and relationships, boundaries, flows, feedback loops, and context.

Course Overview

Systems thinking helps you understand how components interact as part of a whole. This course teaches you to model systems using Sruja's architecture-as-code approach, enabling you to visualize and validate complex system interactions.

What You'll Learn

• Module 1: Fundamentals - Core systems thinking concepts and why they matter
• Module 2: Parts and Relationships - Model components and their interactions
• Module 3: Boundaries - Define what's inside vs. outside your system
• Module 4: Flows - Visualize data and information movement through the system
• Module 5: Feedback Loops - Model cycles and reactive behaviors
• Module 6: Context - Capture the environment, dependencies, and stakeholders

Prerequisites

• Basic familiarity with Sruja DSL (or complete CLI Basics)
• Understanding of C4 Model concepts

Learning Path

Each module contains hands-on examples with Sruja syntax. You'll write .sruja files, validate them with sruja lint, and export to Mermaid diagrams with sruja export mermaid.

Why Systems Thinking?

• Holistic understanding: See the whole system, not just parts
• Natural patterns: Model real-world interactions and feedback
• Clear boundaries: Understand what's in scope vs. context
• Flow visualization: See how data and information move
• Valid cycles: Feedback loops are natural, not errors

Course Duration

Approximately 6-8 hours to complete all modules and exercises.

Next Steps

Start with Module 1: Fundamentals or review the Beginner path for a complete learning journey.

Module 1: Fundamentals

Overview

In this module, you'll learn the core concepts of systems thinking and how they apply to software architecture modeling with Sruja.

Learning Objectives

By the end of this module, you'll be able to:

• Define what systems thinking is and why it matters for software architecture
• Identify the five core systems thinking concepts
• Understand how Sruja supports systems thinking principles
• Recognize when to use systems thinking in your architecture work

Lessons

• Lesson 1: Introduction to Systems Thinking - What is systems thinking and why it matters for architecture (2 min)
• Lesson 2: The Iceberg Model - Understanding events, patterns, structures, and mental models (2 min)
• Lesson 3: Systems in Software Architecture - Every system is a system of systems (2 min)
• Lesson 4: Parts & Relationships - Model components and their interactions (2 min)
• Lesson 5: Boundaries - What's inside vs. outside your system (2 min)
• Lesson 6: Flows - Visualize data and information movement (2 min)
• Lesson 7: Feedback Loops - How systems respond, adapt, and self-regulate (2 min)
• Lesson 8: Context - Capture environment, dependencies, and constraints (2 min)

Prerequisites

• Basic understanding of software architecture concepts
• Familiarity with Sruja DSL basics

Time Investment

Approximately 20-25 minutes to complete all lessons (8 lessons × 2-3 minutes each, including quizzes).

What's Next

After completing this module, you'll dive into specific concepts starting with Module 2: Parts and Relationships.

Lesson 1: Introduction to Systems Thinking

Learning Goal

Understand the basic concept of systems thinking and its importance in architecture.

What is Systems Thinking?

Systems thinking is a holistic approach to understanding how components interact as part of a whole. Instead of looking at parts in isolation, it focuses on relationships, patterns, and emergent behaviors that arise when components work together.

Traditional architecture often takes a reductionist approach: break systems into parts, understand each part, then put them together. But this misses the magic—the interactions that emerge only when parts work together.

A Simple Example: Coffee Shop

Think of a coffee shop:

Isolated view (reductionist):

• Coffee machine
• Barista
• Cups
• Beans
• Customers

Systems thinking view:

• Customer orders → Barista uses machine → Machine produces coffee → Customer receives → Customer might return
• The machine needs beans (supply chain) — what if beans run out?
• Barista needs training (human systems) — what if barista is new?
• Shop needs location (infrastructure) — what if there's no parking?
• Customer satisfaction affects future visits (feedback loop) — happy customers return, unhappy ones don't

Emergent behavior: Wait times fluctuate based on peak hours, customer flow, and barista experience — you can't predict this from individual parts alone.

Real-World Software Example: E-Commerce Platform

Consider an e-commerce application:

Isolated view:

• Frontend (React)
• Backend (Node.js)
• Database (PostgreSQL)
• Cache (Redis)

Systems thinking view:

• User browses → Frontend caches → Backend processes → Database stores → Payment gateway charges → Email service confirms
• What happens if cache is cold? (slower loads, higher database load)
• What happens if payment gateway is down? (order processing stalls, users frustrated)
• What happens during Black Friday sales? (traffic spikes, database contention, CDN becomes critical)
• Customer abandonment creates feedback: if checkout is slow, users don't complete purchases, revenue drops, less investment in performance, slower checkout again (vicious cycle)

Emergent behavior: System throughput varies non-linearly with user load due to caching, database locking, and external API rate limits.

Why It Matters for Architecture

Traditional view: "Build these components" Systems thinking view: "How do components interact to create value?"

Sruja Example: E-Commerce Platform

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

Customer = person "End User"
Admin = person "Administrator"

ECommerce = system "E-Commerce Platform" {
  WebApp = container "Web Application" {
    technology "React"
  }
  API = container "API Service" {
    technology "Node.js"
  }
  Cache = queue "Redis Cache"
  DB = database "PostgreSQL"
}

PaymentGateway = system "Payment Gateway"
EmailService = system "Email Service"

// User flow (happy path)
Customer -> ECommerce.WebApp "Browses products"
ECommerce.WebApp -> ECommerce.Cache "Checks cache"
ECommerce.WebApp -> ECommerce.API "Fetches data"
ECommerce.API -> ECommerce.DB "Reads products"
ECommerce.API -> ECommerce.WebApp "Returns products"

// Order processing flow
Customer -> ECommerce.WebApp "Submits order"
ECommerce.WebApp -> ECommerce.API "Processes order"
ECommerce.API -> ECommerce.DB "Saves order"
ECommerce.API -> PaymentGateway "Charges payment"
PaymentGateway -> ECommerce.API "Payment confirmation"
ECommerce.API -> EmailService "Sends confirmation"
EmailService -> Customer "Order confirmation"

Extended Example: What About Edge Cases?

// What happens when things go wrong?

scenario CacheMiss "Cache Miss Scenario" {
  Customer -> ECommerce.WebApp "Requests product"
  ECommerce.WebApp -> ECommerce.Cache "Cache miss"
  ECommerce.WebApp -> ECommerce.DB "Queries database"  // Slower
  ECommerce.DB -> ECommerce.WebApp "Returns product"
  ECommerce.WebApp -> Customer "Displays product"  // Noticeable delay
}

scenario PaymentFailure "Payment Gateway Down" {
  Customer -> ECommerce.WebApp "Submits order"
  ECommerce.WebApp -> ECommerce.API "Processes order"
  ECommerce.API -> PaymentGateway "Attempts payment"  // Timeout!
  ECommerce.API -> ECommerce.DB "Saves order as pending"  // Graceful degradation
  ECommerce.API -> Customer "Shows: Payment failed, retry later"  // Good UX
}

Key insight: Systems thinking forces you to design for failures, not just happy paths.

Common Misconceptions

❌ "Systems thinking is just about drawing diagrams" Reality: It's about understanding behavior, interactions, and emergent properties. Diagrams are a tool, not the goal.

❌ "More components mean more complex systems" Reality: Complexity comes from relationships and feedback loops, not component count. A simple system with 3 components in a feedback loop can be more complex than 10 components in a linear chain.

❌ "We can optimize parts in isolation" Reality: Optimizing one part (e.g., database queries) without considering the whole system (caches, frontend, network) often has minimal impact or even makes things worse.

❌ "Systems thinking is only for large-scale systems" Reality: It applies to all systems, even small APIs. A small system's design affects maintainability, testability, and future scalability.

Key Takeaways

1. Relationships matter more than parts — interactions drive system behavior
2. Design for the whole system — not just individual components
3. Consider edge cases and failures — systems thinking helps you design gracefully
4. Think in flows and feedback — how do things move through your system?
5. Map emergent behavior — what emerges that you couldn't predict from parts alone?

Systems thinking focuses on relationships and interactions, not just components. It's about understanding behavior, not just structure.

Quiz: Test Your Knowledge

Question 1: What is systems thinking?

• a) A way to optimize code performance
• b) A holistic approach to understanding how components interact as part of a whole
• c) A method for breaking down systems into smaller parts
• d) A database design technique

Check Answer

Question 2: In the coffee shop example, what represents a systems thinking view?

• a) Coffee machine, barista, cups, beans, customers listed separately
• b) Customer orders → Barista uses machine → Machine produces coffee → Customer receives → Customer might return
• c) How much coffee is sold per day
• d) Just focus on the coffee machine and barista

Check Answer

Question 3: What's the key difference between the traditional view and systems thinking view in software architecture?

• a) Traditional uses diagrams, systems thinking uses text
• b) Traditional focuses on user experience, systems thinking focuses on backend
• c) Traditional: "Build these components." Systems thinking: "How do components interact to create value?"
• d) Traditional is for small systems, systems thinking is only for enterprise

Check Answer

Lesson 2: Seeing Deeper with the Iceberg Model

Learning Goals

By the end of this lesson, you'll be able to:

• Identify the four levels of the iceberg model
• Recognize when you're stuck at the surface events level
• Analyze problems by looking for patterns and root causes
• Understand how mental models shape system behavior

Understanding the Iceberg Model

Have you ever felt like you're constantly putting out fires? You fix one bug, test it thoroughly, celebrate—and then two more similar bugs appear the next day. Or maybe you've watched your team debate the same architectural decision repeatedly, never quite resolving it?

These aren't just frustrating experiences. They're symptoms of looking at problems at the surface level—the "events" level—without understanding the deeper patterns, structures, and beliefs that create them.

The iceberg model gives us a way to look deeper.

The Four Levels

The iceberg model has four levels, from surface to depth. Let's walk through each one with examples that might feel familiar.

Events: What You See

Events are the things that happen right now—the incidents, bugs, crashes, and alerts you deal with daily.

Think of a typical Monday: "Server crashed at 2:37 PM" or "User reported a critical bug." These are events. They're immediate, observable, and often prompt a reactive response: "Fix it now."

The problem? Events are just symptoms. Fixing an event doesn't prevent it from happening again tomorrow.

Patterns: What's Happening Over Time

When you look at events collectively, patterns start to emerge. These are trends and recurring sequences that tell you what's really going on.

Maybe you notice: "Similar bugs occur repeatedly after releases" or "Server crashes every Sunday night during backups." These aren't isolated incidents anymore—they're patterns.

Patterns tell you something important: this isn't random. There's something systemic happening here.

Structures: What's Causing the Patterns

Structures are the underlying arrangements and mechanisms that create the patterns you're seeing. They're often invisible until you look for them.

Why do bugs keep appearing after releases? Maybe it's because components are tightly coupled, so a change in one creates cascading failures elsewhere. Why do servers crash during backups? Maybe it's because a single database becomes a bottleneck when backup processes run.

Structures are often about architecture, processes, or technology choices. They're the root causes.

Mental Models: What's Shaping the Structures

This is the deepest level. Mental models are the beliefs, assumptions, and worldviews that influence the structures you create.

Why is your system tightly coupled? Maybe because your team believes "speed to market is everything, let's worry about architecture later." Why is there a single database bottleneck? Maybe because everyone assumes "we can scale a single database if we need to—let's not over-engineer."

Mental models are the hardest to change because they're often unspoken assumptions. But they're also the most powerful because they shape everything above them.

Here's how they connect:

"Mental models" → influence → "Structures" → create → "Patterns" → manifest as → "Events"

When you fix an event without changing the mental model, the pattern eventually returns.

Seeing It in Practice

Let's make this concrete with a real example.

A Real Architecture Scenario

Imagine you're working on an e-commerce platform, and you're dealing with slow page loads. Here's how the iceberg model helps you diagnose the problem:

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

// Event: Slow page loads
// Pattern: Performance degrades after releases
// Structure: Monolithic architecture, no caching
// Mental Model: "Optimization is premature"

App = system "Web Application" {
  Monolith = container "Monolithic App"
  DB = database "Single Database"
}

Monolith -> DB "Heavy queries"

Let's analyze this at each level:

• Event: Users report slow page loads. You investigate, find slow queries, optimize them. Performance improves briefly.
• Pattern: Performance degrades after every release. Optimized queries don't solve it long-term. Something else is happening.
• Structure: The system is monolithic with no caching. Every page load hits the database. As the codebase grows, queries become heavier.
• Mental Model: The team believes "Optimization is premature—ship features first, worry about performance later." This shapes architectural decisions.

If you only fix the event (optimize queries), the pattern returns. If you redesign the structure (add caching, modularize), but don't address the mental model, you'll build similar bottlenecks in the new architecture. The real solution requires changing the belief about performance.

When to Use Each Level

So when do you actually use each level? Here's a practical guide.

Start with Events Level

You're at this level when you're reacting to immediate problems: debugging specific bugs, handling production alerts, or investigating user complaints. This is day-to-day firefighting. It's necessary, but if you never go deeper, you'll keep putting out the same fires.

Move to Patterns Level

When you notice recurring issues, shift to the patterns level. This is for analyzing historical data, identifying trends, and planning for capacity and scaling.

Think about it: "Similar bugs appear after every release" is a pattern. It tells you something systemic is happening. At this level, you're asking: "What keeps happening?"

Dive to Structures Level

This is where architecture and design decisions happen. You're here when designing systems, performing root cause analysis, planning refactoring, or evaluating technology choices.

At the patterns level, you know what's happening. At the structures level, you figure out why it's happening. You map out component relationships and identify root causes.

Reach Mental Models Level

This is the deepest—and most powerful. You're here when making strategic decisions, changing team culture, setting long-term priorities, or aligning stakeholders on vision.

This is the hardest level to reach because mental models are often unspoken. But changing them creates lasting impact. You might ask: "What do we believe that makes this structure seem right?" or "What assumptions are driving our decisions?"

How to Shift Between Levels

The real skill isn't knowing the four levels—it's knowing how to move between them when you're analyzing problems.

From Events to Patterns

You're stuck at the events level when you keep seeing isolated incidents. To shift:

1. Collect data over time - Don't just look at today's incident. Look at the last month's incidents.
2. Look for correlations and trends - Are these incidents connected? Do they follow a pattern?
3. Ask the right question: "What keeps happening?"

From Patterns to Structures

You're at the patterns level when you see recurring issues but don't know the cause. To shift:

1. Analyze root causes - Don't just acknowledge the pattern. Ask why it exists.
2. Map out component relationships - How do parts connect? Where are dependencies?
3. Ask the right question: "What creates these patterns?"

From Structures to Mental Models

This is the hardest shift. You're at the structures level when you understand the architecture but don't understand why decisions were made. To shift:

1. Identify assumptions and beliefs - What does your team believe about this problem?
2. Challenge deeply held views - Are these assumptions still valid? What evidence supports them?
3. Ask the right question: "What do we believe that makes this structure seem right?"

A Practical Example

Let's say your team keeps introducing tightly coupled components. Here's how you might analyze this:

Start: You notice a bug in Component A. Fix it. Same bug appears in Component B. This is the events level.

Shift to patterns: You realize "Coupling issues appear after every feature release." This is the patterns level.

Shift to structures: You investigate and find "Components share the same database table and call each other directly." This is the structures level.

Shift to mental models: You ask "Why did we design it this way?" and realize "We believed tight coupling would speed development." This is the mental models level.

Now you can change the mental model—and create different structures in the future.

What to Remember

The iceberg model gives you a way to look deeper than surface problems. But here's the important part: the deeper you go, the more powerful your solutions become.

Think of it this way: fixing an event is like taking an aspirin for a headache—it might work temporarily, but the headache might come back tomorrow if you don't address the cause. Addressing patterns is like understanding what triggers your headaches. Addressing structures is like changing lifestyle habits that cause headaches. Addressing mental models is like understanding why you adopted those habits in the first place.

The shift in thinking is subtle but profound. Instead of asking "How do I fix this bug?", you ask "Why do similar bugs keep appearing? What structures create these patterns? What beliefs led to these structures?"

This doesn't mean you should always start at the mental models level. Sometimes you genuinely do need to fix a bug quickly. But when you see recurring problems, that's your signal to go deeper.

The iceberg model helps you ask better questions—and asking better questions is the first step to finding better answers.

Check Your Understanding

Let's see if this is clicking.

Quick Check

1. You're investigating slow page loads on your site. You optimized a specific query and it's faster now—but similar performance issues keep appearing. Which level of the iceberg model should you move to next?

[ ] A. Stay at Events level - keep optimizing individual queries [ ] B. Patterns level - look for why these issues keep recurring [ ] C. Structures level - redesign the architecture now [ ] D. Mental Models level - change team beliefs about performance

2. Your team believes "Ship fast, fix bugs later." You've noticed this leads to tightly coupled components and cascading failures. What level of the iceberg model is this belief?

[ ] A. Events - it's a statement in meetings [ ] B. Patterns - this belief appears in every project [ ] C. Structures - it creates tight coupling in code [ ] D. Mental Models - it's an assumption shaping your architecture

Answers & Discussion

1. B. Patterns level – Optimizing individual queries is working at the Events level (fixing incidents). But since "similar performance issues keep appearing," that's a pattern signal. You need to identify what creates this recurring pattern before you can solve it effectively.

2. D. Mental Models – The belief "Ship fast, fix bugs later" is a mental model—a worldview that influences decisions. It leads to Structures (tightly coupled components) that create Patterns (cascading failures) that manifest as Events (bugs). Changing the architecture without changing this belief will likely create similar problems in new forms.

What's Next

Now that you understand the iceberg model and can see systems at different levels, let's apply this to real software systems. In the next lesson, we'll explore Systems in Software Architecture—how every application is actually a system of systems, with multiple layers and dependencies.

This will help you see the bigger picture when designing your own applications.

Lesson 3: Every App is a System of Systems

Learning Goals

By the end of this lesson, you'll be able to:

• Identify the layers that make up a software system
• Recognize when you're ignoring dependencies or organizational factors
• Understand how Conway's Law affects your architecture
• Model systems holistically in Sruja

Seeing Layers: Every App is a System of Systems

When you design software, what do you think about first? The frontend framework? The backend API? The database schema?

These are important parts. But they're not the whole system. Every application exists in a context—users who interact with it, dependencies it relies on, processes that keep it running, and data flowing through it.

Here's what happens when you ignore these layers: You design a perfect API, but your team doesn't know how to deploy it reliably. You optimize database queries, but external payment gateway has rate limits you didn't consider. You build features quickly, but organizational processes create technical debt that slows you down.

Seeing systems holistically—seeing all the layers—is what prevents these problems.

The Layers of a Software System

Every application is built from multiple interconnected layers. Let's visualize them:

┌─────────────────────────────────────┐
│  People: Users, Developers, Ops      │  ← Stakeholders
├─────────────────────────────────────┤
│  Dependencies: APIs, Libraries       │  ← External Systems
├─────────────────────────────────────┤
│  Processes: Dev, Deploy, Monitor     │  ← Operational Systems
├─────────────────────────────────────┤
│  Data: State, Transactions, Logs     │  ← Information Systems
├─────────────────────────────────────┤
│  Application: UI, Logic, Storage     │  ← Your System
└─────────────────────────────────────┘

Why These Layers Matter

Let's talk about why ignoring these layers causes problems. Here's what happens at each layer:

Dependencies Can Fail

When you depend on external systems (payment gateways, APIs, libraries), those dependencies can fail. If you don't account for this in your architecture, a single external failure can bring down your entire application.

Teams Shape Architecture (Conway's Law)

Ever heard of Conway's Law? It states that "organizations which design systems are constrained to produce designs which are copies of the communication structures of these organizations."

Translation: How your team communicates and is organized will directly influence your architecture. If your team is split into silos, you'll likely build tightly coupled systems. If your team has clear cross-team communication, you'll naturally build more modular, integrated systems.

Operational Processes Determine Reliability

Your architecture design matters, but so do your processes. How do you deploy? How do you monitor? How do you handle incidents?

You might design the most resilient architecture possible, but if your deployment process is fragile (manual steps, no testing, no rollbacks), your system will be fragile too.

Data Systems Create Integration Challenges

Data doesn't just sit in one place anymore. It flows between databases, caches, analytics, logs, and external systems. This movement creates integration challenges and consistency requirements.

If you don't consider these data flows, you'll hit problems: inconsistent data across services, race conditions, synchronization issues.

Common Architecture Layers

Now that we understand why layers matter, let's look at common layers you'll encounter in real software systems.

Application Layer: What You Build

This is what most developers think about first—the code and logic. It includes:

• User interfaces: Web applications, mobile apps, CLI tools
• Business logic: APIs, services, domain models
• Data storage: Databases, caches, file systems

This is the visible part of your system—what users interact with and what you spend most of your time building.

Infrastructure Layer: What Runs Your Code

Your application doesn't run in a vacuum. It needs infrastructure:

• Compute: Servers, containers, cloud instances
• Network: Load balancers, CDNs, firewalls, VPNs
• Monitoring: Logs, metrics, alerts, dashboards

Infrastructure determines reliability, scalability, and performance. You might have perfect code, but if your infrastructure can't handle load or lacks monitoring, you won't know when things fail.

Organizational Layer: Who Builds It

This layer often gets overlooked, but it's critical. It includes:

• Teams and responsibilities: Who owns what? How are decisions made?
• Development workflows: Code reviews, testing, CI/CD pipelines
• Release processes: How do features go from idea to production?

As Conway's Law states, how your organization is structured will influence your architecture. If your team is organized by technical skill (backend team, frontend team, database team), you'll likely build systems that mirror that structure—sometimes creating unnecessary boundaries.

Modeling Systems Holistically in Sruja

Let's see how this looks in practice with a real e-commerce system.

Example: E-Commerce Platform

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

// People (stakeholders)
Customer = person "Customer"
Admin = person "Admin"

// External Systems (dependencies)
PaymentGateway = system "Payment Gateway"
EmailService = system "Email Service"

// Your System
ECommerce = system "E-Commerce Platform" {
  WebApp = container "Web Application" {
    technology "React"
  }
  API = container "API Service" {
    technology "Node.js"
  }
  DB = database "PostgreSQL"
}

// Relationships show system interactions
Customer -> ECommerce.WebApp "Browses products"
ECommerce.WebApp -> ECommerce.API "Fetches data"
ECommerce.API -> ECommerce.DB "Queries"
ECommerce.API -> PaymentGateway "Process payment"
PaymentGateway -> EmailService "Send receipt"

Analyzing This Model

Notice how this shows multiple layers:

People layer: Customer and Admin are stakeholders who use and manage the system.

Dependencies layer: PaymentGateway and EmailService are external systems we depend on. If the payment gateway is down, our entire order flow breaks.

Application layer: WebApp, API, and DB are containers within our system. This is what we build and control.

Relationships show dependencies: The arrows between components show data flow and dependencies. API -> PaymentGateway is a critical dependency. If that external system is slow or fails, we need to handle it gracefully.

What This Reveals

When you model systems holistically like this, you start seeing:

• Single points of failure (like PaymentGateway)
• Team ownership boundaries (what's in our system vs. external)
• Data flow paths (how do orders flow through the system?)
• Integration points (where do we cross system boundaries?)

This big-picture view helps you design more resilient systems.

What to Remember

The key insight from this lesson is simple but powerful: Never design in isolation.

Every application exists in a context—people who use it, dependencies it relies on, processes that keep it running, and data flowing through it. When you ignore these layers, you build fragile systems that work in theory but fail in practice.

Think of it this way: A car designer who only thinks about the engine and drivetrain, but ignores the fuel system, cooling system, and driver experience, will create a car that can't run reliably.

The same applies to software. When you see systems holistically—all the layers together—you design better systems. You identify dependencies before they break, you consider team structure before it constrains you, and you plan for failure before it happens.

This is what systems thinking in architecture looks like: Not just code, but code in context.

Check Your Understanding

Let's see if you're seeing systems holistically now.

Quick Check

1. Your team is organized by technical role: backend team, frontend team, database team. You're designing a new feature. What's likely to happen to your architecture, based on Conway's Law?

[ ] A. You'll build a perfectly modular system because roles are clear [ ] B. You'll build systems with boundaries that mirror your team structure [ ] C. Team organization won't affect your architecture at all [ ] D. You'll need to reorganize teams to match a better architecture

2. You're designing an e-commerce system and decide to use an external payment gateway API. What should you consider, based on this lesson?

[ ] A. Nothing—it's just another API call [ ] B. The gateway might fail or have rate limits, which could break your entire order flow [ ] C. Always build your own payment system instead of depending on external services [ ] D. Only worry about the API documentation and authentication

Answers & Discussion

1. B. You'll build systems with boundaries that mirror your team structure – Conway's Law states that systems mirror the communication structures of the organizations that build them. If your teams are organized by technical role (backend, frontend, database), your architecture will likely have similar boundaries, creating unnecessary coupling and communication challenges.

2. B. The gateway might fail or have rate limits, which could break your entire order flow – When you depend on external systems, those dependencies become single points of failure. You need to consider what happens if the gateway is down, has rate limits, or has performance issues. Do you have fallbacks? Retry logic? Degraded service modes? Ignoring these layers leads to fragile systems.

What's Next

Now that you understand every application is a system of systems with multiple layers, let's dive into the specific components that make up these systems. In the next lesson, we'll explore Parts & Relationships—how to identify components and model their interactions.

This is where systems thinking gets practical: You'll learn to model real systems in Sruja with precision and clarity.

Module 2: Parts and Relationships

Overview

In this module, you'll learn to identify and model the components (parts) of a system and how they interact (relationships).

Learning Objectives

By the end of this module, you'll be able to:

• Identify the key parts of a software system
• Model components using Sruja's element types
• Define relationships with clear, meaningful labels
• Use nesting to show hierarchical structure
• Validate relationships for correctness

Lessons

• Lesson 1: Identifying Parts - How to find and classify system components
• Lesson 2: Sruja Elements - Using person, system, container, component
• Lesson 3: Defining Relationships - Modeling interactions between parts
• Lesson 4: Hierarchy and Nesting - Organizing parts within systems

Prerequisites

• Completed Module 1: Fundamentals

Time Investment

Approximately 1.5-2 hours to complete all lessons and exercises.

What's Next

After completing this module, you'll learn about Module 3: Boundaries.

Finding the Building Blocks: Identifying Parts

Ever walked into a room full of people and tried to understand what's going on? You naturally start by identifying the key players: who's talking, who's listening, who's organizing. That's exactly what we do in systems architecture—we identify the parts first, then figure out how they connect.

In this lesson, you'll learn to spot the essential components of any software system. Whether you're building an e-commerce platform, a social network, or an internal tool, the process is the same. Let's dive in.

Learning Goals

By the end of this lesson, you'll be able to:

• Confidently identify the key parts of any software system
• Understand the C4 model's four-level hierarchy
• Apply a systematic approach to breaking down requirements into components
• Recognize when you've found the right level of detail

The C4 Model: Your Guide to Structure

Before we start identifying parts, let me introduce you to the C4 model—a framework that gives us a clear hierarchy for organizing software components. Think of it like a building: you start with the people who use it (person level), then the building itself (system), then the rooms within it (containers), and finally the furniture and fixtures inside those rooms (components).

Here's how it breaks down in practice:

Level 1: Person (Users, stakeholders)
  ↓ Who interacts with the system?
  
Level 2: System (Software systems)
  ↓ What software systems are involved?
  
Level 3: Container (Applications, databases, services)
  ↓ What are the deployable units?
  
Level 4: Component (Modules, classes, libraries)
  ↓ What are the internal building blocks?

I've found this hierarchy incredibly useful because it prevents us from getting lost in the weeds too early. Start at the top, work your way down, and stop when you have enough detail for your audience.

A Step-by-Step Approach to Finding Parts

Let's walk through a practical example together. Imagine you're reading these requirements:

"Customers can browse products, add to cart, and checkout. Administrators can manage inventory and view reports. The system sends email notifications for order confirmations."

How would you identify the parts? Here's my approach:

Step 1: Start with People

Who are the humans interacting with this system? This is always the best starting point because every system exists to serve people.

Looking at the requirements, I can immediately spot two key players:

• Customers—they're browsing, adding to cart, and checking out
• Administrators—they're managing inventory and viewing reports

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

Customer = person "Customer"
Administrator = person "Administrator"

Notice how I'm already thinking in terms of Sruja syntax? That's because once you understand the concept, the code becomes a natural expression of your thinking.

Step 2: Identify the Systems

Now, what software systems are involved? Sometimes this is obvious (one main system you're building), and sometimes it's more complex (multiple systems talking to each other).

From our requirements, I can see:

• E-commerce platform—this is the main system we're building
• Email service—this is an external system we'll integrate with

ECommerce = system "E-Commerce Platform"
EmailService = system "Email Service"

Don't worry if you miss some systems initially. You can always come back and add more as you discover dependencies.

Step 3: Break Down Systems into Containers

Now we get to the interesting part. What are the deployable units that make up our e-commerce platform? Think about what you'd actually deploy: web apps, APIs, databases, caches—these are all containers.

For our e-commerce platform, a sensible breakdown might be:

ECommerce = system "E-Commerce Platform" {
  WebApp = container "Web Application" {
    technology "React"
  }
  API = container "API Service" {
    technology "Node.js"
  }
  Database = database "PostgreSQL" {
    technology "PostgreSQL 14"
  }
  Cache = database "Redis Cache" {
    technology "Redis 7"
  }
}

I've included a cache because I know from experience that almost every e-commerce platform benefits from one for performance. This is where real-world experience comes in—you'll naturally add components that make sense based on patterns you've seen before.

Step 4: Consider Components (But Only If Needed)

This is where many people go wrong. They immediately start modeling every single class and module. Stop and ask yourself: Does my audience need this level of detail?

If you're talking to developers who need to understand the internal architecture, yes—break containers into components. If you're talking to stakeholders who just want to understand the overall system, skip this level.

For example, if we were documenting the API's internal structure for our engineering team:

API = container "API Service" {
  ProductService = component "Product Service"
  CartService = component "Cart Service"
  OrderService = component "Order Service"
  PaymentService = component "Payment Service"
}

The key insight here: match the level of detail to your audience. Not every diagram needs components. Not every discussion needs to dive this deep.

Common Patterns You'll See Everywhere

After building systems for years, you start to recognize patterns that repeat across different domains. Here are three I see constantly:

Pattern 1: The Classic Three-Tier Architecture

This is probably the most common pattern you'll encounter. It's simple, it works, and it's a great starting point for most web applications.

App = system "Application" {
  Frontend = container "Web App" {
    technology "React"
  }
  Backend = container "API Service" {
    technology "Node.js"
  }
  Database = database "Database" {
    technology "PostgreSQL"
  }
}

I've used this pattern more times than I can count. It's a solid foundation that scales well and most developers immediately understand.

Pattern 2: Microservices

When your system grows, you might need to split it into smaller, independently deployable services. That's where this pattern comes in.

App = system "Microservice Application" {
  APIGateway = container "API Gateway"
  UserService = container "User Service"
  OrderService = container "Order Service"
  NotificationService = container "Notification Service"
}

The trick here is knowing when to use this. Don't start with microservices just because it's trendy. Start simple, then split when you have a real reason (scaling, team size, complexity).

Pattern 3: Event-Driven Architecture

When you need systems to react to events in real-time, this pattern shines. It's more complex but incredibly powerful for the right use cases.

App = system "Event-Driven System" {
  Producer = container "Event Producer"
  Consumer = container "Event Consumer"
  MessageQueue = queue "Kafka Cluster"
}

I've seen teams jump into this pattern too early and regret it. Make sure you actually need event-driven architecture before adopting it—it adds significant complexity.

Pitfalls to Avoid (I've Made All of These)

Let me save you some trouble by sharing mistakes I've made and seen others make:

Mistake 1: Oversimplifying

When you're rushing, it's tempting to just model everything as one big system:

// Don't do this—it's too simple
App = system "The App"

This tells you nothing about how the system is structured. Anyone looking at this diagram will be left with more questions than answers.

// This is better—it shows structure
App = system "The App" {
  Frontend = container "Frontend"
  Backend = container "Backend"
  Database = database "Database"
}

Mistake 2: Over-Engineering

On the flip side, I've seen people model every single class and component, creating diagrams that are essentially unreadable:

// Don't do this—it's too detailed
App = system "The App" {
  Frontend = container "Frontend" {
    Header = component "Header"
    Body = component "Body"
    Footer = component "Footer"
  }
}

Who cares about the header, body, and footer at the architecture level? No one. That's implementation detail, not architecture.

// This is the right level of detail
App = system "The App" {
  Frontend = container "Frontend"
  Backend = container "Backend"
}

Mistake 3: Mixing Levels Inconsistently

This one trips up even experienced architects. You might have some parts modeled at the container level and others at the component level, creating confusion:

// Don't do this—inconsistent detail
App = system "The App" {
  Frontend = container "Frontend"
  UserService = component "User Service"  // Skips container level
  Database = database "Database"
}

What's the UserService doing here without a parent container? Is it a standalone service? Part of another system? It's confusing.

// This is consistent and clear
App = system "The App" {
  Frontend = container "Frontend"
  Backend = container "Backend" {
    UserService = component "User Service"
  }
  Database = database "Database"
}

What to Remember

Identifying parts is both an art and a science. The science is following the C4 hierarchy and being systematic. The art is knowing how much detail to include and what to leave out.

If you take away just one thing from this lesson, let it be this: start with people, then systems, then containers, and only add components when your audience truly needs that level of detail.

Everything else flows from that principle.

Check Your Understanding

Let's see if you've got this. Here are a couple of questions to test your understanding:

Question 1

You're building a project management tool with these requirements:

"Team members can create tasks, assign them to others, and track progress. Managers can view reports and approve tasks. The system sends email notifications for task assignments and due dates. Task data is stored in a database. The system integrates with Slack for notifications."

At the person level, which parts should you identify?

A) Task, Report, Email, Database, Slack B) Team Member, Manager C) Project Management Tool, Slack, Email Service D) Task Assignment, Task Approval, Report Generation

Question 2

You're modeling a simple blog platform. When should you break your containers down into components?

A) Always—components provide the most detail B) Never—containers are sufficient for all audiences C) When your audience needs to understand internal architecture or when a container is complex D) Only when you're using microservices

What's Next?

Now that you know how to identify parts, you're probably wondering: "How do I actually define these parts in Sruja? What's the syntax?"

In the next lesson, you'll learn exactly that. We'll cover the four core element types (person, system, container, component), how to use them, and what details to include. You'll have a complete toolkit for modeling any software system.

See you there!

Your Toolkit: Sruja's Element Types

Now that you know how to identify parts, let's talk about how to actually define them in Sruja. Think of element types as your vocabulary—the building blocks you'll use to describe any software architecture.

The beauty of Sruja is that it gives you exactly four element types. Not ten, not twenty—just four. This might feel limiting at first, but I promise you'll appreciate the simplicity. With these four types, you can model any software system from a simple blog to a distributed microservices platform.

Let's dive in.

Learning Goals

By the end of this lesson, you'll be able to:

• Confidently use all four Sruja element types
• Know exactly when to use each type (and when not to)
• Write clean, consistent element definitions
• Add meaningful details that make your diagrams useful

The Four Building Blocks

Here's the complete toolkit. You'll use these four types over and over again:

Notice how each maps to a level in the C4 hierarchy? Person is Level 1, System is Level 2, Container is Level 3, Component is Level 4. They work together in a hierarchy, not as independent pieces.

Person: It Always Starts With People

Every system exists to serve humans. That's why person is your starting point. Don't skip it—even if it feels obvious. Having people in your diagram grounds everything in reality.

The Basics

Here's how simple it is:

Customer = person "Customer"
Admin = person "Administrator"
Support = person "Customer Support"

That's it. You define an ID (like Customer) and a display name (like "Customer"). Simple, readable, and immediately clear.

Adding Context

Sometimes a name isn't enough. You might want to add more details:

Customer = person "Customer" {
  description "End users who purchase products"
  metadata {
    type ["external"]
    priority "high"
  }
}

I use descriptions when the name alone might be ambiguous. For example, "Admin" could mean a system administrator, a content admin, or a superuser. Adding a description removes that ambiguity.

Real-World Examples

Here are some people I've modeled in different projects:

// Internal users
Developer = person "Developer"
ProductManager = person "Product Manager"
DataAnalyst = person "Data Analyst"

// External users
APIConsumer = person "API Consumer"
Partner = person "Business Partner"
Vendor = person "Vendor"

// Support roles
SupportAgent = person "Customer Support"
SalesRep = person "Sales Representative"

One thing I've learned: don't overthink this. If someone interacts with your system, model them as a person. You don't need to capture every single role—just the ones that matter for your diagram's purpose.

System: The Big Picture

Systems are the major software units. Think of them as the "big boxes" in your architecture—the main applications, third-party services, and platforms you depend on.

Defining Systems

Here's the basic syntax:

ECommerce = system "E-Commerce Platform"
PaymentGateway = system "Payment Gateway"
EmailService = system "Email Service"

Adding Details That Matter

When I'm documenting systems for a team, I often add more context:

ECommerce = system "E-Commerce Platform" {
  description "Platform for buying and selling products"
  metadata {
    version "2.0"
    team ["platform-team"]
  }
  slo {
    availability {
      target "99.9%"
    }
  }
}

I love that Sruja lets you add SLOs (Service Level Objectives) directly to systems. This makes your architecture diagrams not just visual—they become living documentation that tells the story of what you've promised to deliver.

Your Systems vs. External Systems

One distinction I always make:

// Systems you own and maintain
Platform = system "Sruja Platform"
Dashboard = system "Analytics Dashboard"

// Systems you depend on (third-party)
Stripe = system "Stripe"
AWS = system "Amazon Web Services"
GitHub = system "GitHub"

I usually tag external systems with metadata { tags ["external"] } so anyone looking at the diagram immediately understands which systems you control and which you don't. This is crucial for understanding dependencies and risk.

Container: What You Actually Deploy

This is where things get practical. Containers are the deployable units—web apps, APIs, databases, caches. These are the things you actually deploy to production.

Understanding Containers

The name "container" can be confusing because people think of Docker containers. In C4 and Sruja, "container" just means "a deployable unit." It could be:

• A web application
• An API service
• A database
• A message queue
• A cache

The Different Container Types

Sruja gives you specific types for common containers:

// Regular containers
WebApp = container "Web Application"
API = container "API Service"

// Databases and datastores
UserDB = database "User Database"
CacheDB = datastore "Redis Cache"

// Message queues
Kafka = queue "Kafka Cluster"
RabbitMQ = queue "RabbitMQ"

I use database for relational databases (PostgreSQL, MySQL) and datastore for non-relational storage (Redis, MongoDB). The distinction matters because the behavior and considerations are different.

Adding Rich Details

When documenting containers for developers, I add a lot of useful information:

API = container "API Service" {
  technology "Node.js"
  description "RESTful API handling all business logic"
  version "3.1.0"
  tags ["backend", "typescript"]
  scale {
    min 2
    max 10
  }
  slo {
    latency {
      p95 "200ms"
    }
  }
}

This tells developers everything they need to know: what technology it uses, what it does, how it scales, and what performance targets it's supposed to meet. This is way more useful than a simple box diagram.

Component: Looking Inside (When You Need To)

Components are optional. I'll say that again: components are optional. Only use them when your audience needs to see inside a container.

When to Use Components

Add components when:

• You're documenting for developers who need implementation details
• A container is complex (more than 5-6 logical parts)
• Different teams own different parts of the same container
• You need to show internal architecture for a design review

Skip components when:

• You're talking to business stakeholders
• The container is simple enough to explain at a high level
• The internal structure is still evolving

Defining Components

Here's how you model them:

API = container "API Service" {
  AuthService = component "Authentication Service"
  ProductService = component "Product Service"
  CartService = component "Cart Service"
  OrderService = component "Order Service"
}

Adding Details to Components

You can add the same details to components that you add to containers:

AuthService = component "Authentication Service" {
  technology "Rust"
  description "Handles user login, registration, and JWT validation"
  scale {
    min 1
    max 5
  }
  slo {
    latency {
      p99 "100ms"
    }
  }
}

Putting It All Together

Let me show you a complete example that uses all four element types. This is a typical e-commerce platform:

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

// Level 1: People
Customer = person "Customer" {
  description "End users purchasing products"
}
Administrator = person "Administrator" {
  description "Staff managing inventory and orders"
}

// Level 2: Systems
ECommerce = system "E-Commerce Platform" {
  description "Main platform for online sales"
}
PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
  }
}
EmailService = system "Email Service" {
  metadata {
    tags ["external"]
  }
}

// Level 3: Containers
ECommerce = system "E-Commerce Platform" {
  WebApp = container "Web Application" {
    technology "React"
    description "Single-page application for customers"
  }

  API = container "API Service" {
    technology "Node.js"
    description "RESTful API handling business logic"
    scale {
      min 3
      max 10
    }

    // Level 4: Components (inside API)
    ProductService = component "Product Service"
    CartService = component "Cart Service"
    OrderService = component "Order Service"
    PaymentService = component "Payment Service"
  }

  Database = database "PostgreSQL" {
    technology "PostgreSQL 14"
    description "Primary data store"
  }

  Cache = database "Redis Cache" {
    technology "Redis 7"
    description "Caching layer for performance"
  }
}

See how everything nests naturally? People at the top, systems next, containers within systems, and components within containers. This hierarchy makes it easy to understand the architecture at any level of detail.

Naming Conventions That Work

After years of modeling systems, I've settled on some naming conventions that keep things consistent and readable.

Element IDs: Use PascalCase

// Good
Customer = person "Customer"
WebApp = container "Web App"
UserService = component "User Service"

// Avoid these
customer = person "Customer"      // SnakeCase is harder to read
WEBAPP = container "Web App"      // ALL CAPS feels like shouting
webapp = container "Web App"      // Lowercase is inconsistent

Display Names: Be Descriptive

// Good
User = person "End User"
API = container "API Service"

// Avoid these
User = person "user"              // Lowercase looks unprofessional
API = container "api"             // Lowercase looks like a typo

Consistency Within a Diagram

This is the one that trips people up most often. If you name one thing a "Service," call all similar things "Service":

// Good: Consistent naming
UserService = component "User Service"
OrderService = component "Order Service"
PaymentService = component "Payment Service"

// Bad: Inconsistent naming
UserService = component "User Service"
Order = component "Order"              // Should be "Order Service"
Payment = component "Payment Service"  // Inconsistent with "Order"

I create a style guide for each project that lists the naming conventions we're using. It sounds tedious, but it saves so much time and confusion in the long run.

Using Metadata Effectively

Metadata is where you add context that makes your diagrams actually useful. Don't add metadata just for the sake of it—add metadata that helps your audience understand what they're looking at.

API = container "API Service" {
  technology "Rust"
  version "2.0.1"
  tags ["backend", "api"]
  metadata {
    team ["platform-team"]
    repository "github.com/company/api"
    documentation "docs.company.com/api"
  }
}

I include team ownership information because it helps people know who to talk to when they have questions. I include repository links because it connects the architecture to the actual code. These details transform a static diagram into a living piece of documentation.

What to Remember

Sruja gives you four element types—person, system, container, component—and they're all you need. The key is knowing when to use each one:

• Person: Always include these. Every system serves humans.
• System: Include the main systems you're building and the ones you depend on.
• Container: Include the deployable units within your systems.
• Component: Only include these when your audience needs implementation details.

Add metadata that provides context. Use naming conventions consistently. Keep it simple and your diagrams will be clear and useful.

Everything else flows from these principles.

Check Your Understanding

Let's see if you've got this. Here are a couple of questions to test your understanding:

Question 1

You're modeling a blog platform with these requirements:

"The platform has readers and writers. The main system contains a web frontend (Next.js), API backend (Python/FastAPI), and database (PostgreSQL). The API has user management, post management, and comment services."

At the container level, which elements should you include?

A) Reader, Writer, User Management, Post Management, Comment Management B) Web Frontend, API Backend, Database C) User Management, Post Management, Comment Management D) Blog Platform, Next.js, FastAPI, PostgreSQL

Question 2

When should you model components within a container?

A) Always—components provide the most detailed view B) Only when using microservices architecture C) When your audience needs to understand internal architecture or when a container is complex D) Never—containers provide sufficient detail for all use cases

What's Next?

Now you know how to define all the parts of your system. But parts alone don't tell the whole story. Systems are defined by how their parts interact and connect.

In the next lesson, you'll learn about relationships—how to model the connections between your elements. You'll learn to write clear, meaningful labels that describe exactly how parts communicate with each other.

See you there!

Connecting the Dots: Defining Relationships

Imagine looking at a map with cities marked but no roads connecting them. You'd know where things are, but you'd have no idea how to get from one place to another. Relationships in software architecture are those roads—they show how your parts connect, communicate, and depend on each other.

In this lesson, you'll learn to create meaningful connections between your elements. These connections transform a collection of isolated parts into a coherent system that tells a story.

Learning Goals

By the end of this lesson, you'll be able to:

• Write clear, meaningful relationship labels
• Model different types of interactions between parts
• Use tags to categorize and enrich your relationships
• Handle complex scenarios like nested references and multiple connections
• Create relationships that make your diagrams tell a story

What Are Relationships, Really?

In the simplest terms, relationships describe how parts interact. They show:

• Communication: How components talk to each other
• Data flow: Where information moves through the system
• Dependencies: What happens if one part goes down
• User actions: What people actually do with the system

But here's the thing I've learned over the years: relationships aren't just technical—they're about telling the story of your system. A well-crafted relationship doesn't just say "connects"—it explains why and how things connect.

The Basic Syntax

Sruja keeps it simple:

From -> To "Label"

• From: Who initiates the interaction?
• To: Who receives it?
• "Label": What's happening? (This is the most important part!)

Here are some examples:

// Person to System
Customer -> Shop "Browses products"
Administrator -> Shop "Manages inventory"

// Container to Container
Shop.WebApp -> Shop.API "Makes API calls"
Shop.API -> Shop.Database "Reads and writes"

// Component to Component
Shop.API.ProductService -> Shop.API.CartService "Gets product details"

Notice how each label uses present tense verbs and specific actions. "Browses products" is way more informative than "uses."

Writing Labels That Tell a Story

The difference between a good architecture diagram and a great one often comes down to relationship labels. Let me show you what I mean.

Good Labels Tell a Story

Customer -> Shop.WebApp "Browses products"
Shop.API -> Shop.Database "Queries data"
Shop.API -> PaymentGateway "Processes payment"

Each label tells you something meaningful:

• The customer is browsing (shopping behavior)
• The API is querying (data retrieval)
• The payment gateway is processing (transaction handling)

Bad Labels Are Mysterious

Customer -> Shop.WebApp "Uses"  // Too generic—what do they do?
Shop.API -> Shop.Database "Connects"  // Doesn't describe the interaction
Shop.API -> PaymentGateway "Integration"  // Technical term, not behavioral

These labels leave you with questions. What does "uses" mean? What kind of connection? What's being integrated?

My Label-Writing Process

When I'm writing relationship labels, I ask myself three questions:

1. What's the action? (Browse, query, process, send, receive)
2. What's the context? (Products, data, payment, notifications)
3. Is it specific enough? (Add details if it helps understanding)

Then I combine them: Action + Context = "Browses products"

Relationship Patterns You'll See Everywhere

After modeling hundreds of systems, I've noticed patterns that repeat constantly. Recognizing these patterns will make you faster and your diagrams more consistent.

Pattern 1: User Interactions

This pattern shows what people actually do with your system:

Customer -> Shop.WebApp "Logs in"
Customer -> Shop.WebApp "Views products"
Customer -> Shop.WebApp "Adds to cart"
Customer -> Shop.WebApp "Checks out"

I model each user action as a separate relationship. This makes it clear what functionality the system needs to support.

Pattern 2: Service Communication

This pattern shows how your backend services talk to each other:

WebApp -> API "Sends requests"
API -> Database "Persists data"
API -> Cache "Reads cache"
Cache -> API "Returns cached data"

Notice the bidirectional communication? The API writes to the cache, but also reads from it. This shows the caching strategy clearly.

Pattern 3: External Dependencies

This pattern shows systems you depend on outside your control:

API -> PaymentGateway "Process payment"
API -> EmailService "Send notifications"
API -> AnalyticsService "Track events"

I always mark these systems as external so anyone looking at the diagram immediately understands which dependencies are within your control and which aren't.

Referencing Nested Elements

One of Sruja's powerful features is dot notation for nested elements. Let me show you how it works.

Direct Child Reference

Customer -> Shop.WebApp "Uses"

This is straightforward—you're referencing a direct child.

Nested Component Reference

Shop.API.ProductService -> Shop.API.CartService "Get product info"

Here, both products and carts live inside the API container. The dot notation makes it clear where each component lives.

Cross-System Reference

Shop.API -> PaymentGateway.ChargeService "Process payment"

This shows that you're calling a specific service within an external system. This level of detail can be crucial when debugging integration issues.

Using Tags to Add Meaning

Tags are optional but incredibly useful for adding context to your relationships. Think of them as annotations that help people understand what they're looking at.

Common Tags I Use

// Protocol information
Shop.WebApp -> Shop.API "Sends requests" [http]
Shop.API -> Shop.Database "Queries data" [sql]

// Importance
Shop.API -> PaymentGateway "Process payment" [critical]
Shop.API -> EmailService "Send notifications" [optional]

// Data flow
Shop.WebApp -> Shop.API "Sends requests" [synchronous]
Shop.API -> EmailService "Send notifications" [asynchronous]

// Security
Shop.WebApp -> Shop.API "Sends requests" [authenticated]
Customer -> Shop.WebApp "Browses" [public]

I use tags when the detail matters for understanding the system. For example, marking something as critical tells people it's a path to watch closely during outages. Marking something as external reminds everyone it's outside your control.

Handling Multiple Relationships

Elements rarely have just one relationship—they're connected to many things. That's normal and expected.

A Typical Container with Multiple Connections

// WebApp connects to several things
Customer -> Shop.WebApp "Browses"
Shop.WebApp -> Shop.API "Queries products"
Shop.WebApp -> Shop.Cache "Reads cache"
Shop.WebApp -> Customer "Displays products"

// API is even more connected
Shop.WebApp -> Shop.API "Sends request"
Shop.API -> Shop.Database "Persists order"
Shop.API -> PaymentGateway "Process payment"
Shop.API -> Shop.WebApp "Returns response"
Shop.API -> Shop.EmailService "Send confirmation"

This might look overwhelming at first, but it's actually telling a clear story. The WebApp is the interface for customers. The API is the orchestrator that talks to databases, payment systems, and email services.

When Does Too Many Become Too Many?

If an element has more than 10-12 relationships, I ask myself: "Is this element doing too much?"

Maybe it's time to split it into smaller, more focused parts. A single service that talks to 15 different systems is probably violating the single responsibility principle.

Understanding Relationship Direction

Direction matters. It tells you who initiates the interaction and who responds.

One-Way Relationships

Customer -> Shop.WebApp "Browses"

The customer acts, the web app responds. Simple.

Two-Way Relationships (Separate Connections)

User -> App.API "Submits data"
App.API -> User "Returns result"

Here, the user sends data, and the API sends data back. They're two separate relationships because each one tells its own story.

Feedback Loops (Cycles)

User -> App.WebApp "Submits form"
App.WebApp -> App.API "Validates"
App.API -> App.WebApp "Returns errors"
App.WebApp -> User "Shows errors"
// User resubmits (loop completes)

This creates a feedback loop: submit → validate → error → show → resubmit. Feedback loops are everywhere in real systems. The thermostat in your house is one. The login flow on a website is another.

Bringing It All Together

Let me show you a complete example that uses everything we've covered:

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

// People
Customer = person "Customer"
Admin = person "Administrator"

// Systems
Shop = system "Shop" {
  WebApp = container "Web Application"
  API = container "API Service"
  DB = database "Database"
}

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
  }
}

// Customer interactions
Customer -> Shop.WebApp "Browses products" [public]
Customer -> Shop.WebApp "Adds to cart" [authenticated]
Customer -> Shop.WebApp "Checks out" [authenticated]

// Internal communication
Shop.WebApp -> Shop.API "Sends requests" [http, encrypted]
Shop.API -> Shop.DB "Persists data" [critical]
Shop.API -> Shop.DB "Queries data" [cached]

// External dependencies
Shop.API -> PaymentGateway "Process payment" [critical, external]

// Admin interactions
Admin -> Shop.WebApp "Manages products" [authenticated]
Admin -> Shop.WebApp "Views reports" [authenticated]

view index {
  include *
}

This diagram tells a complete story. You can see who uses the system, how parts communicate internally, and what external dependencies exist. The tags add crucial context about security, importance, and whether systems are under your control.

What to Remember

Relationships are what transform a collection of parts into a living, breathing system. When you write relationships:

• Be specific: "Browses products" not "uses"
• Use present tense: "Processes" not "will process"
• Think about the story: What's really happening here?
• Add context with tags: When details matter
• Don't overthink it: Most relationships are simple

If you take away one thing, let it be this: a good relationship label tells a story about how your system actually works. Everything else flows from that principle.

Check Your Understanding

Let's see if you've got this. Here are a couple of questions to test your understanding:

Question 1

You're modeling relationships for a blog platform. Which relationship label is the most informative?

A) Reader -> Blog.Frontend "Uses" B) Reader -> Blog.Frontend "Reads posts" C) Reader -> Blog.Frontend "Frontend connection" D) Reader -> Blog.Frontend "HTTP request"

Question 2

When should you add tags to your relationships?

A) Always—tags provide useful context B) Never—tags make diagrams too complex C) When the tag adds meaningful context that helps people understand the system D) Only for external dependencies

What's Next?

Now you know how to define parts and connect them with relationships. You can create diagrams that tell stories about how systems work.

But there's one more thing: how do you organize all these parts? That's what the next lesson is about. You'll learn about hierarchy and nesting—how to structure your systems in a way that's clear, consistent, and scalable.

See you there!

Bringing Order to Chaos: Hierarchy and Nesting

Imagine walking into a house where everything is dumped in one giant room—furniture, kitchen appliances, clothes, tools, books. You could find what you're looking for eventually, but it would be frustrating and inefficient. That's what an unorganized architecture feels like.

Hierarchy and nesting are your tools for bringing order to chaos. They help you organize your system's parts in a way that makes sense, is easy to understand, and scales as your system grows.

In this lesson, you'll learn how to structure your systems effectively using the C4 model's hierarchy. You'll discover when to nest, when to keep things flat, and how to create diagrams that tell a clear story at any level of detail.

Learning Goals

By the end of this lesson, you'll be able to:

• Understand the C4 model's four-level hierarchy
• Know when to nest components and when to keep them separate
• Reference nested elements using dot notation
• Create systems that are consistent and easy to navigate
• Choose the right level of detail for your audience

The C4 Hierarchy: Your Foundation

Let's revisit the C4 model's hierarchy because it's the foundation for everything we'll discuss. Think of it like building a city:

People (Level 1)
  ↓ The citizens who live there
  
Systems (Level 2)
  ↓ The buildings and facilities
  
Containers (Level 3)
  ↓ The rooms and departments within buildings
  
Components (Level 4)
  ↓ The furniture and equipment within rooms

Each level contains the one below it. People interact with systems, systems contain containers, containers contain components. This nested structure is what makes architectures clear and navigable.

I've found this metaphor really helps people understand why we nest things. You don't put a couch (component) directly in the middle of the street (system). It belongs in a living room (container), which is inside a house (system). The same principle applies to software architecture.

Nesting Containers in Systems

Systems contain containers. This is where most of the action happens.

The Basic Pattern

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

ECommerce = system "E-Commerce Platform" {
  WebApp = container "Web Application" {
    technology "React"
  }

  API = container "API Service" {
    technology "Node.js"
  }

  Database = database "PostgreSQL" {
    technology "PostgreSQL 14"
  }

  Cache = database "Redis Cache" {
    technology "Redis 7"
  }
}

Why Nesting Matters

When I first started modeling systems, I sometimes put everything at the same level—all containers, no systems. It seemed simpler, but it created confusion:

• Who owns what? Without systems, ownership is unclear
• What belongs together? Related containers end up scattered
• How do I reference things? Dot notation becomes meaningless

Nesting containers in systems solves all these problems. It's clear what belongs together, who owns it, and how to reference it.

A Real-World Example

Let me show you a more realistic example from a project I worked on—a healthcare platform:

HealthcarePlatform = system "Healthcare Platform" {
  PatientPortal = container "Patient Portal" {
    technology "React"
    description "Web app for patients to manage appointments"
  }

  DoctorDashboard = container "Doctor Dashboard" {
    technology "Vue.js"
    description "Web app for doctors to view patient records"
  }

  API = container "API Gateway" {
    technology "Kong"
    description "Routes requests to microservices"
  }

  EHR = container "EHR System" {
    technology "Java"
    description "Electronic health records system"
  }
}

See how each container has a clear purpose? The system groups them together and tells you they're all part of the same platform. Anyone looking at this diagram immediately understands the big picture.

Nesting Components in Containers

This is where you need to be careful. Components are powerful, but only when used appropriately.

The Decision Framework

I use this simple framework to decide whether to add components:

Add components when:

• You're documenting for developers who need implementation details
• A container is complex (more than 5-6 logical parts)
• Different teams own different parts of the same container
• You need to show internal architecture for a design review

Skip components when:

• You're presenting to stakeholders who don't need technical details
• The container is simple enough to explain at a high level
• The internal structure is still evolving and changing

When to Nest Components

Let me show you an example where components make sense:

API = container "API Service" {
  technology "Node.js"
  description "RESTful API handling all business logic"

  // Authentication and authorization
  AuthService = component "Authentication Service" {
    technology "Node.js"
    description "Handles login, registration, JWT tokens"
  }

  // Domain services
  UserService = component "User Service" {
    description "User profile and preferences"
  }
  
  ProductService = component "Product Service" {
    description "Product catalog and inventory"
  }
  
  CartService = component "Cart Service" {
    description "Shopping cart and checkout"
  }
  
  OrderService = component "Order Service" {
    description "Order processing and fulfillment"
  }

  // Integration services
  PaymentService = component "Payment Service" {
    description "Payment gateway integration"
  }
  
  NotificationService = component "Notification Service" {
    description "Email and SMS notifications"
  }
}

This makes sense because:

• The API is complex with multiple distinct services
• Different teams might own different services
• Developers need to understand the internal architecture

When to Keep It Simple

Now, here's an example where I would not use components:

SimpleAPI = container "Simple API" {
  technology "Node.js"
  description "Basic CRUD API for a small application"
}

Why no components? Because:

• It's simple enough to explain at the container level
• The audience (stakeholders) doesn't need implementation details
• The internal structure might change as we iterate

The key insight: match the level of detail to your audience's needs.

Referencing Nested Elements

Once you have nested elements, you need to know how to reference them. Sruja uses dot notation, which is intuitive once you get the hang of it.

The Reference Patterns

// Level 1 to Level 2 (Person to System)
Customer -> ECommerce "Uses platform"

// Level 2 to Level 3 (System to Container)
Customer -> ECommerce.PatientPortal "Manages appointments"
Doctor -> ECommerce.DoctorDashboard "Views patient records"

// Level 3 to Level 3 (Container to Container)
ECommerce.PatientPortal -> ECommerce.API "Submits requests"
ECommerce.API -> ECommerce.EHR "Retrieves patient data"

// Level 3 to Level 4 (Container to Component)
ECommerce.API -> ECommerce.API.AuthService "Validates user"

// Level 4 to Level 4 (Component to Component)
ECommerce.API.AuthService -> ECommerce.API.UserService "Fetches user profile"

Cross-System References

What if you need to reference something inside another system? Dot notation still works:

// Reference a service inside an external system
ECommerce.API.PaymentService -> Stripe.ChargeService "Process payment"

// Reference a database inside another system
ECommerce.API -> AnalyticsDB.DataWarehouse "Push analytics data"

This level of detail can be useful when debugging integrations or documenting specific API contracts.

Consistency: The Golden Rule

If there's one thing I've learned from years of modeling systems, it's this: consistency matters more than any individual decision.

Consistency in Nesting

Don't mix levels inconsistently:

// Bad: Inconsistent nesting
App = system "App" {
  Frontend = container "Frontend"
  Backend = container "Backend" {
    API = component "API Service"
  }
  Database = database "Database"
}

// Good: Consistent nesting
App = system "App" {
  Frontend = container "Frontend" {
    UI = component "UI Components"
  }
  Backend = container "Backend" {
    API = component "API Service"
  }
  Database = database "Database"
}

In the bad example, why does Backend have components but Frontend doesn't? Is Frontend simpler? Did we forget to break it down? The inconsistency creates confusion. The good example shows a consistent approach.

Consistency in Naming

Use consistent naming conventions across your hierarchy:

// Good: Consistent suffixes
UserService = component "User Service"
OrderService = component "Order Service"
PaymentService = component "Payment Service"

// Bad: Inconsistent suffixes
UserService = component "User Service"
Order = component "Order"
Payment = component "Payment Service"

In the bad example, why is it "User Service" but just "Order"? The inconsistency makes people wonder if there's a meaningful difference. Spoiler: there usually isn't.

Pitfalls I've Encountered (So You Don't Have To)

Let me share some mistakes I've made and seen others make. Hopefully, you can avoid them.

Pitfall 1: Deep Nesting

// Bad: Too deep (5+ levels)
App = system "App" {
  Frontend = container "Frontend" {
    Layout = component "Layout" {
      Header = component "Header" {
        Navigation = component "Navigation" {
          Menu = component "Menu"
        }
      }
    }
  }
}

This is unreadable. Who can understand a 5-level deep structure? Nobody. The diagram becomes useless because it's too complex.

Solution: Keep nesting to 3-4 levels max. If you're going deeper, you're probably in implementation territory, not architecture.

Pitfall 2: Orphaned Elements

// Bad: Component without container
Shop = system "Shop"
WebApp = container "Web App"
API = container "API"
Database = database "Database"
AuthService = component "Auth Service"  // Orphan!

Where does AuthService belong? Is it in WebApp? In API? Orphaned elements confuse everyone who looks at the diagram.

Solution: Every component must belong to a container. Every container must belong to a system. No exceptions.

Pitfall 3: Flat Everything

// Bad: Everything at same level
Customer = person "Customer"
WebApp = container "Web App"
API = container "API"
Database = database "Database"
AuthService = component "Auth Service"

This shows no structure. Is WebApp part of API? Are they siblings? Who knows?

Solution: Show the hierarchy. Nest things properly. Make it clear what belongs to what.

Creating Views at Different Levels

One of the most powerful features of Sruja is the ability to create views at different hierarchy levels. This lets you tell the right story to the right audience.

Level 1: System Context View

view system_context {
  title "System Context"
  include *
}

This view shows everything: people, systems, external dependencies. Perfect for stakeholders who want the big picture.

Level 2: System View

view system_view of ECommerce {
  title "E-Commerce System"
  include ECommerce
}

This view shows a single system and all its containers. Great for developers who need to understand how a specific system is structured.

Level 3: Container View

view container_view of ECommerce.API {
  title "API Containers"
  include ECommerce.API.*
  exclude ECommerce.API.Database
}

This view shows the internals of a container. Perfect for teams working on that specific service.

Level 4: Component View

view component_view of ECommerce.API {
  title "API Components"
  include ECommerce.API.*
}

This view shows all components within a container. Ideal for detailed design reviews and implementation planning.

The beauty is that you can have multiple views of the same architecture, each tailored to a different audience. The stakeholders get the big picture. Developers get the details. Everyone gets what they need.

What to Remember

Hierarchy and nesting are about bringing order to complexity. When you're structuring your systems:

• Follow the C4 hierarchy: Person → System → Container → Component
• Nest logically: Group related parts together
• Be consistent: Use the same patterns throughout
• Match detail to audience: Don't show components to stakeholders
• Create multiple views: Tell different stories to different audiences
• Keep it simple: Avoid deep nesting and over-complexity

If you take away one thing, let it be this: a well-structured hierarchy makes complex systems understandable. Everything else flows from that principle.

Check Your Understanding

Let's see if you've got this. Here are a couple of questions to test your understanding:

Question 1

You're modeling a simple mobile app with these requirements:

"Users can create profiles, post content, and like posts. The app has a mobile frontend, API backend, and database."

At what level should you stop modeling? Should you include components?

A) Yes, always include components for completeness B) No, containers are sufficient for this system C) Include components for the API but not the mobile frontend D) Include components only if using microservices

Question 2

You're referencing nested elements in your architecture. Which reference is correctly formatted?

A) WebApp.API.Database "Queries data" B) API.AuthService -> UserService "Gets profile" C) Shop.API.ProductService -> CartService "Adds item" D) System.Container.Service -> External.Service "Calls"

What's Next?

Congratulations! You've completed Module 2: Parts and Relationships. You now have a complete toolkit for:

• Identifying the key parts of any system
• Modeling parts using Sruja's element types
• Defining meaningful relationships between parts
• Organizing everything with clear hierarchy and structure

You can now create diagrams that tell stories about how systems work—stories that are clear, consistent, and useful for your audience.

In the next module, you'll learn about boundaries—how to define where one system ends and another begins. This is crucial for understanding dependencies, managing complexity, and designing systems that are decoupled and maintainable.

See you there!

Module 2 Complete!

You've now mastered the fundamentals of modeling systems. Here's what you've learned:

Lesson 1: Identifying Parts

• Start with people, then systems, then containers, then components
• Use the C4 hierarchy as your guide
• Match the level of detail to your audience

Lesson 2: Sruja Elements

• Four element types: person, system, container, component
• Add details that matter: technology, description, SLOs
• Use naming conventions consistently

Lesson 3: Defining Relationships

• Write labels that tell a story
• Use tags to add meaningful context
• Reference nested elements with dot notation

Lesson 4: Hierarchy and Nesting

• Structure your systems consistently
• Avoid deep nesting and over-complexity
• Create multiple views for different audiences

You're ready to tackle more advanced concepts. Let's continue!

Module 3: Boundaries

Overview

In this module, you'll learn to define what's inside your system vs. what's outside (the environment). Understanding boundaries is crucial for clear ownership, risk management, and integration planning.

Learning Objectives

By the end of this module, you'll be able to:

• Define system boundaries clearly
• Model internal vs. external components
• Identify and document dependencies
• Create bounded contexts for services
• Plan integrations at boundaries

Lessons

• Lesson 1: Understanding Boundaries - What boundaries are and why they matter
• Lesson 2: Internal vs External - Differentiating and marking boundary elements
• Lesson 3: Crossing Boundaries - Modeling integrations and dependencies

Prerequisites

• Completed Module 2: Parts and Relationships

Time Investment

Approximately 1-1.5 hours to complete all lessons and exercises.

What's Next

After completing this module, you'll learn about Module 4: Flows.

Drawing the Line: Understanding Boundaries

Ever played a game of tag as a kid? There was always that safe zone—home base—where you couldn't be tagged. Everything outside that zone was fair game, everything inside was safe. Boundaries in software architecture work the same way: they define what's safe inside your system and what's risky outside it.

In this lesson, you'll learn to draw those lines clearly. You'll discover why boundaries matter, what types of boundaries you'll encounter, and how to define them effectively in your architectures.

Let's start by understanding what boundaries actually are.

Learning Goals

By the end of this lesson, you'll be able to:

• Define what boundaries are in the context of software architecture
• Recognize the different types of boundaries you'll encounter
• Understand why boundaries matter for ownership, risk, and clarity
• Apply boundaries effectively in your Sruja models

What Are Boundaries, Really?

At its simplest level, a boundary is a line that separates what's inside your system from what's outside. But this line isn't arbitrary—it represents something meaningful:

• Inside: What you build, own, maintain, and control
• Outside: The environment, external dependencies, things you rely on but don't control

Think of it like your house:

┌─────────────────────────────────────┐
│          OUTSIDE                    │
│  (The neighborhood, other houses)  │
│                                     │
│    ┌───────────────────────────┐    │
│    │       YOUR HOUSE          │    │
│    │   (Your safe space)       │    │
│    │                           │    │
│    │  [Your rooms, stuff]      │    │
│    │                           │    │
│    └───────────────────────────┘    │
│             ↑                         │
│     Front door = Boundary Line       │
└─────────────────────────────────────┘

You control everything inside your house. You don't control the neighbor's house down the street. The front door is your boundary—it's clear where your space ends and public space begins.

In software, boundaries work the same way. They tell everyone what you're responsible for and what you're not.

Why Boundaries Matter (The Real Reasons)

I've seen too many projects suffer from unclear boundaries. Teams argue about who owns what. Outages cascade because nobody planned for external failures. Security gaps emerge because nobody thought about what crosses the boundary.

Let me show you why boundaries matter in practice.

1. Clear Ownership: Who's Responsible?

This is the most common reason I see teams argue. When boundaries are unclear, nobody knows who fixes what.

// Inside: Your team owns this
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API Service"
}

// Outside: Another team/vendor owns this
PaymentGateway = system "Payment Gateway"

When something breaks with payments, who fixes it? If the boundary is clear, everyone knows: your team fixes anything inside Shop, the payment vendor fixes anything in PaymentGateway. No confusion, no finger-pointing.

I once worked on a project where a team spent three days arguing about who owned a broken integration because nobody had bothered to document the boundary. Three days of developer time—wasted.

2. Risk Management: What Could Go Wrong?

Every time you cross a boundary, you're introducing risk. You're depending on something outside your control.

// External dependency = external risk
Shop.API -> PaymentGateway "Process payment"

// If PaymentGateway is down, what happens?
// - Can customers still check out?
// - Do we have a backup?
// - What's our SLA with them?

When I model systems, I always ask: "What happens if this external thing breaks?" If I don't have a good answer, that's a risk I need to document and plan for.

3. Testing Scope: What Do We Test?

Boundaries tell you what kind of testing you need.

// Internal: Unit tests are sufficient
Shop.WebApp -> Shop.API

// External: Integration tests are required
Shop.API -> PaymentGateway

You can unit test internal interactions all day. But when you cross a boundary? You need integration tests. You need to handle network failures. You need to test timeout scenarios. Boundaries tell you where testing gets more complex.

4. Security: What Needs Protection?

Security controls should be strongest at your boundaries. That's where attacks happen.

// Inside boundary: Apply internal controls
Shop.WebApp -> Shop.API

// Crossing boundary: Validate everything
Shop.API -> PaymentGateway "Process payment" [authenticated, encrypted]

I learned this the hard way early in my career when I didn't properly validate data crossing a boundary and ended up with a security vulnerability. Lesson learned: boundaries are where security matters most.

Types of Boundaries You'll Encounter

After years of modeling systems, I've noticed there are really five main types of boundaries you'll run into. Understanding which type you're dealing with helps you make the right decisions.

1. System Boundary: Your App vs. The World

This is the most common boundary—your main application versus everything else.

// Inside: Your system
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API"
}

// Outside: Everything else
Customer = person "Customer"
PaymentGateway = system "Payment Gateway"
EmailService = system "Email Service"

The system boundary defines your overall scope. Everything inside is yours. Everything outside is not.

2. Team Boundary: What Your Team Owns

In larger organizations, different teams own different systems. These team boundaries matter for communication and coordination.

// Your team's system
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API"
}

// Another team's system
Analytics = system "Analytics Platform" {
  metadata {
    tags ["internal", "data-team"]
    owner "Data Team"
  }
}

When I see team boundaries, I always add metadata about who owns what. This prevents confusion when issues arise and everyone's trying to figure out who to call.

3. Organizational Boundary: Inside vs. Outside Your Company

Sometimes boundaries exist at the organizational level—your company versus external vendors.

// Your company's system
Shop = system "Shop"

// External vendor
Stripe = system "Stripe" {
  metadata {
    tags ["external", "vendor"]
    owner "Stripe Inc."
  }
}

Vendor relationships are fundamentally different from internal relationships. Different SLAs, different support channels, different everything. Mark these boundaries clearly so everyone knows the difference.

4. Deployment Boundary: What Deploys Together

Sometimes the same team owns systems, but they deploy independently. That's a deployment boundary.

// Same deployment
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API"
}

// Separate deployment
Database = system "Database Cluster" {
  metadata {
    tags ["internal", "dba-team"]
    deployment "Managed Service"
  }
}

Deployment boundaries tell you about failure domains. If the API and database deploy independently, they can fail independently. That's important to understand.

5. Trust Boundary: Security Zones

This is one of the most important boundaries from a security perspective. It defines what's trusted versus untrusted.

// Trusted: Internal network, internal users
InternalAPI = container "Internal API"

// Untrusted: Public internet, anyone
PublicAPI = container "Public API"

I always pay special attention to trust boundaries. This is where you need authentication, authorization, encryption, and all the other security controls. Cross a trust boundary without proper security? That's how breaches happen.

Real-World Examples

Let me show you some examples of boundaries in action.

Example 1: A Typical E-Commerce Platform

// ┌──────────── EXTERNAL WORLD ────────────┐
// │                                        │
// │   Customer (person)                    │
// │   Payment Gateway (system)             │
// │   Email Service (system)               │
// │   Analytics (system)                   │
// │                                        │
// │   ┌────── YOUR SYSTEM ──────────┐     │
// │   │ Shop (system)              │     │
// │   │   WebApp (container)       │     │
// │   │   API (container)          │     │
// │   │   Database (database)      │     │
// │   └───────────────────────────┘     │
// │                                        │
// └────────────────────────────────────────┘

// People are always outside
Customer -> Shop.WebApp "Browses"

// Everything inside your boundary
Shop.WebApp -> Shop.API "Makes requests"
Shop.API -> Shop.Database "Persists orders"

// Crossing your boundary to external systems
Shop.API -> PaymentGateway "Process payment"
Shop.API -> EmailService "Send confirmation"
Shop.API -> Analytics "Track events"

See how clear the boundary is? Everything inside "Your System" is yours. Everything else is external. Anyone looking at this diagram immediately understands the scope and dependencies.

Example 2: Microservices with Internal Boundaries

// Even within an organization, you can have boundaries

OrderService = system "Order Service" {
  metadata {
    tags ["internal", "orders-team"]
    owner "Orders Team"
  }
}

PaymentService = system "Payment Service" {
  metadata {
    tags ["internal", "payments-team"]
    owner "Payments Team"
  }
}

InventoryService = system "Inventory Service" {
  metadata {
    tags ["internal", "inventory-team"]
    owner "Inventory Team"
  }
}

// Cross-team boundaries
OrderService -> PaymentService "Request payment"
PaymentService -> OrderService "Payment result"
OrderService -> InventoryService "Reserve items"

Each service is a bounded context owned by a different team. Even though they're all "internal" to the company, the team boundaries are real and matter for coordination.

Pitfalls to Avoid (I've Made These)

Let me share some boundary mistakes I've made or seen others make. Hopefully, you can avoid them.

Mistake 1: No Clear Boundary

// Bad: Everything looks the same
Customer = person "Customer"
Shop = system "Shop"
PaymentGateway = system "Payment Gateway"
EmailService = system "Email Service"

// Without tags, what's external? What's internal?

I've seen diagrams like this where everything looks internal. Nobody knows what the team controls versus what they depend on. It's confusing and risky.

Fix: Use metadata tags to mark external systems clearly:

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external", "vendor"]
  }
}

Mistake 2: Everything Marked External

// Bad: Everything marked external, no ownership
Shop = system "Shop" {
  tags ["external"]
}
WebApp = container "Web App" {
  tags ["external"]
}

This is the opposite problem. If everything is external, who owns anything? Who's responsible? The diagram provides no clarity about ownership.

Fix: Only mark truly external systems:

Shop = system "Shop" {
  // No tags = internal
  WebApp = container "Web App"
}

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]  // Only mark what's really external
  }
}

Mistake 3: Too Many Fragmented Boundaries

// Bad: Overly fragmented, hard to understand
System1 = system "System 1"
System2 = system "System 2"
System3 = system "System 3"
System4 = system "System 4"
System5 = system "System 5"
// ... and so on

I've seen teams create a separate system boundary for every tiny piece of functionality. The diagram becomes a mess of boxes with no clear groupings. Nobody can understand the big picture.

Fix: Group related functionality into coherent systems:

Shop = system "Shop" {
  // Group all shop-related containers
  WebApp = container "Web App"
  API = container "API"
  Cache = queue "Cache"
}

Analytics = system "Analytics" {
  // Group all analytics-related containers
  Collector = container "Event Collector"
  Processor = container "Event Processor"
}

Defining Boundaries in Sruja

Sruja gives you the tools to define boundaries clearly. Here's how I use them.

Use system for Your Main Boundary

Your main application is a system. Everything you own goes inside it.

Shop = system "Shop" {
  // Everything you control goes here
  WebApp = container "Web App"
  API = container "API"
  Database = database "Database"
}

Use Metadata to Mark External Systems

External systems get metadata tags so everyone knows they're outside your boundary.

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external", "vendor"]
    owner "Stripe"
    sla "99.9% uptime"
  }
}

I always add context to external systems: who owns it, what the SLA is, any relevant compliance requirements. This helps people understand the risk and dependency.

Use person for External Actors

Remember: people are always outside your system boundary.

// Users are external to your system
Customer = person "Customer"
Administrator = person "Administrator"
Support = person "Customer Support"

// Your system
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API"
}

// People interact with internal components
Customer -> Shop.WebApp "Browses products"
Administrator -> Shop.WebApp "Manages inventory"
Support -> Shop.WebApp "Monitors health"

People are the actors who use your system. They're not "inside" your system—they interact with it from the outside. Always model them as separate entities.

What to Remember

Boundaries are about clarity—clarity of ownership, clarity of risk, clarity of responsibility. When you draw boundaries:

• Be intentional: Every boundary should represent something meaningful (ownership, trust, deployment)
• Mark external systems clearly: Use metadata tags so everyone knows what's outside your control
• Document crossings: Every relationship that crosses a boundary is an integration point that needs attention
• Avoid fragmentation: Group related functionality into coherent systems
• Think about risk: Every boundary crossing introduces external risk—plan for it

If you take away one thing, let it be this: clear boundaries prevent confusion, reduce risk, and make your architectures more maintainable. Everything else flows from that principle.

Check Your Understanding

Let's see if you've got this. Here are a couple of questions to test your understanding.

Question 1

You're modeling a healthcare platform with these requirements:

"A hospital scheduling system allows patients to book appointments, doctors to manage their schedules, and administrators to oversee operations. The system integrates with an external insurance API for coverage verification and sends SMS notifications through Twilio. Patient data is stored in the hospital's database."

Which parts should be modeled as outside the system boundary (external)?

A) Patients, Doctors, Administrators, Insurance API, Twilio B) Insurance API, Twilio, Hospital Database C) Patients, Doctors, Administrators D) Insurance API, Twilio, Hospital Scheduling System

Question 2

You're reviewing an architecture diagram and notice this structure:

Shop = system "Shop"
PaymentGateway = system "Payment Gateway"
EmailService = system "Email Service"
AnalyticsService = system "Analytics Service"

Shop.WebApp -> Shop.API "Requests"
Shop.API -> PaymentGateway "Process payment"
Shop.API -> EmailService "Send email"
Shop.API -> AnalyticsService "Track events"

What's the main problem with this diagram from a boundaries perspective?

A) The Shop system doesn't have containers B) External systems aren't marked as external C) There are too many external dependencies D) The relationships are too generic

// Your system (no tags = internal)
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API Service"
}

// External systems (marked clearly)
PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external", "vendor"]
    owner "Stripe"
  }
}

EmailService = system "Email Service" {
  metadata {
    tags ["external", "vendor"]
    owner "SendGrid"
  }
}

AnalyticsService = system "Analytics Service" {
  metadata {
    tags ["external", "vendor"]
    owner "Google"
  }
}

What's Next?

Now you understand what boundaries are and why they matter. You know how to identify different types of boundaries and mark them clearly in your diagrams.

But there's a question we haven't answered: how do you actually mark components as internal or external in Sruja? How do you use metadata effectively to document ownership and dependencies?

In the next lesson, you'll learn exactly that. We'll cover how to annotate boundary elements, model team and organizational boundaries, and create diagrams that make it instantly clear what's inside versus what's outside.

See you there!

Inside and Outside: Internal vs External

Remember those "Keep Out" signs you'd see on fences as a kid? They were clear markers: this side is private, that side is public. Inside the fence, you had your rules. Outside, it was anyone's territory.

Boundaries in software work the same way, but instead of fences, we use metadata and tags. These markers tell everyone what's inside your boundary (what you control) and what's outside (what you depend on but don't control).

In this lesson, you'll learn to mark these boundaries clearly in Sruja. You'll discover how to annotate external systems, document ownership, and make your diagrams instantly readable by anyone who picks them up.

Learning Goals

By the end of this lesson, you'll be able to:

• Use Sruja metadata to mark external systems clearly
• Document ownership and responsibility for each system
• Model team and organizational boundaries effectively
• Create diagrams that make internal/external distinctions instantly visible
• Add meaningful context (SLAs, compliance, contact info) to external systems

Marking External Systems: The Basics

The simplest way to mark something as external is using metadata tags. Let me show you the pattern I use consistently:

// Internal: Your system (no tags = internal by default)
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API Service"
}

// External: Third-party system you depend on
PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
  }
}

The tags ["external"] is the marker. It tells anyone reading your diagram: "This is outside our boundary. We don't control it. Plan accordingly."

This simple tag transforms a diagram from "a bunch of boxes" into "a clear picture of what we own versus what we depend on."

Adding Rich Context to External Systems

I've learned that just marking something as "external" often isn't enough. People want to know: Who owns it? What's the SLA? Who do I call when it breaks? How do we connect?

Let me show you how I add this context.

External System with Ownership

Stripe = system "Stripe" {
  metadata {
    tags ["external", "vendor"]
    owner "Stripe Inc."
    support "support@stripe.com"
  }
}

Now anyone looking at the diagram knows:

• It's external (tags ["external"])
• It's a vendor (tags ["vendor"])
• Who owns it (owner "Stripe Inc.")
• Who to contact for support (support "support@stripe.com")

I include this information because when something breaks at 3 AM (and it will), you don't want to be hunting through documentation trying to figure out who owns what.

External System with SLA Information

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
    sla "99.9% uptime"
    mttr "4 hours"
    support "24/7 enterprise support"
  }
}

SLA (Service Level Agreement) information is crucial for understanding risk:

• 99.9% uptime means ~43 minutes of downtime per month
• mttr (Mean Time To Repair) tells you how quickly they commit to fixing issues
• 24/7 enterprise support tells you response time expectations

I always add SLA information for critical external dependencies. It helps teams understand what they're committing to.

External System with Compliance Requirements

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external", "pci-compliant"]
    compliance ["PCI-DSS Level 1"]
    security ["TLS 1.3", "Mutual TLS"]
  }
}

For highly regulated industries (healthcare, finance, government), compliance information is essential. It tells you:

• What standards the external system meets
• What security controls are in place
• Whether you can use it for sensitive data

I once worked on a healthcare project where someone chose an email provider without checking HIPAA compliance. We had to rebuild the integration later. Lesson learned: document compliance requirements upfront.

Common Boundary Patterns

After modeling hundreds of systems, I've noticed patterns that repeat constantly. Let me show you the ones I see most often.

Pattern 1: Third-Party Services

This is the most common pattern—integrating with vendors who provide specialized services.

// Your system
Shop = system "Shop"

// Third-party integrations
Stripe = system "Stripe" {
  metadata {
    tags ["external", "vendor", "pci-compliant"]
    owner "Stripe"
    sla "99.99% uptime"
    api_endpoint "https://api.stripe.com/v1"
    authentication "API Key"
  }
}

Twilio = system "Twilio" {
  metadata {
    tags ["external", "vendor"]
    owner "Twilio"
    sla "99.9% uptime"
    api_endpoint "https://api.twilio.com"
  }
}

GoogleAnalytics = system "Google Analytics" {
  metadata {
    tags ["external", "vendor"]
    owner "Google"
    privacy_policy "https://policies.google.com/privacy"
  }
}

// Integration relationships
Shop.API -> Stripe "Process payment" [encrypted, tls1.3]
Shop.API -> Twilio "Send SMS" [encrypted]
Shop.API -> GoogleAnalytics "Track events" [anonymous]

Notice how each vendor gets different context based on what matters:

• Stripe: PCI compliance, strict SLA, API endpoint details
• Twilio: SLA, API endpoint
• Google Analytics: Privacy policy (because it's tracking users)

The key insight: add metadata that matters for that specific integration. Don't copy-paste the same structure for every external system.

Pattern 2: Partner Integrations

Partners are different from vendors—they're external organizations you have contractual relationships with.

// Your system
Shop = system "Shop"

// Partner systems (B2B integrations)
LogisticsPartner = system "Logistics Partner API" {
  metadata {
    tags ["external", "partner"]
    owner "FedEx"
    sla "99.5% uptime"
    api_documentation "https://partners.fedex.com/api"
    contact "partnership@fedex.com"
  }
}

InventoryPartner = system "Inventory Partner" {
  metadata {
    tags ["external", "partner"]
    owner "Vendor X"
    sla "99.0% uptime"
    contract "CONTRACT-2024-INV-001"
  }
}

// Partner relationships
Shop.API -> LogisticsPartner "Ship order"
Shop.API -> InventoryPartner "Check stock"

Partner integrations often have:

• Different SLA expectations than public vendors
• Contractual obligations
• Dedicated partnership contacts
• Custom API documentation

I always add contract references for partner systems. When disputes arise about service levels, you want the contract number readily available.

Pattern 3: Internal Team Boundaries

Sometimes the boundary isn't between your company and outside world—it's between teams within your organization.

// Your team's system
Shop = system "Shop" {
  metadata {
    tags ["internal", "shop-team"]
    owner "Shop Team"
    slack "#shop-team"
    repository "github.com/company/shop"
  }
  WebApp = container "Web App"
  API = container "API"
}

// Another team's systems (internal but different ownership)
UserPlatform = system "User Platform" {
  metadata {
    tags ["internal", "platform-team"]
    owner "Platform Team"
    slack "#platform-team"
  }
  AuthService = container "Auth Service"
  UserProfile = container "User Profile"
}

AnalyticsPlatform = system "Analytics Platform" {
  metadata {
    tags ["internal", "data-team"]
    owner "Data Team"
    slack "#data-team"
  }
  EventCollector = container "Event Collector"
  DataWarehouse = database "Data Warehouse"
}

// Cross-team boundaries
Shop.API -> UserPlatform.AuthService "Authenticate user"
Shop.API -> AnalyticsPlatform.EventCollector "Send events"

Internal team boundaries are crucial for:

• Communication: Who do I talk to when something breaks?
• Coordination: How do we coordinate changes?
• Escalation: Who's responsible when issues arise?

I include Slack channel references for internal systems. It's the fastest way to get help or ask questions.

People: Always External

Here's a rule I never break: people are always outside your system boundary.

They're not "inside" your system—they're actors who interact with it from the outside.

// External actors (always outside boundary)
Customer = person "Customer"
Administrator = person "Administrator"
SupportAgent = person "Customer Support"

// Your system (the boundary)
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API"
  Database = database "Database"
}

// People interact with your system, they're not part of it
Customer -> Shop.WebApp "Browses products"
Customer -> Shop.WebApp "Adds to cart"
Customer -> Shop.WebApp "Checks out"

Administrator -> Shop.WebApp "Manages products"
Administrator -> Shop.WebApp "Views reports"

SupportAgent -> Shop.WebApp "Monitors health"

Why does this matter?

1. Ownership clarity: People aren't "owned" by your system. They're autonomous actors who choose to interact with it.
2. Security perspective: People are untrusted by default. You need to authenticate, authorize, and validate everything they do.
3. Testing strategy: You can unit test internal components, but you need to test user interactions differently (end-to-end tests, user acceptance tests).

I've seen diagrams where people are modeled inside the system, and it always creates confusion. Are they part of the system? Do you control them? No—people are always external.

Modeling Boundary Crossings

Every relationship that goes from internal to external (or vice versa) crosses a boundary. These crossings are integration points that need special attention.

Single Boundary Crossing

// Internal system
Shop = system "Shop" {
  API = container "API"
}

// External system
PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
  }
}

// Crossing the boundary
Shop.API -> PaymentGateway "Process payment"

This relationship crosses from internal (your API) to external (payment gateway). That means:

• You need integration tests
• You need error handling for failures
• You need to consider timeout strategies
• You need to understand the failure modes

Multiple Boundary Crossings

Customer = person "Customer"

// Internal
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API"
}

// External systems (multiple)
PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
  }
}

EmailService = system "Email Service" {
  metadata {
    tags ["external"]
  }
}

AnalyticsService = system "Analytics Service" {
  metadata {
    tags ["external"]
  }
}

// Multiple boundary crossings
Customer -> Shop.WebApp "Places order"           // Person to System
Shop.WebApp -> Shop.API "Process order"          // Internal (same boundary)
Shop.API -> PaymentGateway "Charge payment"       // Internal → External
Shop.API -> EmailService "Send confirmation"      // Internal → External
Shop.API -> AnalyticsService "Track event"         // Internal → External

This system has three external dependencies. Each crossing represents:

• Risk: What happens if that external service is down?
• Complexity: Integration testing, error handling, fallback strategies
• Performance: Network latency, rate limits, timeouts

When I see many boundary crossings like this, I ask: "Do we really need all these external services?" Sometimes consolidating reduces complexity and risk.

Team Boundaries in Practice

Let me show you a real-world example of how team boundaries work in a larger organization.

Single Team, One System (Simple)

// One team owns everything
Shop = system "Shop" {
  metadata {
    tags ["internal", "shop-team"]
    owner "Shop Team"
    slack "#shop-team"
  }
  WebApp = container "Web App"
  API = container "API"
  Database = database "Database"
}

This is the ideal scenario. One team, one system, clear ownership. Everything inside is your team's responsibility.

Multiple Teams, Bounded Contexts (Realistic)

// Team A: Shop team
Shop = system "Shop" {
  metadata {
    tags ["internal", "shop-team"]
    owner "Shop Team"
    slack "#shop-team"
    repository "github.com/company/shop"
  }
  WebApp = container "Web App"
  API = container "API"
}

// Team B: Payment team
Payment = system "Payment Service" {
  metadata {
    tags ["internal", "payment-team"]
    owner "Payment Team"
    slack "#payment-team"
    repository "github.com/company/payment"
  }
  Processor = container "Payment Processor"
}

// Team C: Notification team
Notifications = system "Notification Service" {
  metadata {
    tags ["internal", "notification-team"]
    owner "Notification Team"
    slack "#notification-team"
    repository "github.com/company/notifications"
  }
  Sender = container "Notification Sender"
}

// Cross-team boundaries (each is a coordination point)
Shop.API -> Payment.Processor "Process payment"
Shop.API -> Notifications.Sender "Send notification"

This is more realistic in larger organizations. Different teams own different systems, each with their own repositories, Slack channels, and processes.

The boundary crossings between teams matter because:

• Coordination: Changes need to be coordinated across teams
• Testing: Cross-team integrations need integration tests
• Communication: Who do you talk to when something breaks?

I include Slack channels and repository links for every internal system. It saves so much time when you're trying to figure out who to contact or where to look at code.

Creating Views for Different Audiences

One of the most powerful features of Sruja is creating different views for different audiences. Let me show you how.

System Context View (Shows All Boundaries)

view system_context {
  title "System Context - Internal vs External"
  include *
}

This view shows everything:

• Your systems
• External systems
• People
• All relationships

Perfect for stakeholders who want to see the big picture, including dependencies and risks.

Internal-Only View (Shows Just Your System)

view internal_view of Shop {
  title "Internal Architecture"
  include Shop.*
}

This view shows only what's inside your boundary:

• Your containers
• Your components
• Your internal relationships

Perfect for developers who are working on the system and don't need to see external dependencies.

External-Only View (Shows Dependencies)

view external_view of Shop {
  title "External Dependencies"
  exclude Shop.*
}

This view shows only what's external:

• Third-party systems
• Partner systems
• Dependencies you rely on

Perfect for risk management, dependency reviews, and vendor assessments.

What to Remember

Marking internal vs. external is about clarity—clarity of ownership, clarity of risk, clarity of responsibility. When you annotate your diagrams:

• Always mark external systems: Use metadata { tags ["external"] }
• Add meaningful context: Ownership, SLA, support contacts, compliance
• Document team boundaries: Include Slack channels, repository links
• Remember: people are external: They're never inside your system boundary
• Show boundary crossings: Every crossing is an integration point
• Create multiple views: Different audiences need different perspectives

If you take away one thing, let it be this: clearly annotated boundaries prevent confusion and make your diagrams immediately useful to anyone who picks them up, whether they're on your team or not.

Check Your Understanding

Let's see if you've got this. Here are a couple of questions to test your understanding.

Question 1

You're modeling a healthcare platform and want to mark external dependencies correctly. Which metadata structure is best for an external payment gateway?

A)

PaymentGateway = system "Payment Gateway" {
  metadata {
    owner "Stripe"
  }
}

B)

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
    owner "Stripe"
    sla "99.9% uptime"
    support "support@stripe.com"
  }
}

C)

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["internal", "payment"]
    owner "Payment Team"
  }
}

D)

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["vendor", "pci-compliant"]
    api_endpoint "https://api.stripe.com"
  }
}

Question 2

You're reviewing an architecture diagram and notice this structure:

Shop = system "Shop"
PaymentGateway = system "Payment Gateway"
EmailService = system "Email Service"

Shop.API -> PaymentGateway "Process payment"
Shop.API -> EmailService "Send confirmation"

What's missing from a boundaries perspective?

A) Containers for Shop system B) Metadata tags marking external systems C) Person elements for users D) Component-level breakdown

// Your system (internal)
Shop = system "Shop" {
  metadata {
    tags ["internal"]
    owner "Shop Team"
  }
  WebApp = container "Web App"
  API = container "API"
}

// External systems (clearly marked)
PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external", "vendor"]
    owner "Stripe"
    sla "99.9% uptime"
  }
}

EmailService = system "Email Service" {
  metadata {
    tags ["external", "vendor"]
    owner "SendGrid"
    sla "99.9% uptime"
  }
}

Shop.API -> PaymentGateway "Process payment"
Shop.API -> EmailService "Send confirmation"

What's Next?

Now you know how to mark internal and external components clearly. You can annotate external systems with ownership, SLAs, and support information. You can model team boundaries and create different views for different audiences.

But we've only talked about defining boundaries. We haven't talked about what happens when you cross them.

In the next lesson, you'll learn about crossing boundaries—how to model integrations, plan for failures, document interface contracts, and design fallback strategies. You'll discover why every boundary crossing is both an opportunity and a risk.

See you there!

Crossing the Line: Integrations at Boundaries

Imagine crossing a border between countries. You need a passport, you might wait in customs, and there are rules about what you can bring across. Sometimes the border is open and easy to cross. Sometimes it's closed, and you're stuck.

Boundaries in software architecture work the same way. Every time you cross from your internal system to an external one, you're dealing with integration complexity, potential failures, and risks you don't control.

In this lesson, you'll learn to model these boundary crossings effectively. You'll discover how to plan for failures, document interface contracts, and design fallback strategies that keep your system resilient when external dependencies misbehave.

Let's start by understanding what boundary crossings actually are.

Learning Goals

By the end of this lesson, you'll be able to:

• Model integrations across boundaries clearly
• Identify different integration patterns and when to use each
• Plan for common failure scenarios at boundaries
• Document interface contracts that prevent misunderstandings
• Design fallback strategies that keep your system resilient

Boundary Crossings: The Reality

Every relationship that goes from internal to external (or external to internal) is a boundary crossing. These are the riskiest parts of your system.

// Internal → External = Boundary crossing
Shop.API -> PaymentGateway "Process payment"

// External → Internal = Boundary crossing
PaymentGateway -> Shop.API "Payment result"

Why are these risky? Because you don't control what's on the other side.

I learned this the hard way early in my career. We had an e-commerce site that depended on a single payment gateway. When that gateway went down for six hours during Black Friday, we lost millions in sales because we hadn't planned for boundary failures.

Lesson learned: every boundary crossing is a potential failure point. Plan accordingly.

Integration Patterns You'll Use

After years of building systems, I've found there are really three main integration patterns you'll encounter. Understanding which one you're using helps you plan correctly.

Pattern 1: Request-Response (Synchronous)

This is the most common pattern. You send a request, you wait for a response.

Shop.API -> PaymentGateway "Process payment"
PaymentGateway -> Shop.API "Payment result"

Characteristics:

• Synchronous — Your system waits for the response
• Real-time — The customer sees the result immediately
• Tight coupling — If the external service is down, you're down too
• Simple to implement — One call, one response

When to use it:

• When you need an immediate response (payment processing, real-time validation)
• When the operation is critical to the user's workflow
• When the external service has good uptime guarantees

Risks:

• Your users wait if the external service is slow
• Your system fails if the external service is down
• Timeouts need to be configured carefully

This is the pattern I see most often. It's simple, but it's fragile if you don't handle failures properly.

Pattern 2: Event-Driven (Asynchronous)

You publish an event, and other systems process it whenever they can.

Shop.API -> EventQueue "Publish order created"
EventQueue -> PaymentProcessor "Consume order event"
EventQueue -> EmailService "Consume order event"

Characteristics:

• Asynchronous — You don't wait for a response
• Decoupled — Your system continues even if others are slow
• Resilient — If a consumer fails, the queue buffers events
• More complex — You need infrastructure (Kafka, RabbitMQ, etc.)

When to use it:

• When the operation can happen in the background (sending emails, updating analytics)
• When you have multiple consumers who need to process the same event
• When you want resilience and fault tolerance

Risks:

• Eventual consistency (the user sees "processing" before it's actually done)
• More complex infrastructure to maintain
• Harder to debug when things go wrong

I used to think event-driven was overkill for small systems. Then I built a notification system that sent welcome emails, onboarding sequences, and marketing emails. Trying to send all those synchronously was a nightmare. Moving to events made everything so much smoother.

Pattern 3: Polling

Your system periodically checks for updates from an external service.

Shop.API -> ExternalAPI "Check order status"
ExternalAPI -> Shop.API "Return status"

Characteristics:

• Periodic — You check on a schedule (every minute, every hour, etc.)
• Simple — No webhooks or real-time infrastructure needed
• Less efficient — You make calls even when nothing has changed
• Eventual — There's always a delay between an event and when you discover it

When to use it:

• When the external service doesn't support webhooks
• When you need to check status periodically (order fulfillment, shipment tracking)
• When the external API doesn't have push notifications

Risks:

• You're wasting resources polling when nothing changes
• There's always a delay before you see updates
• Rate limiting can become an issue

I only use polling when I have no other choice. It's simple, but it's inefficient and introduces latency.

Integration Considerations (What Actually Matters)

Now that you know the patterns, let's talk about what you actually need to think about when crossing boundaries.

1. Error Handling: What Happens When It Breaks?

External services fail. It's not a question of "if," it's "when."

// Document expected failure modes
PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
    sla "99.9% uptime"
    failure_modes ["timeout", "service unavailable", "network error", "rate limit"]
  }
}

// Model fallbacks
Shop.API -> PrimaryPayment "Process payment" [primary]
Shop.API -> BackupPayment "Process payment" [fallback]

I've seen systems that don't document failure modes. When something breaks, nobody knows what to expect. Does the external service retry automatically? Do they return specific error codes? What's the timeout?

Document this upfront. It saves hours of debugging later.

2. Timeouts and Latency: How Long Is Too Long?

External services can be slow. You need to configure timeouts that protect your system without being too aggressive.

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
    timeout "30s"
    expected_latency "500ms"
    max_latency "5s"
  }
}

Shop.API = container "API Service" {
  slo {
    latency {
      p95 "200ms"  // 95% of requests complete in 200ms
      p99 "500ms"  // 99% of requests complete in 500ms
    }
  }
}

I once worked on a system that had no timeout configured. An external service got slow, and our threads hung indefinitely. The entire system ground to a halt.

Set timeouts. Always. Even if the external service is usually fast.

3. Data Consistency: What Happens When Things Go Wrong?

What if the payment succeeds but saving the order fails? Or the order saves but the payment fails?

Shop.API -> PaymentGateway "Process payment"
Shop.API -> Shop.Database "Save order"

// If payment succeeds but order save fails:
// - Did you charge the customer?
// - Is the order lost?
// - How do you reconcile?

You need strategies for handling this:

• Idempotent payment calls — Calling the same payment ID twice should only charge once
• Compensating transactions — If the order save fails after payment, refund automatically
• Eventual consistency — Accept that things might be inconsistent briefly, then reconcile
• Two-phase commits — Complex, but guarantees consistency

I once worked on a system where we charged customers but lost their orders. We spent weeks manually reconciling payments and orders. Awful experience.

Plan for consistency issues at boundaries. They will happen.

4. Security: What Protects Your Data?

Crossing a boundary is where attacks happen. This is where you need to be most careful.

// Security at the boundary
Shop.API -> PaymentGateway "Process payment" [encrypted, authenticated, tls1.3]

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external", "pci-compliant"]
    security ["mutual TLS", "API key authentication"]
    compliance ["PCI-DSS Level 1"]
  }
}

Security controls at boundaries:

• Authentication — Prove who you are
• Authorization — Prove you're allowed to do what you're asking
• Encryption — Protect data in transit
• Validation — Don't trust anything coming from outside

I learned this lesson painfully. We had an internal API that we exposed to the web without proper validation. Someone sent malformed requests that brought down our database.

Validate everything at your boundaries. Trust nothing from external systems.

Documenting Interface Contracts

One of the most important things you can do for boundary crossings is document the interface contract. This is the agreement between your system and the external one.

API Contract

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
    api_endpoint "https://api.payment.com/v1"
    authentication "API Key (Bearer token)"
    rate_limit "1000 req/min"
    supported_methods ["POST /charges", "GET /charges/:id", "POST /refunds"]
  }
}

Shop.API = container "API Service" {
  metadata {
    api_consumer "Payment Gateway Client"
    retry_policy "3 retries with exponential backoff"
    circuit_breaker "Enabled (5 failures = open for 60s)"
  }
}

This contract tells everyone:

• Where the API is
• How to authenticate
• What methods are available
• What limits exist
• How to handle retries and failures

I've seen so many integration disasters because nobody documented the contract. Teams assumed different APIs, different limits, different behaviors. When something changed, everything broke.

Document your interface contracts. Make them explicit.

Data Format

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
    data_format "JSON"
    schema_version "v1.2"
    validation "Strict schema validation"
    date_format "ISO 8601 (UTC)"
    currency_format "ISO 4217 (e.g., 'USD')"
  }
}

Don't let data format be implicit. Specify:

• JSON vs. XML vs. Protocol Buffers
• Schema version (what happens when it changes?)
• Date formats (timezone matters!)
• Currency formats
• Number formats (decimal precision, rounding)

I once dealt with a system where dates were sometimes in US format (MM/DD/YYYY) and sometimes in ISO format (YYYY-MM-DD), depending on which service you called. Bugs everywhere.

SLA and Reliability

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
    sla "99.9% uptime"
    mttr "4 hours"  // Mean Time To Repair
    support_tier "24/7 enterprise support"
    escalation_path "Support → Account Manager → CTO"
  }
}

SLA documentation tells you:

• What uptime they're committing to
• How fast they'll fix things when they break
• Who to contact and how to escalate
• What compensation you get if they violate SLA

Knowing the SLA helps you decide: do you need a fallback? Can you tolerate 43 minutes of downtime per month (99.9%)? Or do you need 99.99% (4 minutes)?

Fallback Strategies: Planning for Failure

External systems fail. You need fallback strategies. Here are the ones I use most often.

Strategy 1: Redundant Providers

Have a backup provider you can switch to if the primary fails.

// Primary provider
PrimaryPayment = system "Stripe" {
  metadata {
    tags ["external", "primary"]
    sla "99.99% uptime"
    owner "Stripe"
  }
}

// Backup provider
BackupPayment = system "PayPal" {
  metadata {
    tags ["external", "backup"]
    sla "99.9% uptime"
    owner "PayPal"
  }
}

// Try primary, fall back to backup
Shop.API -> PrimaryPayment "Process payment" [primary]
Shop.API -> BackupPayment "Process payment" [fallback]

Why this works: If Stripe is down, you can still process payments through PayPal.

Challenge: Supporting two payment gateways is complex. You need to reconcile transactions, handle different APIs, manage different fee structures.

I've used this strategy for critical paths (payments, messaging, notifications). It adds complexity, but it buys you resilience.

Strategy 2: Circuit Breaker

Stop calling a failing service automatically instead of hammering it with requests.

Shop.API = container "API Service" {
  metadata {
    circuit_breaker {
      enabled true
      failure_threshold 5  // Open after 5 failures
      recovery_timeout "60s"  // Try again after 60 seconds
      half_open_attempts 3  // Send 3 test requests before closing
    }
  }
}

How it works:

1. Closed — Normal operation, requests go through
2. Open — After N failures, stop sending requests
3. Half-open — After timeout, send a few test requests
4. Closed — If tests succeed, go back to normal

Why this works: Instead of hammering a failing service with 1000 requests/second (which might make recovery worse), you stop calling it and fail fast.

This is one of my favorite patterns. It's saved me from cascading failures more times than I can count.

Strategy 3: Degraded Mode

Continue operating even if a non-critical external service is down.

// Non-critical: If analytics fails, continue
Shop.API -> AnalyticsService "Track events" [non_critical]

// Queue for later: If email fails, queue it
Shop.API -> EmailService "Send notifications" [async_queue]

Why this works: Not every external dependency is critical. If analytics is down, you can still process orders. If email is down, queue messages and send later.

What this requires: You need to distinguish between:

• Critical paths — System can't function without them (payments)
• Important paths — System functions, but with degraded UX (email, push notifications)
• Nice-to-have paths — System functions perfectly without them (analytics)

I used to treat all dependencies as critical. Then I realized: if analytics is down for an hour, does anyone actually care? No. Mark it non-critical and move on.

Strategy 4: Cache External Data

Cache responses from external APIs so you can serve from cache if the external service is down.

// External API call
Shop.API -> ExchangeRateAPI "Get exchange rates"

// Cache for backup
Shop.API -> Shop.Cache "Get cached rates"

// Fallback strategy
Shop.API -> ExchangeRateAPI "Get exchange rates" [primary]
Shop.API -> Shop.Cache "Get cached rates" [fallback]

Why this works: Even if the external API is down, you can serve slightly stale data from cache.

What to consider:

• How stale is acceptable? (10 minutes? 1 hour? 24 hours?)
• How do you detect when the external service is back up?
• Do you need to warm the cache before the service goes down?

I've used this for exchange rates, product catalogs, weather data—anything that's expensive to fetch and acceptable to serve slightly stale.

Complete Integration Example

Let me show you a complete example that brings everything together.

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

// People
Customer = person "Customer"

// Your system
Shop = system "Shop" {
  metadata {
    tags ["internal"]
    owner "Shop Team"
    slack "#shop-team"
  }

  WebApp = container "Web Application"
  API = container "API Service" {
    metadata {
      timeout "30s"
      retry_policy "3 retries with exponential backoff"
      circuit_breaker {
        enabled true
        failure_threshold 5
        recovery_timeout "60s"
      }
    }
  }
  Cache = database "Redis Cache"
}

// Primary payment provider
Stripe = system "Stripe" {
  metadata {
    tags ["external", "primary", "vendor"]
    owner "Stripe Inc."
    sla "99.99% uptime"
    mttr "4 hours"
    api_endpoint "https://api.stripe.com/v1"
    authentication "API Key (Bearer token)"
    rate_limit "1000 req/min"
    data_format "JSON"
    schema_version "v1.2"
    security ["TLS 1.3", "API key authentication"]
    compliance ["PCI-DSS Level 1"]
    support "24/7 enterprise support"
    escalation_path "Support → Account Manager → CTO"
  }
}

// Backup payment provider
PayPal = system "PayPal" {
  metadata {
    tags ["external", "backup", "vendor"]
    owner "PayPal"
    sla "99.9% uptime"
    api_endpoint "https://api.paypal.com/v2"
    authentication "OAuth 2.0"
  }
}

// Email service
SendGrid = system "SendGrid" {
  metadata {
    tags ["external", "vendor"]
    owner "SendGrid"
    sla "99.9% uptime"
    timeout "10s"
    api_endpoint "https://api.sendgrid.com/v3"
  }
}

// Integrations
Customer -> Shop.WebApp "Checkout"
Shop.WebApp -> Shop.API "Process order"

// Primary payment (encrypted, authenticated)
Shop.API -> Stripe "Process payment" [primary, encrypted, tls1.3]
Stripe -> Shop.API "Payment result"

// Fallback to backup if Stripe fails
Shop.API -> PayPal "Process payment" [fallback, encrypted]

// Email (non-critical, can queue)
Shop.API -> SendGrid "Send confirmation" [non_critical, async_queue]

// Cache exchange rates
Shop.API -> ExchangeRateAPI "Get exchange rates"
Shop.API -> Shop.Cache "Get cached rates" [fallback]

view index {
  include *
}

This example shows:

• Clear external/internal boundaries with rich metadata
• Multiple integration patterns (synchronous payment, asynchronous email)
• Fallback strategies (backup provider, cache)
• Failure documentation (timeouts, circuit breaker, retry policy)
• Interface contracts (API endpoints, authentication, data formats)

This is the kind of documentation that saves you when things go wrong at 3 AM.

What to Remember

Crossing boundaries is where systems are most fragile. When you model and plan for boundary crossings:

• Document everything — API contracts, failure modes, SLAs, security requirements
• Plan for failures — Timeouts, retries, circuit breakers, fallbacks
• Use the right pattern — Synchronous for critical paths, asynchronous for background work
• Protect your system — Authentication, encryption, validation at every boundary
• Design resilience — Redundant providers, caching, degraded modes
• Test thoroughly — Integration tests, chaos engineering, failure scenarios

If you take away one thing, let it be this: every boundary crossing is both an opportunity and a risk. The opportunity is integrating with powerful external services. The risk is depending on something you don't control. Plan for that risk.

Check Your Understanding

Let's see if you've got this. Here are a couple of questions to test your understanding.

Question 1

You're modeling a weather application that fetches data from an external API. Which integration pattern is most appropriate?

"The weather app needs to display current weather and 7-day forecasts for cities around the world. Users expect to see real-time weather data. The external weather API has good uptime and supports synchronous calls."

A) Request-Response (Synchronous) B) Event-Driven (Asynchronous) C) Polling D) All of the above are equally appropriate

Question 2

You're designing the payment processing flow for an e-commerce platform. The payment gateway has an SLA of 99.9% uptime. What does this mean for your system?

A) You don't need to worry about failures—99.9% is very reliable B) You should have a fallback strategy because 99.9% still means ~43 minutes of downtime per month C) You should only process payments when the gateway is at 100% uptime D) You should switch to a different payment gateway immediately

What's Next?

Congratulations! You've completed Module 3: Boundaries. You now understand:

• What boundaries are and why they matter for ownership, risk, and clarity
• How to mark internal vs. external components using metadata and tags
• How to model boundary crossings with proper planning for failures and fallbacks

You can now create architectures that clearly distinguish what you control from what you depend on. You can plan for failures at boundaries instead of being surprised by them. You can document interface contracts that prevent integration disasters.

You're building resilient systems.

In the next module, you'll learn about flows—how information moves through your system over time. You'll discover how to model data flow, process flows, and temporal behaviors that tell a richer story than static diagrams can.

See you there!

Module 3 Complete!

You've now mastered the art of defining and crossing boundaries. Here's what you've learned:

Lesson 1: Understanding Boundaries

• Boundaries separate what's inside from what's outside
• Multiple types of boundaries: system, team, organization, deployment, trust
• Clear boundaries prevent confusion and clarify ownership

Lesson 2: Internal vs. External

• Use metadata tags to mark external systems clearly
• Document ownership, SLAs, and support contacts
• Remember: people are always outside your system boundary
• Create different views for different audiences

Lesson 3: Crossing Boundaries

• Every boundary crossing is an integration point and potential failure
• Choose the right integration pattern (synchronous, asynchronous, polling)
• Document interface contracts (API endpoints, data formats, security)
• Design fallback strategies (redundant providers, circuit breakers, degraded modes, caching)
• Plan for failures—they will happen

You're ready to tackle more advanced concepts. Let's continue!

Module 4: Flows

Overview

In this module, you'll learn to model how information, data, and actions move through your system. Flows help you understand data lineage, process sequences, and bottlenecks.

Learning Objectives

By the end of this module, you'll be able to:

• Model data flows using Sruja scenarios
• Document user journeys and workflows
• Identify bottlenecks and performance issues
• Differentiate between data flows and behavioral flows

Lessons

• Lesson 1: Understanding Flows - What flows are and when to use them
• Lesson 2: Data Flow Diagrams - Modeling DFD-style data flows
• Lesson 3: User Journeys - Modeling behavioral scenarios

Prerequisites

• Completed Module 3: Boundaries

Time Investment

Approximately 1.5-2 hours to complete all lessons and exercises.

What's Next

After completing this module, you'll learn about Module 5: Feedback Loops.

Seeing Movement: Understanding Flows

Ever watch water flow down a stream? You can see the path it takes, where it speeds up, where it slows down, where it gets stuck. Static diagrams show you the rocks and the banks, but they don't show you how the water actually moves through the system.

That's what flows are for in architecture—they show you how information, data, and actions move through your system over time. Static relationships tell you what's connected. Flows tell you what happens.

In this lesson, you'll learn to model flows effectively. You'll discover different types of flows, when to use them, and how they reveal bottlenecks, errors, and opportunities that static diagrams miss.

Let's start by understanding what flows actually are and why they matter.

Learning Goals

By the end of this lesson, you'll be able to:

• Understand what flows are and how they differ from static relationships
• Recognize different types of flows (data, user journeys, control, event)
• Know when to use flows versus static diagrams
• Model flows at the right level of detail
• Identify common pitfalls and avoid them

What Are Flows, Really?

At its simplest level, a flow shows sequence—how something moves from point A to point B to point C. Unlike static relationships that just say "A is connected to B," flows tell you "A talks to B, then B talks to C, and here's what happens at each step."

Static Relationship vs. Flow

Let me show you the difference:

// Static relationship: Just shows connection
Customer -> Shop.WebApp "Uses"

// Flow: Shows the sequence
CheckoutFlow = scenario "Customer Checkout" {
  Customer -> Shop.WebApp "Submits order"
  Shop.WebApp -> Shop.API "Sends order data"
  Shop.API -> Shop.Database "Saves order"
  Shop.API -> PaymentGateway "Processes payment"
  PaymentGateway -> Shop.API "Returns result"
  Shop.API -> Shop.WebApp "Confirmation"
  Shop.WebApp -> Customer "Show success page"
}

The static relationship just tells you "customer uses the web app." The flow tells you the complete sequence—what the customer does, what the web app does, what the API does, in what order, and what happens at each step.

Why This Matters

I once worked on a system where we had perfect static diagrams showing all the components. But nobody understood the actual order processing flow. When we debugged issues, we'd spend hours tracing through code because the diagrams didn't show sequence.

We added flows, and suddenly everything became clear. Developers could see the complete path from customer action to database storage. Product managers could see exactly what users experienced. Everyone had the same mental model of how things moved through the system.

Why Flows Matter: The Real Benefits

After years of modeling systems, I've found flows reveal things static relationships never can. Let me show you what flows actually surface.

1. Data Lineage: Where Does Data Come From?

Flows show you the complete path data takes through your system—where it starts, how it's transformed, and where it ends up.

OrderAnalyticsFlow = flow "Order Data Lineage" {
  // Where data starts
  Customer -> Shop.WebApp "Order details"
  
  // How data flows through system
  Shop.WebApp -> Shop.API "Order JSON payload"
  Shop.API -> Shop.Database "Persist order record"
  
  // Where data goes for analytics
  Shop.Database -> Analytics.Extractor "Extract order events"
  Analytics.Extractor -> Analytics.Processor "Enrich with user data"
  Analytics.Processor -> Analytics.Warehouse "Store aggregated metrics"
  
  // Where data is ultimately used
  Analytics.Warehouse -> Dashboard.Query "Fetch metrics"
  Dashboard.Query -> BusinessUser "Display analytics"
}

This flow tells the complete story: customer creates an order, order flows through the app and API, gets persisted to the database, gets extracted for analytics, gets enriched and aggregated, stored in the data warehouse, and ultimately shows up on a business dashboard.

Without this flow, would you know the order data goes to a data warehouse? Would you know there's an enrichment step? Would you know business users depend on this data? Probably not.

2. Process Understanding: What's the Sequence?

Flows show you the exact sequence of actions that happen when something occurs. This is crucial for understanding how your system actually works.

OrderProcessFlow = scenario "Order Processing Sequence" {
  // Customer action
  Customer -> Shop.WebApp "Submits order"
  
  // API processing
  Shop.WebApp -> Shop.API "Validates cart"
  Shop.API -> Shop.Database "Checks inventory"
  Shop.Database -> Shop.API "Inventory available"
  
  // External integration
  Shop.API -> PaymentGateway "Charges payment"
  PaymentGateway -> Shop.API "Payment successful"
  
  // Order finalization
  Shop.API -> Shop.Database "Saves order"
  Shop.API -> InventoryService "Reserves items"
  Shop.API -> EmailService "Sends confirmation"
}

This flow reveals the complete sequence of what happens when an order is submitted. You can see exactly what the API does (validate, check inventory, charge, save, reserve, email). You can see the dependencies between steps (inventory must be available before charging). You can see the external integrations.

3. Bottleneck Identification: Where Can Things Slow Down?

Flows make bottlenecks obvious. You can see which steps might become slow, where queues might form, and where performance issues will surface first.

FileUploadFlow = scenario "File Upload" {
  // Fast steps
  User -> Frontend "Selects file and clicks upload"
  Frontend -> API "Sends file data"
  API -> Storage "Stores file" [fast]
  
  // Potential bottleneck
  Storage -> ProcessingService "Processes file" [slow, cpu-intensive]
  
  // Continues if processing succeeds
  ProcessingService -> Notification "Sends completion notification"
  Notification -> User "Receives notification"
}

Look at this flow. Storage is fast. Processing service is marked as "slow" and "CPU-intensive." This tells you immediately: the processing service is the bottleneck. If users complain about slow uploads, you know exactly where to look.

I've used this pattern countless times. A team would spend weeks optimizing the "fast" parts of the system while ignoring the actual bottleneck. Flows make bottlenecks obvious.

4. Error Paths: What Happens When Things Fail?

Static relationships show you the happy path. Flows let you model what happens when things go wrong.

OrderWithErrorsFlow = scenario "Order Processing with Error Handling" {
  Customer -> Shop.API "Submits order"
  Shop.API -> PaymentGateway "Charges payment"
  
  // Success path
  PaymentGateway -> Shop.API "Payment successful"
  Shop.API -> Shop.Database "Saves order"
  Shop.API -> EmailService "Sends confirmation"
  
  // Failure path
  PaymentGateway -> Shop.API "Payment declined"
  Shop.API -> Shop.WebApp "Returns error"
  Shop.WebApp -> Customer "Shows error message: Payment declined"
}

This flow models both the success path and the failure path. When the payment gateway returns a decline, the API returns an error to the web app, which displays it to the customer.

Modeling error paths is crucial. I once worked on a system where we'd only modeled happy paths. When failures occurred, we had no clear strategy for what should happen. Chaos ensued. Model both paths upfront.

Types of Flows You'll Use

After modeling systems for years, I've found there are really four main types of flows you'll encounter. Understanding which type you're modeling helps you get the details right.

1. Data Flow (DFD Style)

Data flows show how data moves and transforms as it passes through your system. Think of them like a pipeline—data goes in one end, gets transformed, and comes out the other.

OrderDataFlow = flow "Order Data Pipeline" {
  // Data originates from customer
  Customer -> Shop.WebApp "Order details"
  
  // Data flows through API as JSON
  Shop.WebApp -> Shop.API "Order JSON payload"
  
  // Data gets persisted as record
  Shop.API -> Shop.Database "Order record"
  
  // Data extracted as event
  Shop.Database -> Analytics.EventStream "Order event"
  
  // Data aggregated for reporting
  Analytics.EventStream -> Analytics.Aggregator "Daily aggregation"
  Analytics.Aggregator -> Analytics.Warehouse "Stored metrics"
}

Use data flows when:

• Modeling data lineage (where data comes from and goes)
• Documenting ETL processes
• Designing analytics pipelines
• Understanding data transformations

Characteristics:

• Focus on data, not actions
• Show how data changes shape/form
• Include storage and processing steps

2. User Journey / Scenario (BDD Style)

User journeys show how a person interacts with your system to achieve a goal. These are behavioral flows from the user's perspective.

CheckoutJourney = scenario "Customer Checkout Experience" {
  // User actions
  Customer -> Shop.WebApp "Clicks checkout button"
  Customer -> Shop.WebApp "Enters shipping address"
  Customer -> Shop.WebApp "Enters payment details"
  Customer -> Shop.WebApp "Clicks 'Place Order'"
  
  // System responses
  Shop.WebApp -> Shop.API "Validates cart"
  Shop.API -> PaymentGateway "Processes payment"
  PaymentGateway -> Shop.API "Payment successful"
  Shop.API -> Shop.Database "Saves order"
  
  // Final user experience
  Shop.WebApp -> Customer "Shows order confirmation page"
  Shop.API -> EmailService "Sends confirmation email"
  EmailService -> Customer "Receives confirmation email"
}

Use user journeys when:

• Modeling user stories and requirements
• Designing test scenarios
• Understanding customer experience
• Documenting acceptance criteria

Characteristics:

• User's perspective, not system's
• Include both user actions and system responses
• Show the complete experience from start to finish

3. Control Flow

Control flows show decision points and branching logic. They model the "if this, then that" parts of your system.

ApprovalFlow = scenario "Order Approval Workflow" {
  Order -> ApprovalService "Submits for approval"
  
  // Branch 1: Auto-approved (low value)
  ApprovalService -> Database "Saves as auto-approved" [if value < $100]
  
  // Branch 2: Manual review (high value)
  ApprovalService -> Manager "Sends approval request" [if value >= $100]
  Manager -> ApprovalService "Approves order"
  ApprovalService -> Database "Saves as approved"
  
  // Both paths converge
  Database -> EmailService "Sends order confirmation"
}

Use control flows when:

• Modeling business logic and rules
• Documenting decision trees
• Understanding conditional paths
• Designing workflow systems

Characteristics:

• Show decision points (if/else logic)
• Include multiple branches that may converge
• Document conditions for each branch

4. Event Flow

Event flows show how events propagate through an event-driven system. They model pub/sub patterns and event sourcing architectures.

OrderEventFlow = flow "Order Event Propagation" {
  // Event published
  OrderAPI -> EventBus "Publishes OrderCreated event"
  
  // Multiple consumers process same event
  EventBus -> NotificationService "Consumes event (sends confirmation)"
  EventBus -> AnalyticsService "Consumes event (tracks metrics)"
  EventBus -> InventoryService "Consumes event (reserves items)"
  EventBus -> EmailService "Consumes event (sends marketing email)"
}

Use event flows when:

• Modeling event-driven architectures
• Designing pub/sub systems
• Understanding event propagation
• Documenting event sourcing patterns

Characteristics:

• One event, multiple consumers
• Asynchronous processing
• Eventual consistency (events processed at different times)

Flow Patterns You'll See

Beyond types, there are structural patterns for how flows behave. Understanding these helps you recognize and model common scenarios.

Linear Flow

The simplest pattern—things happen one after another in a straight line.

LinearFlow = scenario "Simple Three-Step Process" {
  Step1 -> Step2 "Process A"
  Step2 -> Step3 "Process B"
  Step3 -> End "Process C"
}

Characteristics:

• Easy to understand
• No parallel processing
• Single point of failure
• Common in simple workflows

Branching Flow

One step branches into multiple possible paths. This is where your control flow logic lives.

BranchingFlow = scenario "Conditional Processing" {
  Start -> DecisionPoint "Initial processing"
  
  // Branch A: High priority
  DecisionPoint -> FastProcessor "Process immediately" [if priority = high]
  FastProcessor -> End "Complete"
  
  // Branch B: Low priority
  DecisionPoint -> Queue "Add to queue" [if priority = low]
  Queue -> SlowProcessor "Process when available"
  SlowProcessor -> End "Complete"
}

Characteristics:

• Multiple possible paths
• Based on conditions
• Paths may have different characteristics
• Common in workflows with approvals

Converging Flow

Multiple paths start separately but eventually come back together.

ConvergingFlow = scenario "Parallel then Merge" {
  // Parallel paths
  Start -> PathA "Process A"
  Start -> PathB "Process B"
  
  // Both paths converge
  PathA -> MergePoint "Contributes data"
  PathB -> MergePoint "Contributes data"
  
  // Single continuation
  MergePoint -> End "Combine and complete"
}

Characteristics:

• Parallel processing possible
• Multiple contributions to single result
• Synchronization point at convergence
• Common in gather-aggregate patterns

Looping Flow

A step repeats multiple times until a condition is met.

RetryingFlow = scenario "Payment with Retry Logic" {
  API -> PaymentGateway "Process payment"
  
  // First attempt fails
  PaymentGateway -> API "Payment failed: timeout"
  
  // Loop: retry up to 3 times
  API -> PaymentGateway "Retry payment" [attempt 2]
  PaymentGateway -> API "Payment failed: timeout"
  
  API -> PaymentGateway "Retry payment" [attempt 3]
  PaymentGateway -> API "Payment successful"
  
  // Exit loop
  API -> Database "Save order"
}

Characteristics:

• Repeated execution
• Exit condition required
• Common in retry logic and polling

Creating Flows in Sruja

Sruja gives you three keywords for flows, and they're essentially interchangeable. Use whichever makes semantic sense for what you're modeling.

Using scenario

Use scenario for behavioral flows, especially user journeys and BDD-style scenarios.

MyScenario = scenario "User Logs In" {
  User -> WebApp "Enters credentials"
  WebApp -> API "Submits login"
  API -> Database "Verifies user"
  Database -> API "User found"
  API -> WebApp "Returns session token"
  WebApp -> User "Shows dashboard"
}

Using story

Use story as an alias for scenario. It's the same thing, just a different keyword that some teams prefer for user stories.

MyStory = story "As a customer, I want to purchase products" {
  Customer -> WebApp "Browses products"
  Customer -> WebApp "Adds to cart"
  Customer -> WebApp "Checks out"
  WebApp -> API "Processes order"
  API -> Customer "Shows confirmation"
}

Using flow

Use flow for data-oriented flows, especially DFD-style data flows and event flows.

MyFlow = flow "Data Processing Pipeline" {
  Source -> Ingestion "Raw data"
  Ingestion -> Processing "Transformed data"
  Processing -> Storage "Stored data"
  Storage -> Analytics "Query results"
}

When to Use Flows (And When Not To)

Flows are powerful, but they're not always the right tool. Here's how I decide.

Use Flows When

• Sequence matters — You need to show the order in which things happen
• Modeling data lineage — You need to track where data comes from and goes
• Documenting user journeys — You need to understand the user experience
• Understanding process steps — You need to see the complete workflow
• Identifying bottlenecks — You need to find where things slow down
• Modeling error paths — You need to show what happens when things fail

Don't Use Flows When

• Showing general connections — Static relationships are better for showing overall architecture
• High-level overview — Flows have too much detail for executive diagrams
• Simple systems — If everything connects to everything, a flow doesn't add clarity
• Static structure — If you're showing what components exist, not what they do, use static relationships

Pitfalls to Avoid (I've Made All of These)

Let me share some mistakes I've made and seen others make. Hopefully, you can avoid them.

Mistake 1: Too Much Detail

// Bad: Way too detailed
LoginFlow = scenario "User Login (Too Detailed)" {
  User -> UI "Clicks login button"
  UI -> API "HTTP POST /login"
  API -> Database "SELECT * FROM users WHERE email = ?"
  Database -> API "Returns user record"
  API -> AuthService "Verifies password hash"
  AuthService -> API "Password matches"
  API -> TokenService "Generates JWT token"
  TokenService -> API "Returns token"
  API -> UI "JSON response with token"
  UI -> User "Shows dashboard"
}

This is ridiculous. We're showing database queries, HTTP methods, password hashing. This is implementation detail, not architecture. Nobody reading a diagram needs this level of detail.

Better approach: Group related steps together.

// Good: Right level of detail
LoginFlow = scenario "User Login" {
  User -> UI "Submits credentials"
  UI -> API "Authenticates user"
  API -> Database "Verifies credentials"
  Database -> API "User found"
  API -> TokenService "Creates session"
  API -> UI "Returns token"
  UI -> User "Shows dashboard"
}

Mistake 2: Too Abstract

// Bad: Not useful
ProcessFlow = scenario "Data Processing (Too Abstract)" {
  Start -> End "Data gets processed"
}

This tells you nothing. What kind of data? How is it processed? What happens in between? Useless.

Better approach: Add meaningful intermediate steps that explain what's actually happening.

// Good: Meaningful steps
ProcessFlow = scenario "Order Processing" {
  Order -> API "Submits order"
  API -> Payment "Processes payment"
  Payment -> Database "Saves order"
  Database -> Email "Sends confirmation"
}

Mistake 3: Mixing Flows with Static Relationships

// Bad: Confusing mix
Customer -> Shop.WebApp "Uses"  // Static relationship

CheckoutFlow = scenario "Checkout" {
  Customer -> Shop.WebApp "Submits order"  // Flow
  Shop.WebApp -> Shop.API "Sends data"
}

This is confusing. You have both a static relationship and a flow between the same elements. Readers won't know which to look at or what the difference is.

Better approach: Keep flows and static relationships separate. Use flows for sequences, static relationships for overall structure.

// Static architecture view
view architecture {
  title "System Architecture"
  include *
}

// Flow view
view checkout_flow {
  title "Checkout Sequence"
  CheckoutFlow = scenario "Checkout" {
    Customer -> Shop.WebApp "Submits order"
    Shop.WebApp -> Shop.API "Sends data"
  }
}

Mistake 4: One Path Assumes Success

// Bad: Only shows happy path
OrderFlow = scenario "Order Processing" {
  Customer -> Shop.API "Submits order"
  Shop.API -> PaymentGateway "Charges payment"
  PaymentGateway -> Shop.API "Success"
  Shop.API -> Database "Saves order"
}

This only works if everything goes perfectly. But what happens if payment fails? What if the database is down? What if the API times out?

Better approach: Model both success and failure paths.

// Good: Shows both paths
OrderFlow = scenario "Order Processing with Errors" {
  Customer -> Shop.API "Submits order"
  Shop.API -> PaymentGateway "Charges payment"
  
  // Success path
  PaymentGateway -> Shop.API "Payment successful"
  Shop.API -> Database "Saves order"
  Shop.API -> Email "Sends confirmation"
  
  // Failure path
  PaymentGateway -> Shop.API "Payment declined"
  Shop.API -> Shop.WebApp "Returns error"
  Shop.WebApp -> Customer "Shows error message"
}

What to Remember

Flows reveal what static relationships cannot. They show sequence, transformation, bottlenecks, and error paths. When you create flows:

• Show the sequence — Not just what's connected, but in what order
• Model both paths — Success and failure, not just happy paths
• Use the right type — Data flow for lineage, user journey for experience, control flow for logic
• Right level of detail — Not too deep (implementation), not too shallow (useless)
• Label meaningfully — Describe what's actually happening, not generic actions
• Separate from static — Flows complement, don't replace, static architecture

If you take away one thing, let it be this: flows tell the story of how things move through your system over time. Static relationships show the stage. Flows show the performance.

Check Your Understanding

Let's see if you've got this. Here are a couple of questions to test your understanding.

Question 1

You're documenting an order processing system. Which type of flow is most appropriate for modeling the complete customer experience from browsing products to receiving an order confirmation?

"A customer browses products, adds items to cart, proceeds to checkout, enters payment details, and places the order. If payment succeeds, they see a confirmation page and receive a confirmation email. If payment fails, they see an error message."

A) Data Flow B) User Journey / Scenario C) Control Flow D) Event Flow

Question 2

You're creating a flow to model how order data moves through your system from creation to analytics. The data originates from the customer, gets stored in the transactional database, gets extracted daily by an ETL job, gets transformed and aggregated, and ends up in the data warehouse for reporting. Which flow type is most appropriate?

A) User Journey / Scenario B) Control Flow C) Data Flow D) Event Flow

What's Next?

Now you understand what flows are and why they matter. You know the different types of flows (data, user journey, control, event) and when to use each one.

But we've only talked about what flows are. We haven't talked about how to create specific types of flows in practice.

In the next lesson, you'll learn about Data Flow Diagrams—how to model DFD-style data flows that show lineage, transformations, and analytics pipelines. You'll discover how to document where data comes from, how it changes, and where it ultimately ends up.

See you there!

Following the Trail: Data Flow Diagrams

Think of an oil pipeline. Crude oil goes in one end, flows through refineries where it's heated, distilled, and chemically treated, and comes out the other end as gasoline, diesel, or jet fuel. At each stage, the oil transforms into something more valuable.

Data flows work the same way. Raw data enters your system, flows through transformations where it's validated, normalized, enriched, and aggregated, and comes out as insights, reports, or visualizations.

In this lesson, you'll learn to create DFD-style data flows in Sruja. You'll discover how to track data lineage, document transformations, and model the pipelines that power your analytics and reporting.

Let's start by understanding what data flows are and why they matter.

Learning Goals

By the end of this lesson, you'll be able to:

• Create DFD-style data flows in Sruja
• Model data lineage from source to destination
• Document data transformations and how data changes shape
• Design ETL and analytics pipelines
• Track where data comes from and where it ultimately goes

What Are Data Flow Diagrams, Really?

Data Flow Diagrams (DFDs) show how data moves through your system—where it originates, how it's stored, how it transforms, and where it ends up.

Think of it like tracing a river's path:

• Source: Where the river starts (a spring, a mountain lake)
• Flow: The river's journey through valleys and cities
• Transformations: Tributaries joining, diversions splitting, dams changing flow
• Destination: Where the river ends (ocean, another river)

In data terms:

• Source: Where data originates (user input, database, API, file)
• Flow: The path data takes through your system
• Transformations: Validation, normalization, enrichment, aggregation
• Destination: Where data ultimately goes (warehouse, dashboard, report)

Why Data Flows Matter: The Real Benefits

I've built countless data systems over the years, and data flows are always the first thing I create. Here's why.

1. Data Lineage: Where Did This Come From?

Data flows tell you the complete history of data—where it started and every transformation it went through.

CustomerAnalyticsFlow = flow "Customer Data Lineage" {
  // Source: Where data starts
  Customer -> CRMSystem "Creates customer profile"
  
  // Transformation 1: Data extraction
  CRMSystem -> ETLService "Extracts customer records"
  
  // Transformation 2: Data normalization
  ETLService -> NormalizedData "Cleans and standardizes formats"
  
  // Transformation 3: Data enrichment
  NormalizedData -> EnrichmentService "Adds behavioral data from clickstream"
  
  // Transformation 4: Aggregation
  EnrichmentService -> AggregatedData "Creates daily customer segments"
  
  // Destination: Where data ends up
  AggregatedData -> DataWarehouse "Stores for reporting"
  DataWarehouse -> BusinessDashboard "Displays customer segments"
}

This flow tells you the complete story: customer data originates in CRM, gets extracted by ETL, normalized (cleaned up), enriched with behavioral data, aggregated into segments, stored in the warehouse, and ultimately shows up on a business dashboard.

Without this flow, would you know customer data comes from the CRM? Would you know it gets enriched with clickstream data? Would you know it's aggregated daily? Probably not.

I once worked on a project where nobody knew where analytics data came from. We spent weeks tracking down data lineage every time we found an issue. We added data flows, and suddenly everyone knew the complete path.

2. Process Understanding: What Actually Happens?

Data flows reveal the processing steps your data goes through—the "how" not just the "what."

ETLPipelineFlow = flow "ETL Pipeline Steps" {
  // Step 1: Extraction
  SourceDatabase -> IngestionService "Pulls raw transactions"
  
  // Step 2: Validation
  IngestionService -> ValidationService "Validates schema and data types"
  
  // Step 3: Transformation
  ValidationService -> TransformationService "Normalizes dates, currencies, formats"
  
  // Step 4: Loading
  TransformationService -> DataWarehouse "Loads transformed data"
}

This shows you the complete ETL process: extract, validate, transform, load. You can see exactly what each service does and in what order.

When something breaks—a data quality issue, a failed load, a malformed record—you know exactly where to look. Is it in ingestion? In validation? In transformation? The flow tells you.

3. Transformation Documentation: How Does Data Change?

Data flows document how data transforms at each step—what shape it takes, what format it's in.

TransformationFlow = flow "Data Transformations" {
  RawSource -> ETLService "Raw CSV file"
  
  // Transformation 1: Validation
  ETLService -> ValidatedData "Validated (removed invalid records)"
  
  // Transformation 2: Normalization
  ValidatedData -> NormalizedData "Normalized (standardized formats)"
  
  // Transformation 3: Enrichment
  NormalizedData -> EnrichedData "Enriched (added location data)"
  
  // Transformation 4: Aggregation
  EnrichedData -> FinalData "Aggregated (daily metrics)"
}

Each arrow shows a transformation:

• Raw CSV → Validated (invalid records removed)
• Validated → Normalized (formats standardized)
• Normalized → Enriched (location data added)
• Enriched → Aggregated (metrics computed)

This documentation is invaluable. When someone asks, "What happened to this data?" you can point to the flow and show them each transformation step.

I once inherited a system where nobody documented data transformations. We found mysterious records in the warehouse—dates in the wrong format, currencies mixed up, values that made no sense. We spent months reverse-engineering what transformations were happening. Document it upfront.

4. Bottleneck Identification: Where Will Things Slow Down?

Data flows make bottlenecks obvious—where processing might slow down, where queues might form, where latency will be worst.

AnalyticsFlow = flow "Analytics Pipeline" {
  UserActions -> TrackingService "Captures events" [fast]
  TrackingService -> EventStream "Publishes events" [fast]
  EventStream -> BatchProcessor "Consumes and processes" [slow, batch job]
  BatchProcessor -> DataWarehouse "Loads aggregated data" [medium]
  DataWarehouse -> Dashboard "Queries for display" [fast]
}

Look at the labels: fast, fast, slow, medium, fast. The batch processor is marked as slow because it's a scheduled job that runs once daily. This tells you immediately: if you're looking for real-time analytics, you'll be disappointed. The bottleneck is the batch processor.

When users complain about stale data ("why does the dashboard show yesterday's numbers?"), you know exactly why. The flow tells you.

Creating Data Flows in Sruja

Sruja gives you the flow keyword for creating DFD-style data flows. It's designed specifically for data-oriented flows.

Using flow for Data Pipelines

OrderDataFlow = flow "Order Data Processing" {
  Customer -> WebApp "Order form submission"
  WebApp -> API "Order JSON payload"
  API -> Database "Persist order record"
  Database -> AnalyticsExtractor "Extract order events"
  AnalyticsExtractor -> EventStream "Publish to analytics"
  EventStream -> DataWarehouse "Aggregate and store"
  DataWarehouse -> ReportingTool "Query for reports"
}

Using Metadata for Transformations

You can add metadata to document what each step does:

ETLService = container "ETL Service" {
  metadata {
    transformations [
      "Validate schema and data types",
      "Normalize dates to ISO 8601",
      "Standardize currency codes to ISO 4217",
      "Remove invalid or corrupt records"
    ]
    output_format "JSON"
    output_schema "v2.1"
    batch_window "Daily at 2AM UTC"
  }
}

This metadata tells anyone reading the flow:

• What transformations happen
• What output format to expect
• What schema version
• When the batch runs

Common Data Flow Patterns

After building data systems for years, I've noticed patterns that repeat constantly. Let me show you the ones I see most often.

Pattern 1: ETL Pipeline

Extract, Transform, Load—the classic pattern for moving data from operational systems to analytics.

ETLPipelineFlow = flow "Classic ETL Pipeline" {
  // Extract: Pull from source systems
  TransactionDB -> DataCollector "Extracts daily transactions"
  CustomerDB -> DataCollector "Extracts customer profiles"
  
  // Transform: Clean and normalize
  DataCollector -> ValidationService "Validates schemas"
  ValidationService -> CleaningService "Removes duplicates and errors"
  CleaningService -> TransformationService "Normalizes formats"
  
  // Load: Push to warehouse
  TransformationService -> DataWarehouse "Loads transformed data"
  DataWarehouse -> ReportingEngine "Available for queries"
}

Characteristics:

• Scheduled batch processing (daily, hourly)
• Source systems are OLTP (transactional)
• Destination is OLAP (analytics)
• Focus on data quality and consistency

Use when: Building traditional data warehouses, moving from transactional systems to analytics.

Pattern 2: Event Sourcing

Every change to data is captured as an event, and different services project events into read models.

EventSourcingFlow = flow "Event Sourcing Pattern" {
  // Events captured
  OrderAPI -> EventStore "Persist OrderCreated event"
  OrderAPI -> EventStore "Persist OrderPaid event"
  OrderAPI -> EventStore "Persist OrderShipped event"
  
  // Multiple projections
  EventStore -> OrderReadModel "Project to order summary view"
  EventStore -> CustomerReadModel "Project to customer order history view"
  EventStore -> AnalyticsReadModel "Project to order metrics view"
  
  // Read models queried
  OrderReadModel -> OrderService "Fetch order details"
  CustomerReadModel -> CustomerService "Fetch customer orders"
  AnalyticsReadModel -> AnalyticsService "Fetch order metrics"
}

Characteristics:

• Events are immutable (never change)
• Multiple read models for different use cases
• Rebuildable (can replay events)
• Eventually consistent

Use when: Building systems where audit trails matter, where you need multiple views of same data, where rebuildability is important.

Pattern 3: Real-Time Analytics Pipeline

Events flow through a real-time processing pipeline for immediate insights.

RealTimeAnalyticsFlow = flow "Real-Time Analytics Pipeline" {
  // Events captured
  UserActions -> EventCollector "Captures clickstream events"
  EventCollector -> KafkaStream "Publishes to Kafka"
  
  // Real-time processing
  KafkaStream -> StreamProcessor "Processes events in real-time"
  StreamProcessor -> RedisCache "Updates user session data"
  StreamProcessor -> Elasticsearch "Indexes events for search"
  
  // Real-time consumption
  RedisCache -> WebApp "Serves session data"
  Elasticsearch -> Dashboard "Shows real-time user activity"
}

Characteristics:

• Real-time (seconds to minutes latency)
• Stream processing (Kafka, Kinesis, Pulsar)
• Eventually consistent (some delay acceptable)
• Focus on speed and availability

Use when: Building real-time dashboards, fraud detection, personalized recommendations, live monitoring.

Pattern 4: Lambda Architecture

Batch processing for comprehensive analytics plus real-time for speed.

LambdaArchitectureFlow = flow "Lambda Architecture" {
  // Speed layer: Real-time
  Events -> StreamProcessing "Real-time processing"
  StreamProcessing -> SpeedLayer "Serves fast views"
  
  // Batch layer: Comprehensive
  Events -> BatchProcessing "Comprehensive processing"
  BatchProcessing -> BatchLayer "Serves accurate views"
  
  // Serving layer: Merges both
  SpeedLayer -> QueryService "Provides fast results"
  BatchLayer -> QueryService "Provides accurate results"
  QueryService -> API "Serves merged views"
}

Characteristics:

• Two paths: fast (speed layer) and accurate (batch layer)
• Speed layer provides quick but possibly incomplete results
• Batch layer provides comprehensive but delayed results
• Query service merges both for best of both worlds

Use when: You need both real-time responsiveness and comprehensive accuracy.

Documenting Data Transformations

One of the most important things you can do in data flows is document transformations clearly.

Using Relationship Labels

TransformFlow = flow "Data Transformations" {
  RawSource -> ETLService "Raw CSV data"
  ETLService -> ValidatedData "Validated (removed invalids)"
  ValidatedData -> NormalizedData "Normalized (standardized)"
  NormalizedData -> EnrichedData "Enriched (added location)"
  EnrichedData -> FinalData "Aggregated (daily metrics)"
}

Each label describes what transformation happened at that step.

Adding Metadata

ETLService = container "ETL Service" {
  metadata {
    transformations [
      "Remove duplicate records",
      "Normalize phone numbers to E.164 format",
      "Standardize dates to ISO 8601 (UTC)",
      "Geocode addresses to lat/long"
    ]
    input_format "CSV"
    output_format "JSON"
    output_schema "v2.1"
  }
}

This metadata provides complete documentation of what transformations happen.

Complete Data Flow Example

Let me show you a complete example that brings everything together.

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

// People
Customer = person "Customer"

// Systems
Shop = system "Shop" {
  WebApp = container "Web Application"
  API = container "API Service"
  Database = database "PostgreSQL"
}

Analytics = system "Analytics Platform" {
  Ingestion = container "Data Ingestion"
  Processing = container "Data Processing"
  Warehouse = database "Data Warehouse"
  Reporting = container "Reporting Engine"
}

Dashboard = system "Analytics Dashboard" {
  UI = container "Dashboard UI"
}

// Complete data flow: Order to analytics
OrderAnalyticsFlow = flow "Order Analytics Pipeline" {
  // Source: Customer creates order
  Customer -> Shop.WebApp "Submits order"
  Shop.WebApp -> Shop.API "Order data"
  Shop.API -> Shop.Database "Persist order"
  
  // Extraction: Pull orders for analytics
  Shop.Database -> Analytics.Ingestion "Extract order events"
  
  // Transformation: Validate and enrich
  Analytics.Ingestion -> Analytics.Processing "Validate and normalize"
  Analytics.Processing -> Analytics.Processing "Enrich with customer data"
  Analytics.Processing -> Analytics.Processing "Aggregate metrics"
  
  // Loading: Store in warehouse
  Analytics.Processing -> Analytics.Warehouse "Store aggregated data"
  
  // Consumption: Query and display
  Dashboard.UI -> Analytics.Reporting "Query metrics"
  Analytics.Reporting -> Analytics.Warehouse "Fetch data"
  Analytics.Reporting -> Dashboard.UI "Return results"
}

view index {
  include *
}

This flow shows the complete path from customer action to analytics dashboard. Anyone reading this diagram understands how data moves through the system.

What to Remember

Data flows tell the story of how data moves through your system—from origin to destination, including every transformation along the way. When you create data flows:

• Document lineage — Where data comes from and where it goes
• Show transformations — How data changes shape at each step
• Use metadata — Document what each service actually does
• Identify bottlenecks — Mark slow steps and understand their impact
• Choose right pattern — ETL, event sourcing, real-time, or lambda
• Track both paths — Success and failure paths

If you take away one thing, let it be this: data flows are your best documentation of how data actually moves through your system. When someone asks, "Where did this data come from?" or "What happened to this data?" your data flow has the answer.

Check Your Understanding

Let's see if you've got this. Here are a couple of questions to test your understanding.

Question 1

You're modeling a fitness tracking app's data flow. The app tracks user workouts, syncs them to a cloud API, where they're stored in a database. A daily ETL job extracts workouts, calculates daily metrics (calories burned, workout duration), and stores results in a data warehouse for business analytics. Which flow type is most appropriate?

"Users log workouts on their phones. Workout data syncs to the cloud API, gets stored in the main database. Every night at 2 AM, an ETL job pulls all workouts from the database, calculates aggregated metrics (total calories, total minutes, workout counts per user), and loads the results into a data warehouse. Business analysts query the warehouse for reports on user engagement and app usage."

A) User Journey / Scenario B) Control Flow C) Data Flow (DFD Style) D) Event Flow

Question 2

You're creating a data flow for an e-commerce platform. Which structure best documents the data transformations that happen in the ETL pipeline?

A)

ETLPipeline = flow "ETL Pipeline" {
  TransactionDB -> ETLService "Extract"
  ETLService -> DataWarehouse "Load"
}

B)

ETLPipeline = flow "ETL Pipeline" {
  TransactionDB -> ETLService "Extract transactions"
  ETLService -> ValidatedData "Validate and remove errors"
  ValidatedData -> NormalizedData "Normalize formats"
  NormalizedData -> EnrichedData "Add customer data"
  EnrichedData -> DataWarehouse "Load to warehouse"
}

C)

ETLPipeline = flow "ETL Pipeline" {
  TransactionDB -> DataWarehouse "Move data"
}

D)

ETLPipeline = flow "ETL Pipeline" {
  TransactionDB -> ETLService "Extract"
  ETLService -> ValidatedData "?"
  ValidatedData -> NormalizedData "?"
  NormalizedData -> EnrichedData "?"
  EnrichedData -> DataWarehouse "?"
}

What's Next?

Now you understand how to create data flow diagrams. You can model data lineage, document transformations, and design ETL and analytics pipelines.

But data flows are just one type of flow. There's another crucial type—user journeys (or behavioral flows)—which show how users interact with your system from their perspective.

In the next lesson, you'll learn about user journeys. You'll discover how to model BDD-style scenarios, document happy paths and error paths, and capture the complete user experience from start to finish.

See you there!

Walking in Their Shoes: User Journeys

Ever watched someone use a product you built? You notice things you never would—confusing buttons, unclear error messages, workflows that don't make sense. Why? Because you built it from your perspective, not theirs.

User journeys (or scenarios) are your way to model the complete user experience—from their perspective. They show what users do, how your system responds, and what happens when things go right (and wrong).

In this lesson, you'll learn to create user journeys that capture the complete user experience. You'll discover how to model happy paths and error paths, document edge cases, and create scenarios that serve as both requirements and test cases.

Let's start by understanding what user journeys actually are.

Learning Goals

By the end of this lesson, you'll be able to:

• Model user journeys and behavioral scenarios from user's perspective
• Use BDD-style scenarios to document requirements
• Model both happy paths and error paths
• Document edge cases and unusual scenarios
• Create scenarios that serve as test cases and documentation

What Are User Journeys, Really?

User journeys (also called scenarios or behavioral flows) show how a person interacts with your system to achieve a goal. Unlike data flows that show data moving through a system, user journeys show human behavior and system responses.

Think of it like a story: "As a customer, I want to buy a product so I can use it." The journey shows every step—what the customer does, what the system does, and what the customer experiences.

User journeys capture:

• User actions (what they click, type, select)
• System responses (what happens, what they see)
• Success paths (when everything works)
• Error paths (when things go wrong)
• Decision points (where different things happen based on conditions)

What makes them special:

• User's perspective (not system's)
• Behavioral (not just data)
• Complete experience (start to finish)
• Both happy and sad paths

Why User Journeys Matter

I've learned this the hard way. I once built a feature without modeling user journeys, and when we launched, users were completely confused.

They couldn't find the checkout button. When they did, error messages were cryptic. The "success" page didn't tell them what to do next. Support tickets flooded in. We had to rebuild the entire feature.

If I'd modeled user journeys upfront, we would have seen these issues immediately. The journey would have shown: "User clicks checkout → System shows error 'ERR_500' → User is confused."

User journeys matter because:

1. Requirements Clarity

User journeys turn vague requirements into concrete scenarios:

Vague requirement: "Users should be able to check out"

User journey makes it concrete:

CheckoutJourney = scenario "Customer Checkout" {
  Customer -> WebApp "Clicks checkout button"
  WebApp -> API "Validates cart"
  API -> Database "Checks inventory"
  Database -> API "Inventory available"
  API -> PaymentGateway "Processes payment"
  PaymentGateway -> API "Payment successful"
  API -> Database "Saves order"
  API -> EmailService "Sends confirmation"
  WebApp -> Customer "Shows order confirmation page"
}

Now everyone knows exactly what "checkout" means—every step, every system involved, every user action.

2. Test Case Generation

User journeys become test cases automatically:

HappyPathTest = scenario "Test: Successful Checkout" {
  // From the user journey
  Customer -> WebApp "Clicks checkout"
  WebApp -> API "Validates cart"
  // ... test each step
}

ErrorPathTest = scenario "Test: Checkout with Invalid Payment" {
  Customer -> WebApp "Clicks checkout"
  WebApp -> API "Validates cart"
  API -> PaymentGateway "Processes payment"
  PaymentGateway -> API "Payment declined: invalid card"
  API -> WebApp "Returns error: Invalid card"
  WebApp -> Customer "Shows error: Please check your card details"
}

I've worked on teams where we spent weeks writing test cases manually. With user journeys, we just turn scenarios into tests. Huge time saver.

3. User Experience Visibility

User journeys show the complete experience—not just what works, but how it feels:

RegistrationJourney = scenario "User Registration" {
  Customer -> WebApp "Opens registration form"
  Customer -> WebApp "Enters name and email"
  Customer -> WebApp "Enters password"
  Customer -> WebApp "Clicks 'Create Account'"
  WebApp -> API "Submits registration"
  API -> Database "Creates user account"
  API -> EmailService "Sends welcome email"
  WebApp -> Customer "Shows 'Account created!' message"
  WebApp -> Customer "Redirects to dashboard"
}

See how this shows the full experience? Form entry → submission → success message → welcome email → dashboard. Anyone reading this understands exactly what users experience.

4. Edge Case Discovery

When you model user journeys, you naturally think about edge cases:

RegistrationEdgeCases = scenario "Registration Edge Cases" {
  // Edge case 1: Duplicate email
  Customer -> WebApp "Registers with existing email"
  WebApp -> API "Submits registration"
  API -> Database "Checks email exists"
  Database -> API "Email already exists"
  API -> WebApp "Returns error: Email already registered"
  WebApp -> Customer "Shows error: Email already in use"

  // Edge case 2: Weak password
  Customer -> WebApp "Registers with weak password"
  WebApp -> API "Submits registration"
  API -> ValidationService "Validates password strength"
  ValidationService -> API "Password too weak"
  API -> WebApp "Returns error: Password must be at least 8 characters"
  WebApp -> Customer "Shows error: Password too weak"
}

I once launched a feature without modeling edge cases. Users started using weird inputs, emojis in names, passwords with special characters, and the system broke in creative ways. Model edge cases upfront.

Creating User Journeys in Sruja

Sruja gives you two keywords for user journeys, and they're interchangeable:

Using scenario

Use scenario for behavioral flows—it's the most common and descriptive choice:

CheckoutScenario = scenario "Customer Checkout Experience" {
  Customer -> Shop.WebApp "Clicks checkout button"
  Shop.WebApp -> Shop.API "Validates shopping cart"
  Shop.API -> PaymentGateway "Processes payment"
  Shop.WebApp -> Customer "Shows order confirmation"
}

Using story

Use story when you want to emphasize the narrative or story aspect:

CheckoutStory = story "As a customer, I want to checkout so I can purchase my items" {
  Customer -> Shop.WebApp "Clicks checkout button"
  Shop.WebApp -> Shop.API "Validates shopping cart"
  Shop.API -> PaymentGateway "Processes payment"
  Shop.WebApp -> Customer "Shows order confirmation"}
}

The story keyword is great for BDD (Behavior-Driven Development) style where you write scenarios in "Given-When-Then" format.

BDD (Behavior-Driven Development) Style

BDD is about writing requirements as behavior, not specifications. User journeys in Sruja map perfectly to BDD's "Given-When-Then" structure.

The Given-When-Then Pattern

// GIVEN: Customer has items in shopping cart
// WHEN: Customer clicks checkout and completes payment
// THEN: Order is created and confirmation is shown

CheckoutJourney = scenario "Customer Checkout (BDD Style)" {
  // GIVEN: Customer has items in cart
  Customer -> Shop.WebApp "Views shopping cart with 3 items"
  Shop.WebApp -> Shop.API "Fetches cart contents"
  Shop.API -> Shop.Database "Returns cart data"
  
  // WHEN: Customer completes checkout flow
  Customer -> Shop.WebApp "Clicks checkout button"
  Shop.WebApp -> Shop.API "Validates cart"
  Shop.API -> Shop.Database "Checks inventory"
  Shop.Database -> Shop.API "All items available"
  Shop.API -> PaymentGateway "Processes payment"
  PaymentGateway -> Shop.API "Payment successful"
  
  // THEN: Order is created and confirmation shown
  Shop.API -> Shop.Database "Creates order"
  Shop.API -> Shop.Database "Reserves inventory"
  Shop.API -> EmailService "Sends confirmation email"
  Shop.WebApp -> Customer "Shows order confirmation page with order #12345"
}

Why BDD works:

• It's in plain language anyone can understand
• It focuses on behavior, not implementation
• It serves as both requirements and tests
• It's unambiguous (unlike "system should work well")

I've worked with product managers who couldn't understand technical specs. But they understood BDD scenarios immediately. It became our common language.

User Journey Patterns

After modeling user journeys for years, I've found patterns that repeat constantly. Let me show you the ones I see most often.

Pattern 1: Happy Path

The ideal scenario where everything works perfectly:

HappyRegistration = scenario "User Registration (Happy Path)" {
  Customer -> WebApp "Opens registration form"
  Customer -> WebApp "Enters name, email, password"
  Customer -> WebApp "Clicks 'Create Account'"
  WebApp -> API "Submits registration"
  API -> Database "Creates user account"
  Database -> API "User created successfully"
  API -> EmailService "Sends welcome email"
  EmailService -> Customer "Receives welcome email"
  API -> WebApp "Returns success"
  WebApp -> Customer "Shows 'Account created! Welcome!' message"
  WebApp -> Customer "Redirects to dashboard"
}

Characteristics:

• No errors
• No branches
• Perfect flow from start to finish
• User achieves their goal

When to model:

• First—model the ideal scenario
• Before optimizing, understand what success looks like
• Before testing edge cases, have a working baseline

Pattern 2: Error Path

What happens when things go wrong:

ErrorRegistration = scenario "User Registration (Error Path: Duplicate Email)" {
  Customer -> WebApp "Opens registration form"
  Customer -> WebApp "Enters existing email: john@example.com"
  Customer -> WebApp "Enters name and password"
  Customer -> WebApp "Clicks 'Create Account'"
  WebApp -> API "Submits registration"
  API -> Database "Checks if email exists"
  Database -> API "Email already exists: john@example.com"
  API -> WebApp "Returns error: Email already registered"
  WebApp -> Customer "Shows error: 'Email already in use. Try logging in or use a different email.'"
}

Common error paths to model:

• Duplicate data (email, username)
• Invalid data (email format, weak password)
• Missing data (required fields empty)
• System errors (database down, API timeout)
• Business rule violations (age restriction, region blocking)

Characteristics:

• Error occurs at some step
• System returns meaningful error
• User sees helpful error message
• User can correct and retry

When to model:

• Always model critical error paths
• Focus on errors users actually encounter
• Ensure error messages are helpful, not cryptic

I once worked on a system where error messages were like "ERR_500_CHECKOUT_FAILED." Users had no idea what went wrong. We rewrote them to be helpful: "Payment failed. Please check your card details or try a different payment method." Support tickets dropped by 70%.

Pattern 3: Branching Path

Different things happen based on conditions:

BranchingApproval = scenario "Order Approval (Branching Based on Value)" {
  Manager -> WebApp "Submits order for approval"
  WebApp -> API "Processes approval request"
  API -> Database "Fetches order details"
  Database -> API "Returns order: value = $1500"
  
  // Branch 1: Auto-approve for low-value orders
  if value < 1000 {
    API -> Database "Updates order: auto-approved"
    API -> WebApp "Returns: Order auto-approved"
    WebApp -> Manager "Shows 'Order approved! Shipping soon.'"
  }
  
  // Branch 2: Manual review for high-value orders
  if value >= 1000 {
    API -> EmailService "Sends approval request to director"
    EmailService -> Director "Receives approval request"
    Director -> WebApp "Reviews order and approves"
    WebApp -> API "Submits approval decision"
    API -> Database "Updates order: manually approved"
    API -> WebApp "Returns: Order approved by director"
    WebApp -> Manager "Shows 'Order approved by director. Shipping soon.'"
  }
}

Characteristics:

• Decision point in the flow
• Multiple possible paths
• Different actions based on conditions
• Paths may converge at the end

When to model:

• Business logic has rules
• Different user types have different experiences
• System behavior changes based on context

Pattern 4: Retry Path

System tries multiple times before succeeding or failing:

RetryPayment = scenario "Payment with Automatic Retry" {
  Customer -> WebApp "Clicks 'Place Order'"
  WebApp -> API "Submits order for payment"
  
  // Attempt 1: Fails with timeout
  API -> PaymentGateway "Process payment"
  PaymentGateway -> API "Payment failed: timeout"
  API -> WebApp "Returns: Processing, please wait..."
  WebApp -> Customer "Shows spinner: 'Processing your payment...'"
  
  // Attempt 2: Fails with timeout
  API -> PaymentGateway "Retry payment (attempt 2)"
  PaymentGateway -> API "Payment failed: timeout"
  
  // Attempt 3: Succeeds
  API -> PaymentGateway "Retry payment (attempt 3)"
  PaymentGateway -> API "Payment successful!"
  
  // Continue with success
  API -> Database "Saves order"
  API -> EmailService "Sends confirmation"
  WebApp -> Customer "Shows order confirmation"
}

Characteristics:

• Same action repeated
• Eventually succeeds or fails permanently
• User sees "retrying" state
• Transparent about what's happening

When to model: