Sruja

Architecture-as-code for the AI SDLC process. Define architecture in .sruja files; validate, document, and keep it in sync with your workflow. We're a tool for the lifecycle—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 visual editing, steep learning curve
• One-way sync (Structurizr) – code → view only, no visual editing
• Stale diagrams – architecture drifts from reality, documentation gets outdated

Our Solution

Sruja gives you both visual editing and code-backed architecture:

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 (or use the visual designer)
2. Validate with built-in checks (cycles, orphans, unique IDs)
3. Export to JSON, Markdown, or 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, diagnostics, optional diagram preview
• Docs – This book (mdBook, Rust-based; no TypeScript/Node)

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

See Quick start to install the CLI 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

Install CLI

curl -fsSL https://raw.githubusercontent.com/sruja-ai/sruja/main/scripts/install.sh | bash

Or build from source (requires Rust):

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

Create a .sruja file

This is the minimal style (explicit kinds, no import). The full Getting started (full) uses import { * } from 'sruja.ai/stdlib' for less boilerplate — both work.

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 (search for "Sruja") or build from source in extension/.

Introduction

title: "Introduction" weight: 0

Introduction

Sruja is an open source architecture-as-code tool for the AI SDLC process.

New here? Do Quick start (about 5 min), then the Beginner path (2–3 hours). It helps teams define, validate, and evolve software architecture in code—so architecture stays in sync with design, review, CI, and docs. We are not a diagramming tool; diagrams are one output, not the product.

Why Sruja?

Most teams document architecture in static diagrams (Miro, LucidChart, Visio) or inconsistent Wiki pages. These suffer from:

1. Drift: The code changes, but the diagram doesn't.
2. Inconsistency: Every architect draws "boxes and arrows" differently.
3. No Validation: You can't "test" a PNG image for broken dependencies.

Sruja treats Architecture like Code:

• Version Control: Commit your architecture to Git.
• Validation: CI/CD checks for circular dependencies and rule violations.
• Consistency: Based on the C4 Model for clear, hierarchical abstractions. (See Glossary for definitions of key terms.)

Who is Sruja For?

Students & Learners

• Learn system design with production-ready examples from fintech, healthcare, and e-commerce
• Hands-on courses covering fundamentals to advanced patterns
• 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
• Want to learn? Explore Courses and Tutorials
• Need examples? Check out Real-World Examples
• Ready to build? Use the VS Code extension for diagram preview

Getting started (full)

title: "Getting Started" weight: 1 summary: "From zero to architecture in 5 minutes. Install Sruja and deploy your first diagram." difficulty: "beginner" estimatedTime: "5 minutes"

Your First Architecture

Welcome to the future of system design.

Sruja allows you to define your software architecture as code. No more dragging boxes around. No more outdated PNGs on a wiki. You write code, Sruja draws the maps.

1. Installation

Install the Sruja CLI to compile, validate, and export your diagrams.

Mac / Linux

curl -fsSL https://raw.githubusercontent.com/sruja-ai/sruja/main/scripts/install.sh | bash

From Source (Rust)

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

Verify installation:

sruja --version
# Should output something like: sruja version v0.2.0

2. Hello, World!

Let's model a simple web application. Create a file named hello.sruja.

This page uses stdlib import (same style as the rest of the book). The Quick start uses explicit kinds (person = kind "Person", etc.) with no import — both are valid; use whichever you prefer.

The Code

Copy and paste this into your file:

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

// 1. Define the System
webApp = system "My Cool Startup" {
    description "The next big thing."

    frontend = container "React App"
    api = container "Rust Service"
    db = database "PostgreSQL"

    // 2. Define Connections
    frontend -> api "Requests Data"
    api -> db "Reads/Writes"
}

// 3. Define Users
user = person "Early Adopter"

// 4. Connect User to System
user -> webApp.frontend "Visits Website"

view index {
    include *
}

Tip

Using stdlib imports: The import { * } from 'sruja.ai/stdlib' line provides all standard kinds (person, system, container, database, etc.) so you don't declare them manually. For the minimal style with explicit kinds, see Quick start.

3. Generate the Diagram

Run this command in your terminal:

sruja export mermaid hello.sruja > diagram.mmd

You have just created a Diagram-as-Code artifact! You can paste the content of diagram.mmd into Mermaid Live Editor to see it, or use the VS Code extension to preview it instantly.

What you'll get: A beautiful C4 diagram showing:

• The user (person) on the left
• Your system with containers (Web, API, DB) in the middle
• Relationships (arrows) showing how they connect

Tip

Want to see it visually?

• VS Code User? Install the Sruja VS Code Extension for real-time preview, autocomplete, and syntax highlighting.
• Preview in editor: Use the VS Code extension for syntax and diagram preview.

4. Understanding the Basics

Let's break down what just happened.

1. Import Standard Kinds: The import { * } from 'sruja.ai/stdlib' line gives you all standard element types (person, system, container, database, etc.) without needing to declare them manually.
2. Element Creation: You create elements using the = operator (e.g., webApp = system "My Cool Startup").
3. Nested Elements: Containers and components can be defined inside a system block { ... }, or referred to using dot notation (e.g., webApp.frontend).
4. Relationships: The -> operator defines how things connect. Relationships can be defined anywhere in the file.
5. Views: The view index { include * } block tells Sruja to generate a diagram showing all elements. Sruja automatically generates C4 diagrams for you.
6. Flat Syntax: Sruja uses a flat syntax where all declarations are top-level. There are no wrapper blocks required.

Note

Custom Kinds: If you need custom element types (like microservice or serverless), you can declare them manually: microservice = kind "Microservice". For most use cases, the standard kinds from stdlib are sufficient.

What Now?

You have the tools. Now get the skills.

• 🎓 Learn the Core: Take the System Design 101 course to move beyond "Hello World".
• 🏗 See Real Patterns: Copy production-ready code from Examples.
• 🛠 Master the CLI: Learn how to validate constraints in CLI Basics.

How Sruja works

title: "How Sruja Works" weight: 3

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!

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 markdown, sruja export dot, and more.

Examples

title: "Usage Examples" weight: 80 summary: "Production-ready architectures. Learn how to model Fintech, E-Commerce, and SaaS systems with Sruja."

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

title: "Beginner Path" weight: 2 summary: "A 7‑step plan to learn Sruja without overwhelm." difficulty: "beginner" estimatedTime: "~2–3 hours total"

Beginner Path: Learn Sruja Without Overwhelm

If you just did Quick start, you already have your first diagram — the 7 steps below build on that and take about 2–3 hours total. Each step has a clear outcome, takes 10–30 minutes, and gives immediate feedback.

Tip

Track your progress: Check off each step as you complete it. This path takes approximately 2–3 hours total.

Step 1: Getting Started ⏱️ 20–30 min

• Do: Quick start (minimal style). Optional: Getting started (full) (stdlib import).
• Outcome: CLI installed, first model created
• What you'll do: Install Sruja CLI and create your first architecture file
• Success check: You can run sruja lint and sruja export mermaid on your file and get a diagram

Step 2: CLI Basics ⏱️ 20 min

• Tutorial: CLI basics
• Outcome: Run lint, fmt, tree, export commands confidently
• What you'll do: Learn essential CLI commands for working with Sruja files
• Success check: You can validate, format, and export your architecture

Step 3: DSL Basics ⏱️ 25–30 min

• Tutorial: DSL basics
• Quiz: Optional; add exercises in the book if desired
• Outcome: Understand systems, containers, components, relations
• What you'll do: Learn the core DSL syntax and concepts
• Success check: You can read and write basic Sruja DSL code

Step 4: Validation & Linting ⏱️ 15–20 min

• Tutorial: Validation & linting
• Challenge: Missing relations
• Outcome: Fix common modeling errors
• What you'll do: Learn how Sruja validates your architecture and catches errors
• Success check: You can identify and fix validation errors

Step 5: Export Diagrams ⏱️ 15–20 min

• Tutorial: Export diagrams
• Outcome: Generate diagrams (D2, SVG) and Markdown
• What you'll do: Learn to export your architecture in different formats
• Success check: You can export diagrams in multiple formats

Step 6: Practice Micro‑Challenges ⏱️ 20–30 min

• Challenge: Add component
• Challenge: Fix relations
• Challenge: Queue worker
• Outcome: Build confidence with small tasks
• What you'll do: Practice with real-world scenarios
• Success check: You can complete challenges without looking at solutions

Step 7: Systems Thinking ⏱️ 20 min

• Tutorial: Systems thinking
• Outcome: Think in flows, dependencies, and constraints
• What you'll do: Learn to model complex systems and relationships
• Success check: You can model a multi-system architecture

Tips to Avoid Overwhelm

• Small steps: limit sessions to 20–30 minutes
• Visible outcomes: run a command or export a diagram every step
• One concept at a time: model, then lint, then export
• Use checklists: follow the repo docs style when writing
• Ask for help: Discord and Discussions links in README

What’s Next

• Course: System Design 101 – Module 1
• Advanced tutorials: Deployment modeling

Note: Sruja is free and open source (Apache 2.0 licensed). Join the community on Discord or GitHub Discussions for help and to contribute.

Concepts

title: "Overview" weight: 12 summary: "Summarize systems with high‑level context for readers and diagrams."

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

title: "Architecture" weight: 10 summary: "The architecture block is the root element of any Sruja model."

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.

C4 model

title: "The C4 Model" weight: 1 summary: "Understand the core concepts behind Sruja's architecture modeling."

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

title: "System" weight: 11 summary: "A System represents a software system, the highest level of abstraction in the C4 model."

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

title: "Container" weight: 14 summary: "A Container represents an application or a data store."

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

title: "Component" weight: 13 summary: "A Component is a grouping of related functionality encapsulated behind a well-defined interface."

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

title: "Person" weight: 15 summary: "A Person represents a human user of your software system."

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

title: "Relations" weight: 20 summary: "Relations describe how elements interact with each other."

Relations

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

Syntax

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:

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

title: "Views" weight: 36 summary: "Create focused visualizations using includes, excludes, and per‑view styles."

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

title: "Validation" weight: 35 summary: "Automatic checks: IDs, references, cycles, layering, externals."

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

title: "Deployment" weight: 33 summary: "The Deployment view allows you to map your software containers to infrastructure."

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

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

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

containerInstance ContainerID {
    instanceId 1 // Optional
}

Example

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

Requirements

title: "Requirements" weight: 31 summary: "Model functional and non‑functional requirements directly in Sruja DSL."

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

title: "Scenario" weight: 22 summary: "Describe behavioral flows as steps between elements."

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

ADR

title: "Architecture Decision Records (ADR)" weight: 51 summary: "Capture architecture decisions directly in your model."

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

title: "Policy" weight: 50 summary: "Define architectural rules and constraints that must be followed."

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

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

Reference: syntax

title: "Syntax Reference" weight: 51 summary: "Core constructs and fields for Sruja DSL."

Syntax Reference

Elements

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


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

Relations

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

deployment Prod {
  node Cloud {
    node Region {
      node Service {
        containerInstance Web
      }
    }
  }
}

Reference: patterns

title: "Architecture Patterns" weight: 53 summary: "Reusable patterns: request/response, event-driven, saga, CQRS."

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

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

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 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 examples/pattern_agentic_ai.sruja for a complete agent graph.

Cheatsheet

title: "Sruja Cheatsheet" summary: "Quick syntax and common patterns for fast modeling."

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

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.

Adoption guide

title: "Adoption Guide" weight: 21 summary: "Complete guide to evaluating and adopting Sruja for your organization."

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. Try Sruja Designer online
3. Install CLI: curl -fsSL https://raw.githubusercontent.com/sruja-ai/sruja/main/scripts/install.sh | bash
4. Model a simple existing system

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, Discord, etc.)

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

title: "Adoption Playbook" weight: 22 summary: "Practical steps to roll out Sruja across teams and CI."

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@v4
      - 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 – from Git (recommended for now):

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

Option B – install script (if available in repo):

curl -fsSL https://raw.githubusercontent.com/sruja-ai/sruja/main/scripts/install.sh | bash

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 examples).

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@v4

      - 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/ in the Sruja repo

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:

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

From Data Modeling to Sruja:

// 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:

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)

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)

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)

// 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)

// 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)

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

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

// DFD-style — use scenario
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

// 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

title: "Glossary" weight: 100 summary: "Definitions of key terms and concepts used in Sruja."

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:

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:

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

Style guide

title: "Documentation Style Guide" weight: 100 summary: "Standards for tutorials, how‑tos, reference, and explanation." tags: ["docs", "style", "quality"]

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

Community

title: "Community" weight: 90 summary: "Join the Sruja community, contribute, and help shape the future of architecture-as-code."

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

💬 Discord

Join our Discord server for real-time chat, quick questions, and community discussions:

Join Discord

Discord is great for:

• Getting quick help with questions
• Discussing ideas and use cases
• Sharing your Sruja projects
• Connecting with other community members

💬 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 Discord or 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 the examples/ directory
• 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

• Discord: Real-time chat
• 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 Discord 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 the examples/ directory
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 Discord or 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: What is Systems Thinking? - Introduction to systems thinking principles
• Lesson 2: The Five Core Concepts - Overview of the key concepts you'll learn
• Lesson 3: Why Systems Thinking Matters - Benefits and practical applications

Prerequisites

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

Time Investment

Approximately 1-1.5 hours to complete all lessons.

What's Next

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

Lesson 1: What is Systems Thinking?

Learning Goals

• Understand what systems thinking is
• Recognize systems in everyday life and software
• See the connection between systems thinking and software 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 individual parts in isolation, systems thinking focuses on the relationships, patterns, and emergent behaviors that arise when components work together.

A Simple Example

Consider a coffee shop:

Isolated view (reductionist):

• Coffee machine
• Barista
• Cups
• Beans
• Customers

Systems thinking view:

• Customer orders coffee → Barista uses machine → Machine produces coffee → Customer receives coffee → Customer might return
• The coffee machine needs beans (supply chain)
• The barista needs training (human systems)
• The shop needs location (infrastructure)
• Customer satisfaction affects future visits (feedback loop)

Systems in Software Architecture

Every software system is a system of systems:

User Interface
    ↓
Application Logic
    ↓
Data Layer
    ↓
Infrastructure

But there's more:

• Dependencies: External APIs, libraries, services
• People: Users, developers, stakeholders
• Processes: Development, deployment, operations
• Data: Information flows, state, transactions
• Feedback: Monitoring, logs, user behavior

The Iceberg Model

Systems thinking uses the "iceberg model" to understand systems:

Events (what you see)
    ↓
Patterns (what's happening over time)
    ↓
Structures (what's causing the patterns)
    ↓
Mental Models (what's shaping the structures)

In software architecture:

• Events: A user reports a bug
• Patterns: Similar bugs occur repeatedly
• Structures: Tightly coupled components, lack of testing
• Mental Models: "We need to ship fast, quality can wait"

Why Systems Thinking in Architecture?

Traditional architecture often focuses on:

• Components and their functions
• Technology choices
• Implementation details

Systems thinking adds:

• Relationships and interactions
• Emergent behaviors
• Feedback loops
• Context and boundaries
• Flow of information

This leads to architectures that:

• Adapt to change more easily
• Handle edge cases better
• Scale more naturally
• Align with business goals

Sruja and Systems Thinking

Sruja is built on systems thinking principles:

• Elements as parts: person, system, container, component
• Relationships as interactions: clear, labeled connections
• Scenarios as flows: data and information movement
• Views as perspectives: different angles on the same system
• Validation as feedback: catch problems early

Key Takeaways

1. Systems thinking looks at the whole, not just parts
2. Relationships matter as much as components
3. Patterns and emergent behaviors are key insights
4. Context is critical - nothing exists in isolation
5. Sruja supports systems thinking through its language and features

Exercise

Think of a system you work with daily (could be a codebase, a service, or a team). Identify:

• The main components (parts)
• How they interact (relationships)
• Who depends on it (context)
• Any feedback loops (how information flows back)

Next Lesson

In Lesson 2, we'll explore the five core systems thinking concepts you'll master in this course.

Lesson 2: The Five Core Concepts

Learning Goals

• Learn the five core systems thinking concepts
• Understand how they apply to software architecture
• See how Sruja implements each concept

The Five Core Concepts

In this course, you'll master five fundamental systems thinking concepts:

┌─────────────────────────────────────────────┐
│           SYSTEMS THINKING 101              │
├─────────────────────────────────────────────┤
│  1. Parts & Relationships                   │
│  2. Boundaries                              │
│  3. Flows                                   │
│  4. Feedback Loops                          │
│  5. Context                                 │
└─────────────────────────────────────────────┘

1. Parts and Relationships

Definition: What the system contains and how those pieces connect.

In Sruja

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

Customer = person "End User"
Shop = system "Shop" {
  WebApp = container "Web Application"
  API = container "API Service"
  DB = database "Database"
}

// Relationships = how parts connect
Customer -> Shop.WebApp "Uses"
Shop.WebApp -> Shop.API "Calls"
Shop.API -> Shop.DB "Reads"

Why It Matters

• Structure: Defines what exists in your system
• Interactions: Shows how components communicate
• Coupling: Reveals dependencies between parts

2. Boundaries

Definition: What's inside the system vs. what's outside (the environment).

In Sruja

// Inside: Your system
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API"
}

// Outside: External systems
PaymentGateway = system "Payment Service" {
  metadata { tags ["external"] }
}

// Crossing the boundary
Shop.API -> PaymentGateway "Processes payments"

Why It Matters

• Scope: What you're responsible for vs. dependencies
• Integration: How you connect with external systems
• Security: What needs to be protected
• Testing: What's in scope for your tests

3. Flows

Definition: How information, data, and actions move through the system.

In Sruja (Data Flow)

OrderFlow = scenario "Order Processing" {
  Customer -> Shop.WebApp "Submits order"
  Shop.WebApp -> Shop.API "Sends order data"
  Shop.API -> Shop.DB "Saves order"
  Shop.API -> PaymentGateway "Charges payment"
  Shop.API -> Shop.WebApp "Returns result"
  Shop.WebApp -> Customer "Shows confirmation"
}

Why It Matters

• Data lineage: Where does information come from and go?
• Process understanding: What's the sequence of actions?
• Bottlenecks: Where do things slow down?
• Error paths: What happens when something fails?

4. Feedback Loops

Definition: How actions create reactions that affect future actions.

In Sruja (Cycles)

// User feedback loop
User -> App.WebApp "Submits form"
App.WebApp -> App.API "Validates"
App.API -> App.WebApp "Returns result"
App.WebApp -> User "Shows feedback"

// System feedback loop
App.API -> App.DB "Updates inventory"
App.DB -> App.API "Notifies low stock"
App.API -> Admin "Sends alert"
Admin -> App.API "Adjusts inventory"

Why It Matters

• Reactive behavior: How systems respond to changes
• Stability: Does the system self-correct or spiral out of control?
• Adaptation: How the system learns and evolves
• Monitoring: What metrics indicate system health?

5. Context

Definition: The environment the system operates in - stakeholders, dependencies, constraints.

In Sruja

// Your system
Shop = system "Shop"

// Context: Stakeholders
Customer = person "End User"
Admin = person "Administrator"
Support = person "Customer Support"

// Context: Dependencies
PaymentGateway = system "Payment Service"
EmailService = system "Email Service"
Analytics = system "Analytics"

// Context relationships
Customer -> Shop "Uses"
Shop -> PaymentGateway "Depends on"
Shop -> EmailService "Sends notifications"
Admin -> Shop "Manages"

Why It Matters

• Stakeholders: Who cares about this system?
• Dependencies: What external systems do you rely on?
• Constraints: What limits your design choices?
• Success criteria: What does "good" look like?

How They Work Together

A complete systems thinking view combines all five:

┌──────────────────────────────────────────┐
│              CONTEXT                     │
│  Stakeholders: Users, Admins, Support    │
│  Dependencies: External APIs, Services   │
│                                          │
│    ┌────────── BOUNDARY ──────────┐     │
│    │                               │     │
│    │   PARTS ↔ RELATIONSHIPS       │     │
│    │   [User] → [App] → [DB]       │     │
│    │         ↑       ↓             │     │
│    │         └── FEEDBACK ─────┘  │     │
│    │                               │     │
│    │   FLOWS: Order, Payment      │     │
│    └───────────────────────────────┘     │
└──────────────────────────────────────────┘

Sruja Mapping Summary

Key Takeaways

1. Five concepts form the foundation: Parts/relationships, boundaries, flows, feedback loops, context
2. They interconnect: None exists in isolation
3. Sruja supports all five: Built into the language
4. Use them together: Complete architecture requires all perspectives
5. Practice makes perfect: You'll work with each in depth

Exercise

Pick a system you know well. For each concept, write one observation:

• Parts/Relationships: Name 3 components and how they connect
• Boundaries: What's inside vs. outside the system?
• Flows: What's a common data path through the system?
• Feedback Loops: Any automatic responses to user actions?
• Context: Who are the main stakeholders?

Next Lesson

In Lesson 3, we'll explore the practical benefits of systems thinking for software architecture.

Lesson 3: Why Systems Thinking Matters

Learning Goals

• Understand the benefits of systems thinking for software architecture
• Recognize problems that systems thinking prevents
• Apply systems thinking to real architecture challenges

The Architecture Problem

Traditional architecture approaches often lead to:

• Siloed thinking: Components designed in isolation
• Hidden dependencies: Unforeseen coupling
• Brittle systems: Break when one thing changes
• Misaligned with business: Doesn't support actual user journeys
• Hard to scale: Performance and reliability issues

Systems thinking addresses these root causes.

Benefit 1: Holistic Understanding

See the whole system, not just parts.

Example: E-Commerce Checkout

Component-focused view:

• Shopping cart service
• Payment service
• Inventory service
• Notification service

Systems thinking view:

User → Cart Service → Payment Service → Inventory → Notification
  ↑                                              ↓
  └────────────── Feedback Loop ─────────────────┘

In Sruja

CheckoutFlow = scenario "Complete Checkout" {
  User -> CartService "Items ready"
  CartService -> PaymentService "Process payment"
  PaymentService -> CartService "Payment result"
  CartService -> InventoryService "Reserve items"
  InventoryService -> CartService "Stock confirmed"
  CartService -> NotificationService "Send confirmation"
  NotificationService -> User "Order confirmed"
}

Impact

• Identifies the full user journey
• Reveals where things can fail
• Shows data dependencies
• Makes success criteria clear

Benefit 2: Natural Patterns

Model real-world interactions and feedback.

Example: Auto-Scaling

Component view: Configure scaling rules per service.

Systems thinking view: Understand the feedback loop.

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

App = system "Application" {
  API = container "API Service" {
    scale {
      min 2
      max 10
      metric "cpu > 80%"
    }
    slo {
      latency {
        p95 "200ms"
      }
    }
  }
}

Monitor = system "Monitoring System"

// Feedback loop
Monitor -> App.API "Observes load"
App.API -> Monitor "Reports metrics"
Monitor -> App.API "Triggers scale up/down"

Impact

• Self-documenting: The diagram explains the system
• Clear causality: Why do things happen?
• Predictable behavior: What happens under load?

Benefit 3: Clear Boundaries

Understand what's in scope vs. context.

Example: Third-Party Integration

Without boundaries: Where does your system end and Stripe begin?

With boundaries in Sruja:

// Inside: Your responsibility
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API Service"
}

// Outside: External dependency
Stripe = system "Stripe" {
  metadata {
    tags ["external", "pci-compliant"]
  }
  description "Payment processing service"
}

// Boundary crossing
Shop.API -> Stripe "Process payment"
Stripe -> Shop.API "Payment result"

Impact

• Clear ownership: Who's responsible for what?
• Risk management: What external dependencies exist?
• Testing boundaries: What needs integration tests vs. unit tests?
• Failure modes: What if the external service goes down?

Benefit 4: Flow Visualization

See how data and information move.

Example: Data Lineage

Without flows: Where does this data come from?

With flows in Sruja:

DataPipeline = flow "Order Analytics" {
  User -> Shop.WebApp "Submits order"
  Shop.WebApp -> Shop.API "Order data"
  Shop.API -> Shop.Database "Persist order"
  Shop.Database -> Analytics "Extract"
  Analytics -> DataWarehouse "Transform & load"
  DataWarehouse -> Dashboard "Visualize"
  Dashboard -> BusinessTeam "Make decisions"
}

Impact

• Traceability: Where does data originate?
• Compliance: What data flows where?
• Performance: Where are bottlenecks?
• Security: Where is sensitive data exposed?

Benefit 5: Valid Cycles

Feedback loops are natural, not errors.

Example: Real-Time Updates

Traditional view: Cycles are bad (circular dependency).

Systems thinking view: Cycles enable real-time behavior.

// Real-time collaboration
CollaborationSystem = system "Collaboration Tool" {
  Editor = container "Editor App"
  Sync = container "Sync Service"
  Database = database "Real-time DB"
}

// Valid feedback loop
Editor -> Sync "Local change"
Sync -> Database "Persist change"
Database -> Sync "Broadcast to others"
Sync -> Editor "Receive remote changes"
Editor -> Database "Acknowledge receipt"

Impact

• Models real behavior: Systems often have natural cycles
• Enables async patterns: Event-driven architectures
• Simplifies mental model: Don't force acyclic where it doesn't belong
• Better documentation: Shows the true system behavior

Practical Benefits

For Development

• Better communication: Diagrams that everyone understands
• Faster onboarding: New team members see the big picture quickly
• Clear requirements: Scenarios define expected behavior
• Easier testing: Flows guide test scenarios

For Operations

• Better monitoring: Feedback loops show what to observe
• Clearer incident response: Understand the failure path
• Capacity planning: See data flows and bottlenecks
• Change impact: What breaks if X changes?

For Business

• Aligns with user journeys: Scenarios mirror real workflows
• Clearer ownership: Boundaries show responsibility
• Risk visibility: Dependencies and external factors visible
• Better decisions: Full picture, not isolated features

When to Use Systems Thinking

Perfect for:

• System design and architecture
• Migration planning
• Feature impact analysis
• Root cause analysis
• Cross-team coordination

Less critical for:

• Simple CRUD applications
• Individual feature implementation
• Quick prototypes
• Isolated bug fixes

Common Mistakes

Over-Engineering

Don't model everything. Start with the core system and add detail as needed.

Ignoring Context

Focusing only on technical components and missing stakeholders.

Missing Flows

Modeling components but not how data moves between them.

Forcing Cycles Out

Removing valid feedback loops because "cycles are bad."

Key Takeaways

1. Systems thinking prevents common architecture problems
2. Benefits span development, operations, and business
3. Sruja provides concrete tools for each concept
4. Use it appropriately - not everything needs full systems modeling
5. Start simple, add detail incrementally

Exercise

Think of a recent architecture decision or problem you encountered. How would systems thinking have helped?

• Could you have seen the full user journey?
• Were there hidden dependencies?
• Were external dependencies clear?
• Did you understand the data flows?
• Were there feedback loops you missed?

Module 1 Complete

You've completed the fundamentals module! You now understand:

• What systems thinking is
• The five core concepts
• Why it matters for software architecture

Next: Dive into specific concepts starting with Module 2: Parts and Relationships.

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.

Lesson 1: Identifying Parts

Learning Goals

• Learn how to identify the key parts of a system
• Understand the different types of components
• Practice identifying parts from requirements

What Are Parts?

In systems thinking, "parts" are the distinct components that make up a system. In software architecture, these are the building blocks: users, systems, services, databases, queues, and more.

The C4 Model Hierarchy

Sruja follows the C4 model, which provides a clear hierarchy of parts:

Level 1: Person (Users, stakeholders)
  ↓
Level 2: System (Software systems)
  ↓
Level 3: Container (Applications, databases, services)
  ↓
Level 4: Component (Modules, classes, libraries)

Identifying Parts: Step by Step

Step 1: Start with People

Who interacts with the system?

Example Requirements:

"Customers can browse products, add to cart, and checkout. Administrators can manage inventory and view reports."

People identified:

• Customer
• Administrator

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

Customer = person "Customer"
Administrator = person "Administrator"

Step 2: Identify Systems

What software systems are involved?

From requirements:

• E-commerce platform (the main system)
• Payment gateway (external)
• Email service (external)

ECommerce = system "E-Commerce Platform"
PaymentGateway = system "Payment Gateway"
EmailService = system "Email Service"

Step 3: Break Down Systems into Containers

What applications, services, and databases make up each system?

For E-Commerce:

• Web Application (React frontend)
• API Service (Node.js backend)
• Database (PostgreSQL)
• Cache (Redis)

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

Step 4: Break Down Containers into Components (Optional)

What modules or components make up each container?

For API Service:

• Product Service
• Cart Service
• Order Service
• Payment Service

API = container "API Service" {
  ProductService = component "Product Service"
  CartService = component "Cart Service"
  OrderService = component "Order Service"
  PaymentService = component "Payment Service"
}

Common Patterns

Pattern 1: Frontend-Backend-Database

App = system "Application" {
  Frontend = container "Web App" {
    technology "React"
  }
  Backend = container "API Service" {
    technology "Node.js"
  }
  Database = database "Database" {
    technology "PostgreSQL"
  }
}

Pattern 2: Microservices

App = system "Microservice Application" {
  APIGateway = container "API Gateway"
  UserService = container "User Service"
  OrderService = container "Order Service"
  NotificationService = container "Notification Service"
}

Pattern 3: Event-Driven

App = system "Event-Driven System" {
  Producer = container "Event Producer"
  Consumer = container "Event Consumer"
  MessageQueue = queue "Kafka Cluster"
}

Anti-Patterns to Avoid

Anti-Pattern 1: Oversimplification

Don't:

// Too simple, loses important detail
App = system "The App"

Do:

// Shows structure
App = system "The App" {
  Frontend = container "Frontend"
  Backend = container "Backend"
  Database = database "Database"
}

Anti-Pattern 2: Over-Engineering

Don't:

// Too detailed, hard to understand
App = system "The App" {
  Frontend = container "Frontend" {
    Header = component "Header"
    Body = component "Body"
    Footer = component "Footer"
  }
}

Do:

// Right level of detail
App = system "The App" {
  Frontend = container "Frontend"
  Backend = container "Backend"
}

Anti-Pattern 3: Mixing Levels

Don't:

// Inconsistent level of detail
App = system "The App" {
  Frontend = container "Frontend"
  UserService = component "User Service"  // Skips container level
  Database = database "Database"
}

Do:

// Consistent hierarchy
App = system "The App" {
  Frontend = container "Frontend"
  Backend = container "Backend" {
    UserService = component "User Service"
  }
  Database = database "Database"
}

Exercise: Identify Parts

Read these requirements and identify the parts:

"A project management tool allows team members to 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."

Identify:

1. People: _
2. Systems: _
3. Containers: _

Key Takeaways

1. Start with people: Who uses the system?
2. Use the C4 hierarchy: Person → System → Container → Component
3. Match detail to audience: Not every diagram needs components
4. Avoid anti-patterns: Don't oversimplify or over-engineer
5. Be consistent: Use the same level of detail throughout

Next Lesson

In Lesson 2, you'll learn how to use Sruja's element types to model the parts you've identified.

Lesson 2: Sruja Elements

Learning Goals

• Learn Sruja's core element types
• Understand when to use each type
• Model parts with proper Sruja syntax

Sruja Element Types

Sruja provides element types that map to the C4 model:

Person

Use person to represent humans who interact with your system.

Basic Syntax

person = kind "Person"

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

With Details

Customer = person "Customer" {
  description "End users who purchase products"
  metadata {
    type ["external"]
    priority "high"
  }
}

When to Use

• End users (customers, employees)
• Stakeholders (managers, business owners)
• Support teams
• External users (API consumers)

Examples

// Internal users
Developer = person "Developer"
ProductManager = person "Product Manager"

// External users
APIConsumer = person "API Consumer"
Partner = person "Business Partner"

System

Use system to represent standalone software systems.

Basic Syntax

system = kind "System"

Shop = system "E-Commerce Platform"
APIGateway = system "API Gateway"
PaymentGateway = system "Payment Gateway"

With Details

ECommerce = system "E-Commerce Platform" {
  description "Platform for buying and selling products"
  metadata {
    version "2.0"
    team ["platform-team"]
  }
  slo {
    availability {
      target "99.9%"
    }
  }
}

When to Use

• Main application you're building
• External systems you depend on
• Third-party services
• Separate software products

Examples

// Your systems
Platform = system "Sruja Platform"
Dashboard = system "Analytics Dashboard"

// External systems
Stripe = system "Stripe"
AWS = system "Amazon Web Services"
GitHub = system "GitHub"

Container

Use container to represent applications, databases, and other deployable units within a system.

Basic Syntax

container = kind "Container"

WebApp = container "Web Application"
API = container "API Service"
DB = database "Database"
Queue = queue "Message Queue"

With Details

WebApp = container "Web Application" {
  technology "React"
  description "Single-page application"
  version "3.1.0"
  tags ["frontend", "typescript"]
  scale {
    min 2
    max 10
  }
  slo {
    latency {
      p95 "200ms"
    }
  }
}

When to Use

• Web applications (React, Vue, Angular)
• API services (Node.js, Rust, Python)
• Databases (PostgreSQL, MongoDB)
• Message queues (Kafka, RabbitMQ)
• Caches (Redis, Memcached)

Database vs Datastore

// Database (relational)
UserDB = database "User Database" {
  technology "PostgreSQL"
}

// Datastore (document)
CacheDB = datastore "Redis Cache" {
  technology "Redis"
}

Component

Use component to represent modules or services within a container.

Basic Syntax

component = kind "Component"

AuthService = component "Authentication Service"
UserService = component "User Service"
OrderController = component "Order Controller"

With Details

AuthService = component "Authentication Service" {
  technology "Rust"
  description "Handles user login and registration"
  scale {
    min 1
    max 5
  }
}

When to Use

• Service modules within a monolith
• Controllers in MVC architecture
• Domain services
• Library components
• Utilities and helpers

Complete Example

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

// People (Level 1)
Customer = person "Customer"
Administrator = person "Administrator"

// Systems (Level 2)
ECommerce = system "E-Commerce Platform"
PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
  }
}

// Containers (Level 3)
ECommerce = system "E-Commerce Platform" {
  WebApp = container "Web Application" {
    technology "React"
  }

  API = container "API Service" {
    technology "Node.js"
    scale {
      min 3
      max 10
    }

    // Components (Level 4)
    ProductService = component "Product Service"
    CartService = component "Cart Service"
    OrderService = component "Order Service"
    PaymentService = component "Payment Service"
  }

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

  Cache = queue "Redis" {
    technology "Redis 7"
  }
}

Naming Conventions

Element IDs

Use PascalCase for element IDs:

Good:
Customer = person "Customer"
WebApp = container "Web App"

Bad:
customer = person "Customer"  // SnakeCase
WEBAPP = container "Web App"  // ALL CAPS

Display Names

Use descriptive names with proper capitalization:

Good:
User = person "End User"
API = container "API Service"

Bad:
User = person "user"  // Lowercase
API = container "api"  // Lowercase

Consistency

Be consistent across your architecture:

Good:
UserService = component "User Service"
OrderService = component "Order Service"
PaymentService = component "Payment Service"

Bad:
UserService = component "User Service"
Order = component "Order"
Payment = component "Payment Service"

Adding Metadata

Use metadata to add context:

API = container "API Service" {
  technology "Rust"
  version "2.0.1"
  tags ["backend", "api"]
  metadata {
    team ["platform-team"]
    repository "github.com/company/api"
  }
}

Exercise

Model the following using Sruja elements:

"A blog 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."

Create elements for:

• People
• Systems
• Containers
• Components

Key Takeaways

1. Four core element types: person, system, container, component
2. Match type to C4 level: Each has a specific purpose
3. Add details: technology, description, tags, scale, SLOs
4. Follow naming conventions: Be consistent
5. Use metadata: Add context for your team

Next Lesson

In Lesson 3, you'll learn how to connect parts with relationships.

Lesson 3: Defining Relationships

Learning Goals

• Understand how parts connect
• Learn Sruja relationship syntax
• Write clear, meaningful relationship labels
• Model different types of interactions

What Are Relationships?

Relationships describe how parts interact. They show:

• Communication between components
• Data flow
• Dependencies
• User actions

Basic Syntax

From -> To "Label"

• From: Source element
• To: Destination element
• "Label": What the relationship represents (required)

Examples

Person to System

Customer -> Shop "Uses"
Administrator -> Shop "Manages"

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"
Shop.API.CartService -> Shop.API.OrderService "Creates order"

Relationship Labels

Labels should be clear, concise, and meaningful.

Good Labels

Customer -> Shop.WebApp "Browses products"
Shop.API -> Shop.Database "Queries data"
Shop.API -> PaymentGateway "Processes payment"

Bad Labels

Customer -> Shop.WebApp "Uses"  // Too generic
Shop.API -> Shop.Database "Connects"  // Doesn't describe what happens
Shop.API -> PaymentGateway "Integration"  // Technical, not behavioral

Label Guidelines

• Use present tense verbs: "uses", "reads", "calls"
• Be specific: "Processes payment" vs "uses"
• Show direction: Clear who initiates the action
• Keep it short: 2-5 words is ideal

Relationship Patterns

Pattern 1: User Interactions

User -> WebApp "Logs in"
User -> WebApp "Views products"
User -> WebApp "Adds to cart"
User -> WebApp "Checks out"

Pattern 2: Service Communication

WebApp -> API "Sends requests"
API -> Database "Persists data"
API -> Cache "Reads cache"
Cache -> API "Returns cached data"

Pattern 3: External Dependencies

API -> PaymentGateway "Process payment"
API -> EmailService "Send notifications"
API -> AnalyticsService "Track events"

Nested Element References

Use dot notation to reference nested elements:

// Direct child reference
Customer -> Shop.WebApp "Uses"

// Nested component reference
Shop.API.ProductService -> Shop.API.CartService "Get product info"

// Cross-system reference
Shop.API -> PaymentGateway.ChargeService "Process payment"

Relationship Tags

Add tags to categorize relationships:

From -> To "Label" [tag1, tag2]

// Example
Shop.API -> PaymentGateway "Process payment" [critical, external]
Shop.WebApp -> Shop.API "API call" [http]

Common Tags

// Protocol
[http], [grpc], [websocket]

// Importance
[critical], [optional], [best-effort]

// Data type
[synchronous], [asynchronous], [streaming]

// Security
[encrypted], [authenticated], [public]

// Scope
[internal], [external], [partner]

Multiple Relationships

Elements can have multiple relationships:

// WebApp has multiple relationships
Customer -> Shop.WebApp "Browses"
Shop.WebApp -> Shop.API "Queries products"
Shop.WebApp -> Shop.Cache "Reads cache"
Shop.WebApp -> Customer "Displays products"

// API has multiple relationships
Shop.WebApp -> Shop.API "Sends request"
Shop.API -> Shop.Database "Persists order"
Shop.API -> PaymentGateway "Process payment"
Shop.API -> Shop.WebApp "Returns response"

Relationship Direction

One-Way

Customer -> Shop.WebApp "Uses"

Two-Way (Two separate relationships)

User -> App.API "Submits data"
App.API -> User "Returns result"

Feedback Loop (Cycle)

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)

Relationships in Views

Relationships are automatically included in views:

view index {
  include *
}

view container_view of Shop {
  include Shop.*
}

Complete Example

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

// Elements
Customer = person "Customer"
Admin = person "Administrator"

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

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
  }
}

// Relationships
Customer -> Shop.WebApp "Browses products" [public]
Customer -> Shop.WebApp "Adds to cart" [authenticated]
Customer -> Shop.WebApp "Checks out" [authenticated]

Shop.WebApp -> Shop.API "Sends requests" [http, encrypted]
Shop.API -> Shop.DB "Persists data" [critical]
Shop.API -> Shop.DB "Queries data" [cached]

Shop.API -> PaymentGateway "Process payment" [critical, external]

Admin -> Shop.WebApp "Manages products" [authenticated]
Admin -> Shop.WebApp "Views reports" [authenticated]

view index {
  include *
}

Exercise

Add relationships to this architecture:

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

Reader = person "Reader"
Writer = person "Writer"

Blog = system "Blog Platform" {
  Frontend = container "Web App"
  Backend = container "API"
  Database = database "PostgreSQL"
}

EmailService = system "Email Service" {
  tags ["external"]
}

Define relationships for:

• Reader interactions
• Writer interactions
• Backend-Database communication
• Backend-EmailService integration

Key Takeaways

1. Relationships show interactions: How parts communicate
2. Labels must be meaningful: Clear, specific verbs
3. Use dot notation: Reference nested elements
4. Add tags: Categorize relationships
5. Multiple relationships: Elements can have many connections

Next Lesson

In Lesson 4, you'll learn how to organize parts using hierarchy and nesting.

Lesson 4: Hierarchy and Nesting

Learning Goals

• Understand how to organize parts hierarchically
• Learn nesting patterns for containers and components
• Model complex systems with clear structure
• Balance detail and clarity

The C4 Hierarchy

Sruja follows the C4 model hierarchy:

Person (Level 1)
  ↓
System (Level 2)
  ↓
Container (Level 3)
  ↓
Component (Level 4)

Nesting Containers in Systems

Systems contain containers:

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

Shop = system "E-Commerce Platform" {
  WebApp = container "Web Application" {
    technology "React"
  }

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

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

Benefits of Nesting

• Clear ownership: Containers belong to systems
• Logical grouping: Related components together
• Simpler references: Use dot notation
• Better organization: Easier to navigate

Nesting Components in Containers

Containers contain components:

API = container "API Service" {
  AuthService = component "Authentication Service"
  ProductService = component "Product Service"
  CartService = component "Cart Service"
  OrderService = component "Order Service"
}

When to Add Components

Add components when:

• Container is complex (>5 logical parts)
• Different teams own different parts
• Need to show internal architecture
• Documenting for implementation

Skip components when:

• Container is simple (monolith)
• Too much detail for audience
• Container level is sufficient

Reference Patterns

Level 1 to Level 2 (Person to System)

Customer -> Shop "Uses"

Level 2 to Level 3 (System to Container)

Use dot notation:

Customer -> Shop.WebApp "Browses"
Customer -> Shop.API "Submits order"

Level 3 to Level 3 (Container to Container)

Shop.WebApp -> Shop.API "Sends requests"
Shop.API -> Shop.DB "Persists data"

Level 3 to Level 4 (Container to Component)

Shop.API -> Shop.API.ProductService "Get products"
Shop.API -> Shop.API.OrderService "Create order"

Level 4 to Level 4 (Component to Component)

Shop.API.ProductService -> Shop.API.CartService "Get product details"
Shop.API.CartService -> Shop.API.OrderService "Create order"

Multi-Level Systems

Complex Example

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

Customer = person "Customer"

ECommerce = system "E-Commerce Platform" {
  WebApp = container "Web Application" {
    technology "React"
  }

  API = container "API Service" {
    technology "Node.js"

    ProductService = component "Product Service"
    CartService = component "Cart Service"
    OrderService = component "Order Service"
    PaymentService = component "Payment Service"
    NotificationService = component "Notification Service"
  }

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

  Cache = queue "Redis" {
    technology "Redis 7"
  }
}

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
  }
}

EmailService = system "Email Service" {
  metadata {
    tags ["external"]
  }
}

// Relationships at different levels
Customer -> ECommerce.WebApp "Browses"
ECommerce.WebApp -> ECommerce.API "Makes requests"
ECommerce.API.ProductService -> ECommerce.Cache "Reads cache"
ECommerce.API.PaymentService -> PaymentGateway "Process payment"
ECommerce.API.NotificationService -> EmailService "Send notifications"

Hierarchy Best Practices

1. Be Consistent

Don't mix levels:

// 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"
}

2. Right Level of Detail

Match detail to audience:

// For business stakeholders
Platform = system "Platform" {
  WebApp = container "Web App"
  API = container "API"
}

// For developers
Platform = system "Platform" {
  WebApp = container "Web App" {
    Auth = component "Auth Module"
    Dashboard = component "Dashboard"
  }
  API = container "API" {
    UserService = component "User Service"
    ProductService = component "Product Service"
  }
}

3. Logical Grouping

Group related components:

// Good: Logical grouping
API = container "API" {
  UserServices = component "User Service"
  ProductServices = component "Product Service"
  OrderServices = component "Order Service"
}

// Also Good: Domain-based grouping
API = container "API" {
  UserDomain = component "User Module"
  ProductDomain = component "Product Module"
  OrderDomain = component "Order Module"
}

Implied Relationships

Sruja automatically infers some relationships:

Customer -> Shop.WebApp "Uses"
// Implies: Customer -> Shop

This reduces boilerplate while maintaining accuracy.

Views and Hierarchy

Create views at different hierarchy levels:

// Level 1 view (System Context)
view index {
  title "System Context"
  include *
}

// Level 2 view (System)
view system_view of Shop {
  title "Shop System"
  include Shop
}

// Level 3 view (Containers)
view container_view of Shop {
  title "Shop Containers"
  include Shop.*
  exclude Shop.Database
}

// Level 4 view (Components)
view component_view of Shop.API {
  title "API Components"
  include Shop.API.*
}

Anti-Patterns to Avoid

Anti-Pattern 1: Deep Nesting

// Bad: Too deep (hard to read)
App = system "App" {
  Frontend = container "Frontend" {
    Layout = component "Layout" {
      Header = component "Header" {
        Navigation = component "Navigation"
      }
    }
  }
}

Solution: Keep nesting to 3-4 levels max.

Anti-Pattern 2: Orphaned Elements

// Bad: Component without container
Shop = system "Shop"
WebApp = container "Web App"
API = component "API Service"  // Should be in a container

Solution: Nest components properly.

Anti-Pattern 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"

Solution: Show proper hierarchy.

Exercise

Create a nested architecture for:

"A social media platform with users, posts, and comments. The platform has a web frontend, mobile API, and backend services. The backend has user management, post management, and notification services. Data is stored in PostgreSQL and cached in Redis."

Create:

• Person level
• System level with nested containers
• Component level for at least one container

Key Takeaways

1. Follow C4 hierarchy: Person → System → Container → Component
2. Nest logically: Group related parts together
3. Use dot notation: Reference nested elements
4. Right level of detail: Match audience needs
5. Create multiple views: Show different hierarchy levels

Module 2 Complete

You've completed Parts and Relationships! You now understand:

• How to identify system parts
• Sruja's element types
• Defining meaningful relationships
• Organizing parts hierarchically

Next: Learn about Module 3: Boundaries.

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.

Lesson 1: Understanding Boundaries

Learning Goals

• Understand what boundaries are in software architecture
• Recognize different types of boundaries
• Learn why boundaries matter

What Are Boundaries?

A boundary is the line that separates what's inside your system (what you build, own, and maintain) from what's outside (the environment, external dependencies, and stakeholders).

┌─────────────────────────────────────┐
│          EXTERNAL                   │
│  (Environment, Dependencies)        │
│                                     │
│    ┌───────────────────────────┐    │
│    │     INTERNAL             │    │
│    │   (Your System)          │    │
│    │                           │    │
│    │  [Components]             │    │
│    │                           │    │
│    └───────────────────────────┘    │
│             ↑                         │
│     Boundary Line                    │
└─────────────────────────────────────┘

Why Boundaries Matter

1. Clear Ownership

Who's responsible for what?

// Inside: Your team owns this
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API Service"
}

// Outside: Another team/service owns this
PaymentGateway = system "Payment Gateway"

2. Risk Management

What external risks exist?

// External dependency = external risk
Shop.API -> PaymentGateway "Process payment"

// If PaymentGateway is down, what happens?
// What's your fallback? SLA?

3. Testing Scope

What needs integration tests vs. unit tests?

// Internal: Unit tests sufficient
Shop.WebApp -> Shop.API

// External: Integration tests needed
Shop.API -> PaymentGateway

4. Security

What needs protection?

// Inside boundary: Apply security controls
Shop.WebApp -> Shop.API

// Crossing boundary: Validate, authenticate
Shop.API -> PaymentGateway

Types of Boundaries

1. System Boundary

Your main application vs. the world:

// Inside
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API"
}

// Outside
Customer = person "Customer"

2. Team Boundary

What your team owns vs. what other teams own:

// Your team's system
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API"
}

// Another team's system
Analytics = system "Analytics Platform"

3. Organizational Boundary

Internal vs. external organizations:

// Your company's system
Shop = system "Shop"

// External vendor
Stripe = system "Stripe" {
  metadata {
    tags ["external", "vendor"]
  }
}

4. Deployment Boundary

What's deployed together:

// Same deployment
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API"
}

// Separate deployment
Database = system "Database Cluster"

5. Trust Boundary

Security and trust levels:

// Trusted: Internal network
InternalAPI = container "Internal API"

// Untrusted: Public internet
PublicAPI = container "Public API"

Boundary Examples

Example 1: E-Commerce Platform

// ┌──────────── EXTERNAL ────────────┐
// │                                  │
// │   Customer (person)               │
// │   Payment Gateway (system)        │
// │   Email Service (system)          │
// │                                  │
// │   ┌────── INTERNAL ─────────┐    │
// │   │ Shop (system)           │    │
// │   │   WebApp (container)    │    │
// │   │   API (container)       │    │
// │   │   Database (database)   │    │
// │   └─────────────────────────┘    │
// │                                  │
// └──────────────────────────────────┘

Customer -> Shop.WebApp "Uses"
Shop.WebApp -> Shop.API "Calls"
Shop.API -> PaymentGateway "Process payment"

Example 2: Microservices Architecture

// Internal boundaries (within organization)
OrderService = system "Order Service"
PaymentService = system "Payment Service"
InventoryService = system "Inventory Service"

OrderService -> PaymentService "Request payment"
PaymentService -> OrderService "Payment result"
OrderService -> InventoryService "Reserve items"

Boundary Anti-Patterns

Anti-Pattern 1: No Clear Boundary

// Bad: Everything looks internal
Customer = person "Customer"
Shop = system "Shop"
PaymentGateway = system "Payment Gateway"
EmailService = system "Email Service"

// Without tags, it's unclear what's external

Solution: Use metadata tags to mark external systems.

Anti-Pattern 2: Everything External

// Bad: Everything marked external, no ownership
Shop = system "Shop" {
  tags ["external"]
}
WebApp = container "Web App" {
  tags ["external"]
}

Solution: Mark only truly external systems.

Anti-Pattern 3: Too Many Boundaries

// Bad: Overly fragmented, hard to understand
System1 = system "System 1"
System2 = system "System 2"
System3 = system "System 3"
// ... many small systems

Solution: Group related functionality.

Defining Boundaries in Sruja

Use system for Main Boundary

Shop = system "Shop" {
  // Internal containers
  WebApp = container "Web App"
  API = container "API"
}

Use Metadata for External Systems

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external", "vendor"]
    owner "Third-party"
  }
}

Use person for External Actors

// Users are outside the system boundary
Customer = person "Customer"
Administrator = person "Administrator"

Exercise

Identify the boundaries in this scenario:

"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."

Identify:

1. Internal system: _
2. External systems: _
3. External actors: _
4. Boundary crossings: _

Key Takeaways

1. Boundaries define ownership: What you build vs. what you depend on
2. Multiple boundary types: System, team, organization, deployment, trust
3. Mark external systems: Use metadata tags
4. Document crossings: Show how boundaries are crossed
5. Avoid anti-patterns: Clear but not over-fragmented boundaries

Next Lesson

In Lesson 2, you'll learn how to differentiate and mark internal vs. external components.

Lesson 2: Internal vs External

Learning Goals

• Learn how to mark components as internal or external
• Use Sruja metadata to annotate boundary elements
• Model team and organizational boundaries

Marking External Systems

Basic Pattern

// Internal: Your system
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API Service"
}

// External: Third-party system
PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
  }
}

Metadata for External Systems

External Tag

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
  }
}

External with Ownership

Stripe = system "Stripe" {
  metadata {
    tags ["external", "vendor"]
    owner "Stripe Inc."
  }
}

External with SLA

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
    sla "99.9% uptime"
  }
}

External with Compliance

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external", "pci-compliant"]
    compliance ["PCI-DSS Level 1"]
  }
}

Internal vs External Patterns

Pattern 1: Third-Party Services

// Your system
Shop = system "Shop"

// Third-party integrations
Stripe = system "Stripe" {
  metadata {
    tags ["external", "vendor", "pci-compliant"]
    owner "Stripe"
  }
}

Twilio = system "Twilio" {
  metadata {
    tags ["external", "vendor"]
    owner "Twilio"
  }
}

GoogleAnalytics = system "Google Analytics" {
  metadata {
    tags ["external", "vendor"]
    owner "Google"
  }
}

Pattern 2: Partner Integrations

// Your system
Shop = system "Shop"

// Partner systems
LogisticsPartner = system "Logistics Partner API" {
  metadata {
    tags ["external", "partner"]
    owner "FedEx"
  }
}

InventoryPartner = system "Inventory Partner" {
  metadata {
    tags ["external", "partner"]
    owner "Vendor X"
  }
}

Pattern 3: Internal Team Boundaries

// Your team's system
Shop = system "Shop"

// Another team's systems
UserPlatform = system "User Platform" {
  metadata {
    tags ["internal", "platform-team"]
    owner "Platform Team"
  }
}

AnalyticsPlatform = system "Analytics Platform" {
  metadata {
    tags ["internal", "data-team"]
    owner "Data Team"
  }
}

People: Always External

People are always outside the system boundary:

// External actors
Customer = person "Customer"
Administrator = person "Administrator"
Support = person "Customer Support"

// Your system
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API Service"
}

// People interact with internal components
Customer -> Shop.WebApp "Browses"
Administrator -> Shop.WebApp "Manages"
Support -> Shop.WebApp "Monitors"

Boundary Crossings

Crossing to External Systems

// External dependency
PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
  }
}

// Crossing the boundary
Shop.API -> PaymentGateway "Process payment"
PaymentGateway -> Shop.API "Payment result"

Multiple Boundary Crossings

Customer = person "Customer"

// Internal
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API"
}

// External 1
PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
  }
}

// External 2
EmailService = system "Email Service" {
  metadata {
    tags ["external"]
  }
}

// External 3
AnalyticsService = system "Analytics Service" {
  metadata {
    tags ["external"]
  }
}

// Multiple crossings
Customer -> Shop.WebApp "Places order"
Shop.WebApp -> Shop.API "Process order"
Shop.API -> PaymentGateway "Charge payment"
Shop.API -> EmailService "Send confirmation"
Shop.API -> AnalyticsService "Track event"

Teams and Boundaries

Single Team, One System

// Your team owns everything
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API"
  Database = database "Database"
}

Multiple Teams, Bounded Contexts

// Team A: Shop team
Shop = system "Shop" {
  metadata {
    tags ["internal", "shop-team"]
    owner "Shop Team"
  }
  WebApp = container "Web App"
  API = container "API"
}

// Team B: Payment team
Payment = system "Payment Service" {
  metadata {
    tags ["internal", "payment-team"]
    owner "Payment Team"
  }
  Processor = container "Payment Processor"
}

// Team C: Notification team
Notifications = system "Notification Service" {
  metadata {
    tags ["internal", "notification-team"]
    owner "Notification Team"
  }
  Sender = container "Notification Sender"
}

// Cross-team boundaries
Shop.API -> Payment.Processor "Process payment"
Shop.API -> Notifications.Sender "Send notification"

Complete Example

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

// External actors (always external)
Customer = person "Customer"
Administrator = person "Administrator"

// Internal system
Shop = system "Shop" {
  metadata {
    tags ["internal"]
    owner "Shop Team"
  }

  WebApp = container "Web Application"
  API = container "API Service"
  Database = database "PostgreSQL"
}

// External systems
PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external", "vendor", "pci-compliant"]
    owner "Stripe"
    sla "99.9% uptime"
  }
}

EmailService = system "Email Service" {
  metadata {
    tags ["external", "vendor"]
    owner "SendGrid"
  }
}

AnalyticsService = system "Analytics Service" {
  metadata {
    tags ["external", "vendor"]
    owner "Google"
  }
}

// Relationships
Customer -> Shop.WebApp "Uses"
Shop.WebApp -> Shop.API "Sends requests"
Shop.API -> Shop.Database "Persists data"

// Crossing boundaries
Shop.API -> PaymentGateway "Process payment"
PaymentGateway -> Shop.API "Payment result"
Shop.API -> EmailService "Send notifications"
Shop.API -> AnalyticsService "Track events"

view index {
  include *
}

Boundary Views

System Context View (Shows boundaries)

view index {
  title "System Context - Shows Internal vs External"
  include *
}

Internal-Only View

view internal_view of Shop {
  title "Internal Architecture"
  include Shop.*
  exclude external
}

Exercise

Mark internal and external components:

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

// Add metadata to mark external systems

Patient = person "Patient"
Doctor = person "Doctor"

Hospital = system "Hospital Scheduling" {
  WebApp = container "Web App"
  API = container "API Service"
  Database = database "Database"
}

InsuranceAPI = system "Insurance API"
SMSProvider = system "SMS Provider"

Add metadata to mark:

• External systems
• External dependencies
• Owner information

Key Takeaways

1. Use metadata tags: Mark external systems clearly
2. People are external: Users are outside the system
3. Document ownership: Who owns each system
4. Show crossings: How boundaries are crossed
5. Team boundaries: Internal boundaries between teams

Next Lesson

In Lesson 3, you'll learn how to model integrations and plan for boundary crossings.

Lesson 3: Crossing Boundaries

Learning Goals

• Model integrations across boundaries
• Plan for failures at boundaries
• Document interface contracts
• Design fallback strategies

Boundary Crossings

Every time a relationship crosses from internal to external, it's a boundary crossing:

// Internal → External = Boundary crossing
Shop.API -> PaymentGateway "Process payment"

// External → Internal = Boundary crossing
PaymentGateway -> Shop.API "Payment result"

Integration Patterns

Pattern 1: Request-Response

Shop.API -> PaymentGateway "Process payment"
PaymentGateway -> Shop.API "Payment result"

// Characteristics:
// - Synchronous
// - Real-time
// - Tight coupling

Pattern 2: Event-Driven

Shop.API -> EventQueue "Publish order event"
EventQueue -> PaymentProcessor "Consume order event"

// Characteristics:
// - Asynchronous
// - Decoupled
// - Resilient

Pattern 3: Polling

Shop.API -> ExternalAPI "Check status"
ExternalAPI -> Shop.API "Return status"

// Characteristics:
// - Periodic checks
// - No webhooks
// - Simpler but less efficient

Integration Considerations

1. Error Handling

What happens when external service fails?

// Document expected failure modes
PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
    sla "99.9% uptime"
    failure_modes ["timeout", "service unavailable", "network error"]
  }
}

// Model fallbacks
Shop.API -> PaymentGateway "Process payment" [primary]
Shop.API -> PaymentGatewayBackup "Process payment" [fallback]

2. Timeouts and Latency

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
    timeout "30s"
    expected_latency "500ms"
    max_latency "5s"
  }
}

Shop.API = container "API Service" {
  slo {
    latency {
      p95 "200ms"
      p99 "500ms"
    }
  }
}

3. Data Consistency

// Document consistency guarantees
Shop.API -> PaymentGateway "Process payment"
// If payment succeeds but order save fails:
// - Idempotent payment calls
// - Compensating transactions
// - Eventual consistency

4. Security

// Security at 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"]
  }
}

Documenting Interface Contracts

API Contract

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
    api_endpoint "https://api.payment.com/v1"
    authentication "API Key"
    rate_limit "1000 req/min"
  }
}

Shop.API = container "API Service" {
  metadata {
    api_consumer "Payment Gateway Client"
    retry_policy "3 retries with exponential backoff"
  }
}

Data Format

PaymentGateway = system "Payment Gateway" {
  metadata {
    data_format "JSON"
    schema_version "v1.2"
    validation "Strict schema validation"
  }
}

SLA and Reliability

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
    sla "99.9% uptime"
    mttr "4 hours"
    support "24/7 enterprise support"
  }
}

Fallback Strategies

Strategy 1: Redundant Providers

// Primary provider
PrimaryPayment = system "Primary Payment Gateway" {
  metadata {
    tags ["external", "primary"]
  }
}

// Backup provider
BackupPayment = system "Backup Payment Gateway" {
  metadata {
    tags ["external", "backup"]
  }
}

// Try primary, fall back to backup
Shop.API -> PrimaryPayment "Process payment" [primary]
Shop.API -> BackupPayment "Process payment" [fallback]

Strategy 2: Circuit Breaker

Shop.API = container "API Service" {
  metadata {
    circuit_breaker {
      enabled true
      failure_threshold "5"
      recovery_timeout "60s"
    }
  }
}

Strategy 3: Degraded Mode

// If external analytics fails, continue operation
Shop.API -> AnalyticsService "Track events" [non_critical]

// If email fails, queue for later
Shop.API -> EmailService "Send notifications" [async_queue]

Strategy 4: Cache External Data

// Cache external API responses
Shop.API -> ExternalAPI "Get exchange rates"
Shop.Cache -> Shop.API "Return cached rates"

// Fallback to cache if external fails
Shop.API -> Shop.Cache "Get cached rates" [fallback]

Complete Integration Example

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

Customer = person "Customer"

Shop = system "Shop" {
  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", "pci-compliant"]
    owner "Stripe Inc."
    sla "99.99% uptime"
    api_endpoint "https://api.stripe.com/v1"
    authentication "API Key"
    rate_limit "1000 req/min"
    data_format "JSON"
  }
}

// Backup payment provider
PayPal = system "PayPal" {
  metadata {
    tags ["external", "backup"]
    owner "PayPal"
    sla "99.9% uptime"
  }
}

// Email service
SendGrid = system "SendGrid" {
  metadata {
    tags ["external"]
    sla "99.9% uptime"
    timeout "10s"
  }
}

// Integrations
Customer -> Shop.WebApp "Checkout"
Shop.WebApp -> Shop.API "Process order"

// Primary payment integration (encrypted, authenticated)
Shop.API -> Stripe "Process payment" [primary, encrypted, tls1.3]
Stripe -> Shop.API "Payment result"

// Fallback to backup
Shop.API -> PayPal "Process payment" [fallback, encrypted]

// Email (non-critical, can queue)
Shop.API -> SendGrid "Send confirmation" [non_critical, async_queue]

// Cache external API calls
Shop.Cache -> Shop.API "Return cached data"

view index {
  include *
}

Boundary Testing

What to Test at Boundaries

// Document test requirements
PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
    tests [
      "Happy path integration test",
      "Timeout handling",
      "Error response handling",
      "Rate limiting",
      "Authentication failure"
    ]
  }
}

Exercise

Design an integration for:

"A weather application displays current weather and forecasts. The app fetches weather data from OpenWeatherMap API and sends location-based ads to users. The ad service is provided by an external vendor."

Consider:

1. Boundary crossings
2. Error handling
3. Caching strategy
4. Fallbacks (if any)

Key Takeaways

1. Every boundary crossing is an integration point
2. Document interface contracts: API endpoints, data formats, SLAs
3. Plan for failures: Timeouts, errors, service outages
4. Design fallbacks: Redundant providers, degraded modes, caching
5. Test boundaries: Integration tests, error scenarios

Module 3 Complete

You've completed Boundaries! You now understand:

• What boundaries are and why they matter
• How to mark internal vs. external components
• How to model integrations and plan for boundary crossings

Next: Learn about Module 4: Flows.

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.

Lesson 1: Understanding Flows

Learning Goals

• Understand what flows are in systems thinking
• Learn when to use flows vs. static relationships
• Recognize different types of flows

What Are Flows?

Flows show how information, data, and actions move through a system. Unlike static relationships (which show connections), flows show sequences and transformations.

Static Relationship vs. Flow

// Static relationship: Shows connection
Customer -> Shop.WebApp "Uses"

// Flow: Shows sequence
CheckoutFlow = scenario "Checkout" {
  Customer -> Shop.WebApp "Submits order"
  Shop.WebApp -> Shop.API "Sends order data"
  Shop.API -> Shop.Database "Saves order"
}

Why Flows Matter

1. Data Lineage

Where does data come from and where does it go?

DataFlow = flow "Order Analytics" {
  Customer -> Shop.WebApp "Order data"
  Shop.WebApp -> Shop.API "API request"
  Shop.API -> Shop.Database "Persist"
  Shop.Database -> Analytics "Extract"
  Analytics -> Dashboard "Visualize"
}

2. Process Understanding

What's the sequence of actions?

OrderProcess = scenario "Order Processing" {
  Customer -> Shop.WebApp "Submits order"
  Shop.WebApp -> Shop.API "Process order"
  Shop.API -> PaymentGateway "Charge payment"
  Shop.API -> InventoryService "Reserve items"
  Shop.API -> EmailService "Send confirmation"
}

3. Bottleneck Identification

Where can things slow down?

UploadFlow = scenario "File Upload" {
  User -> Frontend "Upload file"
  Frontend -> API "Send file data"
  API -> Storage "Store file"
  Storage -> Processing "Process file"  // Potential bottleneck
  Processing -> Notification "Notify user"
}

4. Error Paths

What happens when things fail?

OrderFlow = scenario "Order Processing" {
  Customer -> Shop.API "Submit order"
  Shop.API -> PaymentGateway "Charge payment"
  PaymentGateway -> Shop.API "Payment result"

  // Success path
  Shop.API -> Shop.Database "Save order"
  Shop.API -> EmailService "Send confirmation"

  // Failure path
  Shop.API -> Shop.WebApp "Return error"
  Shop.WebApp -> Customer "Display error"
}

Types of Flows

1. Data Flow (DFD Style)

Shows how data moves through the system:

OrderFlow = flow "Order Data Flow" {
  Customer -> Shop.WebApp "Order details"
  Shop.WebApp -> Shop.API "Order JSON"
  Shop.API -> Shop.Database "Order record"
  Shop.Database -> Analytics "Order event"
}

Use when: Modeling data lineage, ETL processes, analytics pipelines

2. User Journey / Scenario (BDD Style)

Shows user interactions and system responses:

Checkout = story "User Checkout Flow" {
  Customer -> Shop.WebApp "Clicks checkout"
  Shop.WebApp -> Shop.API "Validate cart"
  Shop.API -> PaymentGateway "Process payment"
  PaymentGateway -> Shop.API "Payment result"
  Shop.API -> Shop.WebApp "Order confirmation"
  Shop.WebApp -> Customer "Show success message"
}

Use when: Modeling user stories, test scenarios, requirements

3. Control Flow

Shows decision points and branches:

ApprovalFlow = scenario "Order Approval" {
  Order -> ApprovalService "Submit for approval"

  // Branch 1: Auto-approved
  ApprovalService -> Database "Save order"

  // Branch 2: Manual review
  ApprovalService -> Manager "Request approval"
  Manager -> ApprovalService "Approve/Reject"
  ApprovalService -> Database "Save order"
}

Use when: Modeling business logic, workflows

4. Event Flow

Shows events and their propagation:

EventFlow = flow "Order Event Flow" {
  API -> EventBus "Publish order created"
  EventBus -> NotificationService "Consume event"
  EventBus -> AnalyticsService "Consume event"
  EventBus -> EmailService "Consume event"
}

Use when: Event-driven architectures, pub/sub patterns

Flow Characteristics

Linear Flow

LinearFlow = scenario "Simple Process" {
  Step1 -> Step2
  Step2 -> Step3
  Step3 -> Step4
}

Branching Flow

BranchingFlow = scenario "With Conditions" {
  Step1 -> Step2

  // Branch A
  Step2 -> Step3A
  Step3A -> Step4

  // Branch B
  Step2 -> Step3B
  Step3B -> Step4
}

Converging Flow

ConvergingFlow = scenario "Parallel then Merge" {
  Step1 -> Step2A
  Step1 -> Step2B
  Step2A -> Step3
  Step2B -> Step3
  Step3 -> Step4
}

Flows in Sruja

Using scenario

MyScenario = scenario "Scenario Title" {
  Step1 -> Step2 "Action"
  Step2 -> Step3 "Action"
}

Using story (alias)

MyStory = story "Story Title" {
  Step1 -> Step2 "Action"
  Step2 -> Step3 "Action"
}

Using flow

MyFlow = flow "Flow Title" {
  Step1 -> Step2 "Data"
  Step2 -> Step3 "Data"
}

When to Use Flows

Use Flows When

• You need to show sequence (order matters)
• Modeling data lineage or transformation
• Documenting user journeys
• Understanding process steps
• Identifying bottlenecks

Don't Use Flows When

• Showing general connections (use static relationships)
• High-level overview (too much detail)
• Simple system (relationships suffice)

Flow Anti-Patterns

Anti-Pattern 1: Too Detailed

// Bad: Too much detail
Flow = scenario "Login" {
  User -> UI "Click login button"
  UI -> API "HTTP POST /login"
  API -> Database "SELECT * FROM users"
  Database -> API "User record"
  API -> Auth "Verify password"
  Auth -> API "Result"
  API -> UI "Response"
  UI -> User "Show dashboard"
}

Solution: Group related steps.

Anti-Pattern 2: Too Abstract

// Bad: Not useful
Flow = scenario "Process" {
  Start -> End "Process completes"
}

Solution: Add meaningful intermediate steps.

Anti-Pattern 3: Mixing Flows with Static Relationships

// Bad: Confusing to read
Customer -> Shop.WebApp "Uses"
OrderFlow = scenario "Checkout" {
  Customer -> Shop.WebApp "Submits order"
}

Solution: Keep flows separate from static architecture.

Exercise

Identify the type of flow for each scenario:

1. "User clicks 'Buy Now', sees payment form, enters card details, sees success page"
2. "Order data is sent to API, saved to database, extracted to analytics warehouse"
3. "Order is created, event is published, multiple services process the event"
4. "Order is submitted, if >$100 requires approval, otherwise auto-approved"

Key Takeaways

1. Flows show sequences: How things happen, not just connections
2. Multiple flow types: Data flows, user journeys, control flows, event flows
3. Right level of detail: Not too detailed, not too abstract
4. Use appropriately: When sequence matters
5. Separate from static: Flows complement, don't replace, relationships

Next Lesson

In Lesson 2, you'll learn how to create data flow diagrams.

Lesson 2: Data Flow Diagrams

Learning Goals

• Create DFD-style data flows in Sruja
• Model data lineage and transformations
• Document ETL and analytics pipelines

What Are Data Flow Diagrams?

Data Flow Diagrams (DFDs) show how data moves through a system, including:

• Where data originates
• Where it's stored
• How it's transformed
• Where it ultimately goes

DFD Elements in Sruja

flow for Data-Oriented Flows

OrderDataFlow = flow "Order Data Processing" {
  Customer -> Shop.WebApp "Order form data"
  Shop.WebApp -> Shop.API "Order JSON"
  Shop.API -> Shop.Database "Order record"
  Shop.Database -> Analytics "Order event"
  Analytics -> Dashboard "Aggregated metrics"
}

DFD Patterns

Pattern 1: ETL Pipeline

ETLPipeline = flow "Data ETL Pipeline" {
  SourceSystem -> DataCollector "Raw data"
  DataCollector -> MessageQueue "Data events"
  MessageQueue -> DataProcessor "Consumes data"
  DataProcessor -> DataWarehouse "Transformed data"
  DataWarehouse -> ReportingEngine "Query results"
  ReportingEngine -> Dashboard "Visualizations"
}

Pattern 2: Event Sourcing

EventFlow = flow "Event Sourcing Pipeline" {
  API -> EventStore "Persist events"
  EventStore -> ProjectorA "Project to read model A"
  EventStore -> ProjectorB "Project to read model B"
  ProjectorA -> ReadDatabaseA "Read model A"
  ProjectorB -> ReadDatabaseB "Read model B"
}

Pattern 3: Analytics Pipeline

AnalyticsFlow = flow "User Analytics Pipeline" {
  UserApp -> TrackingService "User actions"
  TrackingService -> EventStream "Raw events"
  EventStream -> BatchProcessor "Daily batch"
  BatchProcessor -> DataWarehouse "Aggregated data"
  DataWarehouse -> ReportingTool "Analytics queries"
  ReportingTool -> BusinessTeam "Insights"
}

Pattern 4: Real-Time Processing

RealTimeFlow = flow "Real-Time Fraud Detection" {
  TransactionAPI -> IngestService "Transaction data"
  IngestService -> KafkaStream "Event stream"
  KafkaStream -> FraudDetectionService "Consume events"
  FraudDetectionService -> AlertService "Fraud alerts"
  AlertService -> SecurityTeam "Notifications"
}

Documenting Data Transformations

Use Relationship Labels

DataFlow = flow "Data Transformation" {
  RawSource -> ETLService "Raw CSV data"
  ETLService -> CleanedData "Validated, normalized data"
  CleanedData -> Aggregator "Aggregated metrics"
  Aggregator -> DataWarehouse "Hourly aggregations"
}

Add Metadata for Details

ETLService = container "ETL Service" {
  metadata {
    transformations [
      "Remove invalid records",
      "Normalize phone numbers",
      "Standardize dates"
    ]
    output_format "JSON"
    output_schema "v2"
  }
}

Complete DFD Example

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

Customer = person "Customer"

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"
}

// Data flow: Order processing and analytics
OrderAnalyticsFlow = flow "Order Analytics Pipeline" {
  Customer -> Shop.WebApp "Submits order"
  Shop.WebApp -> Shop.API "Order data"
  Shop.API -> Shop.Database "Persist order"

  // Real-time data capture
  Shop.API -> Analytics.Ingestion "Order event"
  Analytics.Ingestion -> Analytics.Processing "Validates and enriches"
  Analytics.Processing -> Analytics.Warehouse "Stores aggregated data"

  // Query and visualization
  Dashboard.UI -> Analytics.Reporting "Query metrics"
  Analytics.Reporting -> Analytics.Warehouse "Fetch data"
  Analytics.Reporting -> Dashboard.UI "Return results"
}

view index {
  include *
}

Data Lineage Tracing

Forward Tracing

// Where does this data go?
OrderFlow = flow "Order Data Lineage" {
  OrderAPI -> Database "Save order"
  Database -> ReplicationService "Replicate to secondary"
  ReplicationService -> AnalyticsDB "Stream to analytics"
  AnalyticsDB -> ReportGenerator "Generate reports"
}

Backward Tracing

// Where does this data come from?
ReportFlow = flow "Report Data Source" {
  UserActivityReport <- AnalyticsDB "Aggregated data"
  AnalyticsDB <- EventStream "Raw events"
  EventStream <- UserApp "User actions"
}

Error Handling in Flows

Document Error Paths

OrderFlow = scenario "Order Processing with Errors" {
  Customer -> Shop.API "Submit order"
  Shop.API -> PaymentGateway "Process payment"

  // Success path
  PaymentGateway -> Shop.API "Payment success"
  Shop.API -> Shop.Database "Save order"

  // Error path
  PaymentGateway -> Shop.API "Payment failed"
  Shop.API -> Shop.WebApp "Return error"
  Shop.WebApp -> Customer "Show error message"
}

Retry Logic

Shop.API = container "API Service" {
  metadata {
    retry_policy {
      max_attempts 3
      backoff "exponential"
      initial_delay "1s"
    }
  }
}

Performance Considerations

Document Latency Expectations

PaymentGateway = system "Payment Gateway" {
  metadata {
    expected_latency "500ms"
    timeout "5s"
  }
}

OrderFlow = scenario "Order Processing" {
  Customer -> Shop.WebApp "Submit order" [user_interaction]
  Shop.WebApp -> Shop.API "Send order" [internal_fast]
  Shop.API -> PaymentGateway "Process payment" [external_slower]
}

Identify Bottlenecks

ProcessingFlow = flow "File Processing Pipeline" {
  Upload -> Storage "Store file" [fast]
  Storage -> Processor "Process file" [bottleneck]
  Processor -> Notification "Notify user" [fast]
}

Exercise

Create a DFD for:

"A fitness tracking app where users log workouts. Workout data is sent to an API, stored in a database, and also sent to a real-time analytics service. The analytics service processes events and updates user dashboards. Daily, a batch job aggregates data and generates reports stored in a data warehouse for business analysis."

Create:

• Main data flow
• At least one data transformation
• Real-time and batch processing paths

Key Takeaways

1. Use flow for DFDs: Data-oriented flows
2. Show transformations: How data changes
3. Document lineage: Where data comes from and goes
4. Handle errors: Show success and failure paths
5. Identify bottlenecks: Where processing slows down

Next Lesson

In Lesson 3, you'll learn how to model user journeys and behavioral scenarios.

Lesson 3: User Journeys

Learning Goals

• Model user journeys and behavioral scenarios
• Use BDD-style scenarios for requirements
• Document test cases with flows

What Are User Journeys?

User journeys (or scenarios) show how users interact with a system to achieve a goal. They're behavioral flows that capture:

• User actions
• System responses
• Success and failure paths
• Decision points

User Journey Elements in Sruja

scenario for Behavioral Flows

CheckoutScenario = scenario "User Checkout" {
  Customer -> Shop.WebApp "Clicks checkout"
  Shop.WebApp -> Shop.API "Validate cart"
  Shop.API -> PaymentGateway "Process payment"
  Shop.API -> EmailService "Send confirmation"
  Shop.WebApp -> Customer "Show success page"
}

story (alias)

CheckoutStory = story "As a customer, I want to checkout" {
  Customer -> Shop.WebApp "Clicks checkout"
  Shop.WebApp -> Shop.API "Validate cart"
  Shop.API -> PaymentGateway "Process payment"
  Shop.WebApp -> Customer "Show success page"
}

BDD (Behavior-Driven Development) Style

Given-When-Then Pattern

// GIVEN: Customer has items in cart
// WHEN: Customer clicks checkout
// THEN: Payment is processed and confirmation shown

CheckoutScenario = scenario "Customer Checkout" {
  Customer -> Shop.WebApp "Clicks checkout"
  Shop.WebApp -> Shop.API "Validate cart"
  Shop.API -> PaymentGateway "Process payment"
  Shop.API -> Shop.WebApp "Order confirmation"
  Shop.WebApp -> Customer "Show success page"
}

User Journey Patterns

Pattern 1: Happy Path

HappyPath = scenario "Successful User Registration" {
  User -> WebApp "Opens registration form"
  WebApp -> API "Submit registration"
  API -> Database "Create user"
  API -> EmailService "Send welcome email"
  API -> WebApp "Registration success"
  WebApp -> User "Show welcome page"
}

Pattern 2: Error Path

ErrorPath = scenario "Registration with Duplicate Email" {
  User -> WebApp "Submit registration"
  WebApp -> API "Submit registration"
  API -> Database "Check email exists"
  Database -> API "Email already exists"
  API -> WebApp "Return error"
  WebApp -> User "Show error: Email already registered"
}

Pattern 3: Branching Path

BranchingPath = scenario "Order Approval" {
  Manager -> WebApp "Submit for approval"

  // Branch 1: Auto-approved for < $100
  if value < 100 {
    WebApp -> API "Auto-approve"
    API -> Database "Save approved order"
  }

  // Branch 2: Manual review for > $100
  if value > 100 {
    WebApp -> API "Request manual approval"
    API -> Approver "Send approval request"
    Approver -> API "Approve order"
    API -> Database "Save approved order"
  }

  API -> WebApp "Approval result"
  WebApp -> Manager "Show confirmation"
}

Pattern 4: Retry Path

RetryPath = scenario "Payment with Retry" {
  Customer -> WebApp "Submit order"
  WebApp -> API "Process order"

  // First attempt fails
  API -> PaymentGateway "Process payment"
  PaymentGateway -> API "Payment failed: timeout"

  // Retry
  API -> PaymentGateway "Retry payment"
  PaymentGateway -> API "Payment success"

  API -> Database "Save order"
  API -> WebApp "Order confirmed"
  WebApp -> Customer "Show confirmation"
}

User Journey Examples

Example 1: E-Commerce

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

Customer = person "Customer"

Shop = system "Shop" {
  WebApp = container "Web Application"
  API = container "API Service"
  Database = database "Database"
}

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

// Complete user journey
CheckoutJourney = scenario "Complete Checkout" {
  Customer -> Shop.WebApp "Add item to cart"
  Customer -> Shop.WebApp "Click checkout"
  Shop.WebApp -> Shop.API "Validate cart"
  Shop.API -> Shop.Database "Check inventory"
  Shop.Database -> Shop.API "Inventory available"
  Shop.API -> PaymentGateway "Process payment"
  PaymentGateway -> Shop.API "Payment success"
  Shop.API -> Shop.Database "Save order"
  Shop.API -> EmailService "Send confirmation"
  Shop.WebApp -> Customer "Show order confirmation"
}

view index {
  include *
}

Example 2: User Authentication

AuthJourney = scenario "User Login" {
  User -> WebApp "Enter credentials"
  WebApp -> API "Submit login"
  API -> Database "Verify credentials"
  Database -> API "Valid credentials"
  API -> AuthService "Generate JWT token"
  AuthService -> API "Token"
  API -> WebApp "Return token and user data"
  WebApp -> User "Show dashboard"
}

Example 3: File Upload

UploadJourney = scenario "File Upload" {
  User -> WebApp "Select file and click upload"
  WebApp -> API "Upload file data"
  API -> Storage "Store file"
  Storage -> API "File URL"
  API -> ProcessingService "Process file"
  ProcessingService -> API "Processing complete"
  API -> WebApp "Upload success"
  WebApp -> User "Show file preview"
}

Complex User Journey

ComplexJourney = scenario "Complete Order Workflow" {
  Customer -> Shop.WebApp "Browse products"
  Shop.WebApp -> Shop.API "Get products"
  Shop.API -> Shop.Database "Query products"
  Shop.Database -> Shop.API "Product data"
  Shop.API -> Shop.WebApp "Product list"
  Shop.WebApp -> Customer "Display products"

  Customer -> Shop.WebApp "Add to cart"
  Shop.WebApp -> Shop.API "Add to cart"
  Shop.API -> Shop.Database "Save cart item"

  Customer -> Shop.WebApp "Checkout"
  Shop.WebApp -> Shop.API "Create order"
  Shop.API -> Shop.Database "Save order"
  Shop.API -> PaymentGateway "Process payment"
  PaymentGateway -> Shop.API "Payment result"

  // Success path
  if payment_success {
    Shop.API -> EmailService "Send confirmation"
    Shop.API -> InventoryService "Reserve items"
    Shop.API -> NotificationService "Notify warehouse"
    Shop.WebApp -> Customer "Order confirmation"
  }

  // Failure path
  if payment_failed {
    Shop.API -> Shop.WebApp "Payment error"
    Shop.WebApp -> Customer "Show error message"
  }
}

Testing with Scenarios

Acceptance Criteria

// As a customer, I want to checkout so that I can purchase products

AcceptanceScenario = scenario "Checkout Acceptance Criteria" {
  // AC1: Customer can checkout with valid payment
  Customer -> Shop.WebApp "Checkout with valid payment"
  Shop.WebApp -> Shop.API "Process order"
  Shop.API -> PaymentGateway "Charge card"
  PaymentGateway -> Shop.API "Success"
  Shop.API -> Shop.WebApp "Order confirmed"
  Shop.WebApp -> Customer "Show confirmation page"

  // AC2: Customer sees error with invalid payment
  Customer -> Shop.WebApp "Checkout with invalid card"
  Shop.WebApp -> Shop.API "Process order"
  Shop.API -> PaymentGateway "Charge card"
  PaymentGateway -> Shop.API "Declined"
  Shop.API -> Shop.WebApp "Payment failed"
  Shop.WebApp -> Customer "Show error message"

  // AC3: Customer receives email confirmation
  Shop.API -> EmailService "Send confirmation"
  Customer -> EmailService "Receive confirmation email"
}

Documenting Edge Cases

Edge Case Scenarios

EdgeCase1 = scenario "Checkout with Expired Card" {
  Customer -> Shop.WebApp "Checkout"
  Shop.WebApp -> Shop.API "Process payment"
  Shop.API -> PaymentGateway "Charge card"
  PaymentGateway -> Shop.API "Card expired"
  Shop.API -> Shop.WebApp "Error: Card expired"
  Shop.WebApp -> Customer "Show error and prompt new card"
}

EdgeCase2 = scenario "Checkout with Insufficient Inventory" {
  Customer -> Shop.WebApp "Checkout"
  Shop.WebApp -> Shop.API "Process order"
  Shop.API -> Shop.Database "Check inventory"
  Shop.Database -> Shop.API "Insufficient stock"
  Shop.API -> Shop.WebApp "Error: Not enough stock"
  Shop.WebApp -> Customer "Show error and suggest alternatives"
}

Exercise

Create user journeys for:

1. Happy Path: User registers successfully
2. Error Path: User tries to register with existing email
3. Branching: User submits order that requires approval if > $1000
4. Retry: Payment fails twice, succeeds on third attempt

Key Takeaways

1. Use scenario/story: For behavioral flows
2. Model happy and error paths: Document all outcomes
3. Include user actions: From user perspective
4. Document edge cases: Unexpected scenarios
5. Use for testing: Scenarios make good test cases

Module 4 Complete

You've completed Flows! You now understand:

• What flows are and when to use them
• Data Flow Diagrams (DFDs)
• User journeys and behavioral scenarios

Next: Learn about Module 5: Feedback Loops.

Module 5: Feedback Loops

Overview

In this module, you'll learn to model feedback loops - how actions create reactions that affect future actions. Feedback loops are natural patterns in systems and not errors.

Learning Objectives

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

• Understand different types of feedback loops
• Model positive and negative feedback
• Recognize when cycles are valid patterns
• Design self-regulating and adaptive systems

Lessons

• Lesson 1: Understanding Feedback Loops - What feedback loops are and why they matter
• Lesson 2: Types of Feedback Loops - Positive, negative, and balancing loops
• Lesson 3: Modeling Cycles - Creating valid cycles in Sruja

Prerequisites

• Completed Module 4: Flows

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 6: Context.

Lesson 1: Understanding Feedback Loops

Learning Goals

• Understand what feedback loops are
• Recognize feedback loops in everyday systems
• Learn why cycles are not errors

What Are Feedback Loops?

A feedback loop occurs when an action creates a reaction that affects future actions. It's a cycle where the output becomes input for the next iteration.

Action → Response → Adjustment → Action (repeated)

Everyday Examples

Example 1: Thermostat

Temperature drops
    ↓
Thermostat detects low temp
    ↓
Turns on heater
    ↓
Temperature rises
    ↓
Thermostat turns off heater
    ↓
Temperature drops
    ↓
[Loop repeats]

Example 2: Feedback at Work

Submit code for review
    ↓
Manager provides feedback
    ↓
Developer fixes issues
    ↓
Submit revised code
    ↓
[Loop repeats until approved]

Example 3: Social Media Algorithm

User watches video
    ↓
Algorithm recommends similar videos
    ↓
User watches more
    ↓
Algorithm learns preferences
    ↓
[Loop reinforces the behavior]

Feedback Loops in Software Architecture

Example 1: Auto-Scaling

// Positive feedback loop: Scale up when load increases
MonitoringSystem -> App.API "Detects high load"
App.API -> AutoScaler "Request scale up"
AutoScaler -> App.API "Adds more instances"
App.API -> MonitoringSystem "Reports lower load"

Example 2: User Experience

// User feedback loop
User -> App.WebApp "Submits form"
App.WebApp -> App.API "Validates"
App.API -> App.WebApp "Returns errors"
App.WebApp -> User "Shows errors"
// User corrects and resubmits (loop)

Example 3: Inventory Management

// Inventory feedback loop
Shop.API -> Inventory "Updates stock"
Inventory -> Shop.API "Notifies low stock"
Shop.API -> Admin "Sends alert"
Admin -> Shop.API "Restocks inventory"
Shop.API -> Inventory "Updates stock"
// Loop continues as inventory changes

Why Feedback Loops Matter

1. Self-Regulation

Systems can adjust automatically:

AutoScaling = scenario "Auto-Scaling Feedback" {
  Monitor -> App "Detects high CPU"
  App -> ScalingService "Request scale up"
  ScalingService -> App "Add instances"
  App -> Monitor "CPU decreases"
  // If CPU still high, loop repeats
}

2. Learning and Adaptation

Systems improve over time:

MLFeedback = scenario "Machine Learning Feedback" {
  User -> App "Rates recommendation"
  App -> MLModel "Update preferences"
  MLModel -> App "Improved recommendations"
  App -> User "Better suggestions"
  // User rates again, model improves
}

3. Error Recovery

Systems recover from failures:

RetryLoop = scenario "Retry with Backoff" {
  App -> ExternalAPI "Make request"
  ExternalAPI -> App "Request failed (timeout)"

  App -> ExternalAPI "Retry in 1s"
  ExternalAPI -> App "Request failed"

  App -> ExternalAPI "Retry in 2s"
  ExternalAPI -> App "Success"
}

4. Resource Management

Optimize resource usage:

ResourceFeedback = scenario "Cache Feedback" {
  App -> Cache "Check cache"
  Cache -> App "Cache miss"
  App -> Database "Query data"
  Database -> App "Return data"
  App -> Cache "Store in cache"

  // Next time: Cache hit
  App -> Cache "Check cache"
  Cache -> App "Cache hit (faster)"
}

Feedback Loop Types

1. Positive Feedback (Reinforcing)

Increases the effect, leading to exponential growth or collapse:

// Example: Viral sharing
UserA -> App "Shares content"
App -> UserB "Shows content"
UserB -> App "Shares content"
App -> UserC "Shows content"
UserC -> App "Shares content"
// More users see and share

Use when: viral growth, network effects, learning systems

2. Negative Feedback (Balancing)

Reduces the effect, maintaining stability:

// Example: Temperature control
Thermostat -> Heater "Turn on if too cold"
Heater -> Room "Heats room"
Room -> Thermostat "Temperature reading"
Thermostat -> Heater "Turn off if too warm"
// Maintains stable temperature

Use when: Stability, control, regulation

3. Delayed Feedback

Feedback occurs after a delay:

// Example: Performance monitoring
App -> Database "Slow query"
Database -> App "Returns data"
App -> Analytics "Logs slow query"
Analytics -> App "Sends alert (after threshold)"

// Alert arrives later, system adjusts

Are Cycles Bad?

In traditional software architecture, circular dependencies are considered bad. But in systems thinking, cycles are natural and valid.

Circular Dependency (Bad)

// Bad: Module A depends on B, B depends on A
ModuleA -> ModuleB "Calls"
ModuleB -> ModuleA "Calls"

// Problem: Impossible to initialize, tight coupling

Feedback Loop (Good)

// Good: System learns from output
User -> System "Submits data"
System -> User "Shows result"
User -> System "Adjusts based on feedback"

// Problem: Natural, enables adaptation

Key Differences

Exercise

Identify feedback loops in these scenarios:

1. Chat application: User sends message, app shows typing indicator, receiver sees it, receiver starts typing, sender sees typing indicator...

2. Recommendation system: User watches video, algorithm updates preferences, recommends more videos, user watches more, algorithm learns more...

3. CI/CD pipeline: Developer commits code, tests run, if fails developer fixes, commits again, tests run...

Key Takeaways

1. Feedback loops are cycles where output affects future input
2. They're everywhere: In nature, software, everyday life
3. Not errors: Unlike circular dependencies, feedback loops are valid patterns
4. Enable adaptation: Systems can self-regulate and improve
5. Two main types: Positive (reinforcing) and negative (balancing)

Next Lesson

In Lesson 2, you'll learn about different types of feedback loops and when to use each.

Lesson 2: Types of Feedback Loops

Learning Goals

• Understand positive, negative, and balancing feedback loops
• Learn when to use each type
• Recognize feedback loop behavior in systems

Feedback Loop Classification

Feedback Loops
├── Positive (Reinforcing)
│   ├── Virtuous cycle (good)
│   └── Vicious cycle (bad)
└── Negative (Balancing)
    ├── Self-regulating
    ├── Error-correcting
    └── Stabilizing

Positive Feedback Loops (Reinforcing)

Amplify change, leading to exponential growth or collapse.

Pattern 1: Virtuous Cycle (Growth)

VirtuousCycle = scenario "Network Effects" {
  UserA -> App "Joins platform"
  App -> UserB "Invites friend"
  UserB -> App "Joins platform"
  App -> UserC "Invites friend"

  // More users → More value → More users
  App -> Users "Platform value increases"
  Users -> App "More users join"
}

Use when: Viral growth, network effects, learning systems

Examples:

• Social networks (more users = more connections)
• Marketplaces (more sellers = more buyers)
• Machine learning (more data = better predictions)

Pattern 2: Vicious Cycle (Collapse)

ViciousCycle = scenario "Performance Degradation" {
  User -> App "Makes request"
  App -> Database "Query"

  // Slow query → Queue builds → Slower queries
  Database -> App "Slow response"
  App -> Queue "Requests back up"
  Queue -> Database "More load"
  Database -> App "Even slower response"

  // If not interrupted, system collapses
}

Use when: Identifying failure modes, designing circuit breakers

Examples:

• System overload
• Cache stampede
• Database deadlock cascade

Pattern 3: Learning Loop (Improvement)

LearningLoop = scenario "ML Model Improvement" {
  User -> Model "Makes prediction"
  Model -> User "Shows result"
  User -> Model "Rates accuracy"

  // Better data → Better model → Better predictions
  Model -> Training "Updates with rating"
  Training -> Model "Improved model"
  Model -> User "Better predictions"
}

Use when: Machine learning, recommendation systems, A/B testing

Examples:

• Search engine relevance
• Ad targeting
• Personalized recommendations

Negative Feedback Loops (Balancing)

Counteract change, maintaining stability and equilibrium.

Pattern 1: Self-Regulating (Homeostasis)

Homeostasis = scenario "Auto-Scaling" {
  Monitoring -> App "Detects high load"
  App -> ScalingService "Request scale up"
  ScalingService -> App "Adds instances"
  App -> Monitoring "Reports lower load"

  // System self-regulates to target load
  Monitoring -> App "Detects low load"
  App -> ScalingService "Request scale down"
  ScalingService -> App "Removes instances"
}

Use when: Auto-scaling, resource management, capacity planning

Examples:

• Server auto-scaling
• Database connection pooling
• Rate limiting

Pattern 2: Error-Correcting (Resilience)

ErrorCorrection = scenario "Retry with Backoff" {
  App -> Service "Make request"
  Service -> App "Failure"

  // Exponential backoff
  App -> Service "Retry after 1s"
  Service -> App "Failure"
  App -> Service "Retry after 2s"
  Service -> App "Failure"
  App -> Service "Retry after 4s"
  Service -> App "Success"

  // System recovers from transient errors
}

Use when: Error handling, resilience, fault tolerance

Examples:

• Retry logic
• Circuit breakers
• Fallback mechanisms

Pattern 3: Stabilizing (Control)

Stabilizing = scenario "Rate Limiting" {
  User -> API "Send request"
  API -> RateLimiter "Check rate"

  // If under limit, allow
  RateLimiter -> API "Under limit"
  API -> User "Process request"

  // If over limit, throttle
  API -> RateLimiter "Check rate"
  RateLimiter -> API "Over limit"
  API -> User "Rate limit exceeded"

  // System stabilizes request rate
}

Use when: Traffic control, resource allocation, load balancing

Examples:

• API rate limiting
• Load balancers
• Queue management

Comparing Feedback Loops

Delayed Feedback

Feedback occurs after a delay, can cause oscillation.

DelayedFeedback = scenario "Delayed Monitoring" {
  App -> System "Request processed"

  // Delay before feedback
  System -> Analytics "Log event"
  Analytics -> Monitoring "Aggregate metrics"
  Monitoring -> App "Send alert (5 min delay)"

  // By the time alert arrives, system may have changed
}

Mitigation:

• Use real-time monitoring
• Reduce delays
• Add hysteresis (threshold buffer)

Feedback Loop Behaviors

Convergent

System reaches a stable state:

Convergent = scenario "Converging to Equilibrium" {
  // System oscillates but stabilizes
  App -> Cache "Check cache"
  Cache -> App "Miss"
  App -> Database "Query"
  Database -> App "Data"
  App -> Cache "Store"

  // Next time: Cache hit (faster, stabilizes)
  App -> Cache "Check cache"
  Cache -> App "Hit (stable)"
}

Divergent

System grows without bound or collapses:

Divergent = scenario "Exponential Growth" {
  User -> App "Invite friend"
  App -> Friend "Invitation"
  Friend -> App "Accept and invite"
  App -> Friend2 "Invitation"
  Friend2 -> App "Accept and invite"

  // Without limits, grows exponentially
}

Oscillating

System cycles between states:

Oscillating = scenario "Hysteresis Loop" {
  Monitor -> App "Load high"
  App -> Scaling "Scale up"
  App -> Monitor "Load normal"

  Monitor -> App "Load low"
  App -> Scaling "Scale down"
  App -> Monitor "Load high"

  // Oscillates between scale up/down
}

Designing Feedback Loops

Step 1: Identify the Feedback

What creates the feedback?

// What output becomes input?
User -> App "Action"
App -> User "Response"
// User's response becomes next action's input

Step 2: Determine the Type

Is it reinforcing or balancing?

// Reinforcing: Increases effect
App -> ML "More data"
ML -> App "Better model"

// Balancing: Maintains equilibrium
App -> Monitor "Check load"
Monitor -> App "Adjust capacity"

Step 3: Add Controls

Prevent runaway behavior:

AutoScaling = container "Auto-Scaling Service" {
  scale {
    min 2
    max 10
    metric "cpu > 80%"
  }
}

Step 4: Monitor

Observe behavior:

Monitor = system "Monitoring System" {
  metrics {
    cpu_usage
    request_rate
    error_rate
    feedback_loop_iterations
  }
}

Exercise

Classify these feedback loops:

1. "More users join platform → More content → More users join..."
2. "System detects high load → Scales up → Load decreases → Scales down..."
3. "User likes video → Algorithm shows similar videos → User likes more → Algorithm learns..."
4. "Request fails → Retry with backoff → Eventually succeeds..."

Key Takeaways

1. Positive loops: Reinforce change (growth or collapse)
2. Negative loops: Maintain stability (balance and regulate)
3. Delayed feedback: Can cause oscillation, needs monitoring
4. Design intentionally: Add controls to prevent runaway behavior
5. Monitor behavior: Ensure loops behave as expected

Next Lesson

In Lesson 3, you'll learn how to model feedback loops as valid cycles in Sruja.

Lesson 3: Modeling Cycles

Learning Goals

• Learn how to create valid cycles in Sruja
• Model feedback loops explicitly
• Differentiate cycles from circular dependencies

Cycles in Sruja

Unlike circular dependencies (bad), feedback loops (good) are valid cycles in Sruja.

Basic Cycle Syntax

// Valid feedback loop
User -> App.WebApp "Submits form"
App.WebApp -> App.API "Validates"
App.API -> App.WebApp "Returns result"
App.WebApp -> User "Shows feedback"

// User resubmits (cycle completes)

Modeling Feedback Loops

Example 1: User Feedback Loop

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

User = person "User"

App = system "Application" {
  WebApp = container "Web Application"
  API = container "API Service"
}

// User feedback cycle
UserFeedback = scenario "User Form Feedback" {
  User -> App.WebApp "Submit form"
  App.WebApp -> App.API "Validate input"
  App.API -> App.WebApp "Return validation result"

  // Error path (loop)
  if has_errors {
    App.WebApp -> User "Show errors"
    User -> App.WebApp "Correct and resubmit"
  }

  // Success path (end cycle)
  if no_errors {
    App.WebApp -> Database "Save data"
    App.WebApp -> User "Show success"
  }
}

Example 2: System Self-Regulation

AutoScaling = system "Auto-Scaling System" {
  Monitor = container "Monitoring Service"
  Scaling = container "Scaling Service"
}

App = system "Application" {
  API = container "API Service"
}

// Auto-scaling feedback loop
ScalingLoop = scenario "Auto-Scaling Feedback" {
  App.API -> AutoScaling.Monitor "Reports load"

  // Scale up if load is high
  if load_high {
    AutoScaling.Monitor -> AutoScaling.Scaling "Trigger scale up"
    AutoScaling.Scaling -> App.API "Add instances"
    App.API -> AutoScaling.Monitor "Reports new load"
    // Loop continues until load normalizes
  }

  // Scale down if load is low
  if load_low {
    AutoScaling.Monitor -> AutoScaling.Scaling "Trigger scale down"
    AutoScaling.Scaling -> App.API "Remove instances"
    App.API -> AutoScaling.Monitor "Reports new load"
    // Loop continues until load normalizes
  }
}

Example 3: Inventory Management

Admin = person "Administrator"

Shop = system "Shop" {
  API = container "API Service"
  Inventory = database "Inventory Database"
}

// Inventory feedback loop
InventoryLoop = scenario "Inventory Feedback" {
  Shop.API -> Shop.Inventory "Update stock"

  // Low stock alert
  if stock_low {
    Shop.Inventory -> Shop.API "Notify low stock"
    Shop.API -> Admin "Send restock alert"
    Admin -> Shop.API "Restock inventory"
    Shop.API -> Shop.Inventory "Update stock"
    // Inventory updates, loop may repeat
  }

  // Normal stock (no action needed)
  if stock_normal {
    Shop.Inventory -> Shop.API "Stock OK"
  }
}

Example 4: Learning System

User = person "User"

MLSystem = system "ML Recommendation System" {
  API = container "Recommendation API"
  Model = database "ML Model"
  Training = container "Training Pipeline"
}

// Learning feedback loop
LearningLoop = scenario "ML Learning Cycle" {
  User -> MLSystem.API "Request recommendations"
  MLSystem.API -> MLSystem.Model "Get predictions"
  MLSystem.Model -> MLSystem.API "Return recommendations"
  MLSystem.API -> User "Show recommendations"

  // User feedback
  User -> MLSystem.API "Rate recommendations"

  // Model update
  MLSystem.API -> MLSystem.Training "Add training data"
  MLSystem.Training -> MLSystem.Model "Update model"

  // Improved recommendations next time
  MLSystem.Model -> MLSystem.API "Better predictions"
  MLSystem.API -> User "Show improved recommendations"
}

Explicit vs Implicit Cycles

Explicit Cycle (Clear Feedback)

// Shows the complete feedback path
User -> App "Submit data"
App -> User "Show result"
User -> App "Adjust and resubmit"

// Clearly shows learning/adaptation

Implicit Cycle (Inferred)

// Relationships imply the cycle exists
User -> App "Uses"
App -> User "Responds"

// Cycle is there but not explicitly modeled

Recommendation: Use explicit cycles for important feedback mechanisms.

Valid Cycles vs Circular Dependencies

Circular Dependency (Bad)

// Static compile-time dependency
ModuleA -> ModuleB "Imports"
ModuleB -> ModuleA "Imports"

// Problems:
// - Impossible to initialize
// - Tight coupling
// - No clear purpose

Feedback Loop (Good)

// Dynamic runtime feedback
User -> App "Submits data"
App -> User "Shows result"

// Benefits:
// - Enables adaptation
// - Clear purpose
// - Loose coupling (eventual consistency)

Feedback Loop Patterns

Pattern 1: Immediate Feedback

InstantFeedback = scenario "Form Validation" {
  User -> WebApp "Type in field"
  WebApp -> API "Validate"
  API -> WebApp "Result (instant)"
  WebApp -> User "Show error/success"
}

Pattern 2: Delayed Feedback

DelayedFeedback = scenario "Performance Monitoring" {
  App -> Monitoring "Log metrics"

  // Time passes

  Monitoring -> App "Send alert (after threshold)"
  App -> Admin "Notify"
  Admin -> App "Adjust configuration"
  App -> Monitoring "Log new metrics"
}

Pattern 3: Aggregated Feedback

AggregatedFeedback = scenario "A/B Testing" {
  Users -> App "Use feature A"

  // Aggregate many interactions
  App -> Analytics "Log events"
  Analytics -> Dashboard "Show aggregated results"

  Team -> App "Make decision based on data"
  App -> Users "Roll out winner to all"
}

Feedback Loop Controls

Prevent Runaway Behavior

AutoScaling = container "Auto-Scaling Service" {
  scale {
    min 2
    max 10
    metric "cpu > 80%"
    cooldown "5 minutes"  // Prevent rapid scaling
  }
}

Circuit Breaker Pattern

CircuitBreaker = scenario "Circuit Breaker Feedback" {
  App -> Service "Make request"

  // If failures exceed threshold, open circuit
  if failures > threshold {
    App -> Fallback "Use fallback"
    Fallback -> App "Return cached data"

    // After cooldown, try again
    if cooldown_elapsed {
      App -> Service "Make request"
      Service -> App "Success (close circuit)"
    }
  }
}

Rate Limiting

RateLimited = scenario "Rate Limited Requests" {
  User -> API "Send request"

  // Check rate limit
  API -> RateLimiter "Check limit"

  if under_limit {
    RateLimiter -> API "Allow"
    API -> User "Process request"
  }

  if over_limit {
    RateLimiter -> API "Throttle"
    API -> User "Rate limit exceeded"

    // User waits and retries (feedback loop)
    User -> API "Retry after delay"
  }
}

Documenting Feedback Loops

Add Metadata

AutoScaling = system "Auto-Scaling" {
  metadata {
    feedback_loop {
      type "negative_balancing"
      purpose "Maintain target CPU usage"
      target "70% CPU"
      controls "min/max instance limits"
      monitoring "CPU, latency, error rate"
    }
  }
}

Complete Example: E-Commerce Feedback Loops

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

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

Shop = system "Shop" {
  WebApp = container "Web Application"
  API = container "API Service"
  Database = database "Database"
  Cache = database "Redis Cache"
}

// User feedback loop (interactive)
UserFeedback = scenario "Checkout Feedback" {
  Customer -> Shop.WebApp "Submit order"
  Shop.WebApp -> Shop.API "Process order"

  // Payment feedback
  Shop.API -> PaymentGateway "Process payment"
  PaymentGateway -> Shop.API "Payment result"

  if payment_failed {
    Shop.API -> Shop.WebApp "Return error"
    Shop.WebApp -> Customer "Show error, retry"
    Customer -> Shop.WebApp "Try again"  // Loop
  }

  if payment_success {
    Shop.API -> Shop.Database "Save order"
    Shop.API -> Shop.WebApp "Success"
    Shop.WebApp -> Customer "Show confirmation"
  }
}

// Inventory feedback loop (self-regulating)
InventoryFeedback = scenario "Inventory Feedback" {
  Shop.API -> Shop.Database "Update inventory"

  if stock_low {
    Shop.Database -> Shop.API "Notify low stock"
    Shop.API -> Admin "Send alert"
    Admin -> Shop.API "Restock"
    Shop.API -> Shop.Database "Update inventory"
  }
}

// Cache feedback loop (learning)
CacheFeedback = scenario "Cache Learning" {
  Shop.API -> Shop.Cache "Query cache"

  if cache_hit {
    Shop.Cache -> Shop.API "Return data (fast)"
  }

  if cache_miss {
    Shop.API -> Shop.Database "Query database"
    Shop.Database -> Shop.API "Return data"
    Shop.API -> Shop.Cache "Store in cache"
    // Next request will be a cache hit
  }
}

view index {
  include *
}

Exercise

Model feedback loops for:

1. Chat application: User types, app shows "typing indicator", receiver sees it, receiver types, sender sees "typing indicator"...

2. Review system: User rates product, system updates average rating, displays to next users...

3. Load balancing: Server gets overloaded, balancer sends traffic to other servers, load redistributes...

Key Takeaways

1. Cycles are valid in Sruja: Feedback loops are not errors
2. Explicit cycles: Model important feedback mechanisms
3. Differentiate: Circular dependencies (bad) vs feedback loops (good)
4. Add controls: Prevent runaway behavior with limits
5. Document clearly: Use metadata to explain feedback loops

Module 5 Complete

You've completed Feedback Loops! You now understand:

• What feedback loops are and why they matter
• Types of feedback loops (positive, negative, delayed)
• How to model cycles in Sruja

Next: Learn about Module 6: Context.

Module 6: Context

Overview

In this module, you'll learn to capture the environment your system operates in - stakeholders, dependencies, constraints, and success criteria.

Learning Objectives

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

• Identify and document stakeholders
• Model external dependencies and integrations
• Define constraints and non-functional requirements
• Capture success criteria and SLOs

Lessons

• Lesson 1: Understanding Context - What context is and why it matters
• Lesson 2: Stakeholders - Modeling users, teams, and organizations
• Lesson 3: Dependencies and Constraints - Documenting what your system depends on

Prerequisites

• Completed Module 5: Feedback Loops

Time Investment

Approximately 1-1.5 hours to complete all lessons and exercises.

Course Completion

After completing this module, you'll have finished Systems Thinking 101!

Next Steps

After completing this course:

• Try the System Design 101 course
• Explore the Systems Thinking tutorial
• Review the Beginner path

Lesson 1: Understanding Context

Learning Goals

• Understand what context is in systems thinking
• Recognize the different layers of context
• Learn why context matters for architecture

What Is Context?

Context is the environment your system operates in. It includes everything that affects or is affected by your system, even if it's not part of the system itself.

┌─────────────────────────────────────────────┐
│              ORGANIZATIONAL CONTEXT          │
│  Company culture, processes, constraints    │
│                                             │
│   ┌─────────────────────────────────────┐   │
│   │       TECHNICAL CONTEXT            │   │
│   │  Dependencies, infrastructure, APIs  │   │
│   │                                   │   │
│   │  ┌─────────────────────────────┐  │   │
│   │  │    STAKEHOLDER CONTEXT     │  │   │
│   │  │  Users, teams, customers   │  │   │
│   │  │                           │  │   │
│   │  │  ┌───────────────────────┐ │  │   │
│   │  │  │   YOUR SYSTEM         │ │  │   │
│   │  │  └───────────────────────┘ │  │   │
│   │  └─────────────────────────────┘  │   │
│   └─────────────────────────────────────┘   │
└─────────────────────────────────────────────┘

Layers of Context

1. Stakeholder Context

Who cares about your system?

// People who use or influence the system
Customer = person "Customer"
Administrator = person "Administrator"
SupportTeam = person "Support Team"
BusinessOwner = person "Business Owner"

2. Technical Context

What technical dependencies exist?

// External systems and services
PaymentGateway = system "Payment Gateway"
EmailService = system "Email Service"
Analytics = system "Analytics Platform"
CDN = system "Content Delivery Network"

3. Organizational Context

What organizational factors affect the system?

// Documented in metadata
Shop = system "Shop" {
  metadata {
    team ["platform-team"]
    business_unit ["e-commerce"]
    compliance ["PCI-DSS"]
    cost_center ["engineering"]
  }
}

Why Context Matters

1. Stakeholder Alignment

Understand who your system serves:

// Different stakeholders have different needs
Customer -> Shop "Wants fast checkout"
Administrator -> Shop "Wants easy management"
BusinessOwner -> Shop "Wants high conversion"
ComplianceOfficer -> Shop "Wants data security"

2. Dependency Management

Know what you depend on:

Shop = system "Shop"

// Explicit dependencies
Shop -> PaymentGateway "Depends on for payments"
Shop -> EmailService "Depends on for notifications"
Shop -> Analytics "Depends on for tracking"

// If any dependency fails, what's the impact?

3. Constraint Awareness

Understand limitations:

Shop = system "Shop" {
  metadata {
    constraints {
      "PCI-DSS compliance required",
      "Maximum response time: 2s",
      "Budget: $500/month infrastructure",
      "Team size: 3 engineers"
    }
  }
}

4. Success Criteria

Define what success looks like:

Shop = system "Shop" {
  slo {
    availability {
      target "99.9%"
    }
    latency {
      p95 "200ms"
    }
  }

  metadata {
    success_criteria {
      "Support 10k concurrent users",
      "Less than 1% abandoned carts",
      "Checkout completion rate > 80%"
    }
  }
}

Context in Sruja

Using overview Block

overview {
  summary "E-commerce platform for online retail"
  audience "Customers, administrators, business owners"
  scope "Shopping cart, checkout, order management"
  goals [
    "Fast and reliable checkout",
    "Easy order management",
    "Real-time inventory tracking"
  ]
  non_goals [
    "Social features",
    "Mobile app (web-only)"
  ]
  risks [
    "Payment gateway downtime",
    "Database scaling limits"
  ]
}

Using person for Stakeholders

// Different types of stakeholders
Customer = person "Customer"
Administrator = person "Administrator"
SupportAgent = person "Support Agent"
ProductManager = person "Product Manager"
ComplianceOfficer = person "Compliance Officer"

Using system for External Dependencies

// Document external services
PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external", "critical"]
    sla "99.9% uptime"
  }
}

EmailService = system "Email Service" {
  metadata {
    tags ["external"]
    priority "low"  // Email can be delayed
  }
}

Using requirements

// Capture constraints and requirements
R1 = requirement functional "Must support multiple payment methods"
R2 = requirement constraint "Must be PCI-DSS compliant"
R3 = requirement performance "Page load time < 2 seconds"
R4 = requirement security "All data encrypted at rest"

Context Examples

Example 1: E-Commerce Platform

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

// Stakeholder context
Customer = person "Customer"
Administrator = person "Administrator"
BusinessOwner = person "Business Owner"
SupportTeam = person "Support Team"

// System
Shop = system "Shop"

// Technical context (dependencies)
PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external", "critical", "pci-compliant"]
  }
}

EmailService = system "Email Service" {
  metadata {
    tags ["external", "low-priority"]
  }
}

AnalyticsService = system "Analytics Service" {
  metadata {
    tags ["external"]
  }
}

// Relationships show dependencies
Shop -> PaymentGateway "Depends on for payments"
Shop -> EmailService "Depends on for notifications"
Shop -> AnalyticsService "Depends on for tracking"

Customer -> Shop "Wants fast, reliable shopping"
Administrator -> Shop "Wants easy management"
BusinessOwner -> Shop "Wants high revenue"
SupportTeam -> Shop "Wants clear error messages"

view index {
  include *
}

Example 2: Internal Tool

// Stakeholder context (internal only)
Developer = person "Developer"
QAEngineer = person "QA Engineer"
DevOpsEngineer = person "DevOps Engineer"

// System
DeploymentTool = system "Deployment Tool"

// Technical context
GitHub = system "GitHub" {
  metadata {
    tags ["external"]
  }
}

AWS = system "Amazon Web Services" {
  metadata {
    tags ["external", "infrastructure"]
  }
}

Slack = system "Slack" {
  metadata {
    tags ["external", "communication"]
  }
}

// Dependencies
DeploymentTool -> GitHub "Fetches code"
DeploymentTool -> AWS "Deploys to AWS"
DeploymentTool -> Slack "Sends notifications"

// Context shows different stakeholders have different needs
Developer -> DeploymentTool "Wants simple interface"
QAEngineer -> DeploymentTool "Wants detailed logs"
DevOpsEngineer -> DeploymentTool "Wants monitoring & alerts"

Context Anti-Patterns

Anti-Pattern 1: No Context

// Bad: System in isolation
Shop = system "Shop" {
  WebApp = container "Web App"
  API = container "API"
}

Solution: Add stakeholders and dependencies.

Anti-Pattern 2: Too Much Context

// Bad: Everything is context, system is lost
Customer = person "Customer"
Manager = person "Manager"
Support = person "Support"
Finance = person "Finance"
Legal = person "Legal"
HR = person "HR"
Marketing = person "Marketing"
// ... 20 more stakeholders

Solution: Focus on key stakeholders directly affected.

Anti-Pattern 3: Wrong Level of Context

// Bad: Too detailed (implementation, not context)
Shop = system "Shop"
PostgreSQL = system "PostgreSQL"
Redis = system "Redis"
Nginx = system "Nginx"

Solution: Group into higher-level services.

Exercise

Identify the context layers for a hotel booking system:

Requirements: "A hotel booking system allows guests to search rooms, make reservations, and manage bookings. Hotel staff can manage room inventory and view reports. The system integrates with a payment gateway for payments and sends SMS confirmations. Hotel management needs reporting on occupancy and revenue."

Identify:

1. Stakeholders: _
2. External dependencies: _
3. Organizational constraints: _

Key Takeaways

1. Context is the environment: Everything affecting or affected by your system
2. Multiple layers: Stakeholder, technical, organizational
3. Use Sruja features: overview, person, system, requirements
4. Balance detail: Don't ignore context, don't overwhelm
5. Context matters: Affects design, decisions, and success

Next Lesson

In Lesson 2, you'll learn how to model stakeholders and their relationships to your system.

Lesson 2: Stakeholders

Learning Goals

• Identify key stakeholders for your system
• Model different stakeholder types
• Document stakeholder needs and concerns

Who Are Stakeholders?

Stakeholders are people or groups who are affected by or can affect your system. They include users, customers, team members, and anyone else with an interest in the system.

Stakeholder Categories

1. Primary Users

Direct users of the system:

Customer = person "Customer" {
  description "End users who purchase products"
  metadata {
    needs ["Fast checkout", "Easy product search", "Order tracking"]
    pain_points ["Complex checkout", "Slow search results"]
  }
}

Administrator = person "Administrator" {
  description "Manages products, orders, and users"
  metadata {
    needs ["Dashboard", "Bulk operations", "Reporting"]
  }
}

2. Secondary Users

Users who use the system indirectly:

SupportAgent = person "Support Agent" {
  description "Helps customers with orders"
  metadata {
    needs ["Order history", "Customer lookup", "Quick access"]
  }
}

3. Business Stakeholders

Decision-makers and business owners:

ProductManager = person "Product Manager" {
  description "Owns product strategy"
  metadata {
    needs ["Analytics", "User feedback", "Feature usage"]
  }
}

BusinessOwner = person "Business Owner" {
  description "Responsible for revenue and profit"
  metadata {
    needs ["Sales reports", "Conversion metrics", "ROI data"]
  }
}

4. Technical Stakeholders

People who build and maintain the system:

Developer = person "Developer" {
  description "Builds and maintains the system"
  metadata {
    needs ["API documentation", "Clear architecture", "Debugging tools"]
  }
}

DevOpsEngineer = person "DevOps Engineer" {
  description "Deploys and operates the system"
  metadata {
    needs ["Monitoring", "Logs", "Health checks"]
  }
}

5. Compliance & Governance

People ensuring rules are followed:

ComplianceOfficer = person "Compliance Officer" {
  description "Ensures regulatory compliance"
  metadata {
    needs ["Audit logs", "Data privacy controls", "Access logs"]
  }
}

SecurityAuditor = person "Security Auditor" {
  description "Reviews security posture"
  metadata {
    needs ["Security reports", "Vulnerability assessments", "Penetration test results"]
  }
}

Modeling Stakeholders in Sruja

Basic Stakeholder

Customer = person "Customer"

With Details

Customer = person "Customer" {
  description "End users who purchase products"
  metadata {
    tags ["primary-user", "external"]
    priority "high"
    needs [
      "Fast and easy checkout",
      "Product search and filtering",
      "Order tracking"
    ]
    pain_points [
      "Complex forms",
      "Slow page loads",
      "Lack of mobile support"
    ]
  }
}

With Relationships

Customer = person "Customer"
Shop = system "Shop"

// Customer relationship shows interaction
Customer -> Shop "Purchases products"
Shop -> Customer "Sends order updates"

Stakeholder Interactions

Example: E-Commerce Platform

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

// Stakeholders
Customer = person "Customer"
Administrator = person "Administrator"
SupportAgent = person "Support Agent"
ProductManager = person "Product Manager"
BusinessOwner = person "Business Owner"

// System
Shop = system "Shop" {
  WebApp = container "Web Application"
  API = container "API Service"
  Database = database "Database"
}

// Stakeholder interactions
Customer -> Shop.WebApp "Browses products"
Customer -> Shop.WebApp "Purchases products"
Customer -> Shop.WebApp "Tracks orders"

Administrator -> Shop.WebApp "Manages products"
Administrator -> Shop.WebApp "Views reports"

SupportAgent -> Shop.WebApp "Assists customers"
SupportAgent -> Shop.WebApp "Views order history"

ProductManager -> Shop.WebApp "Reviews analytics"
ProductManager -> Shop.WebApp "Monitors user behavior"

BusinessOwner -> Shop.WebApp "Views revenue reports"
BusinessOwner -> Shop.WebApp "Monitors KPIs"

view index {
  include *
}

Stakeholder Matrix

Prioritizing Stakeholders

MoSCoW Method

// Must Have (Critical)
Customer = person "Customer"

// Should Have (Important)
Administrator = person "Administrator"

// Could Have (Nice to have)
ProductManager = person "Product Manager"

// Won't Have (Out of scope)
MarketingAnalyst = person "Marketing Analyst"

RICE Scoring (for Features)

// High impact, low effort
Customer = person "Customer" {
  metadata {
    rice_score {
      reach "10000 users"
      impact "High"
      confidence "80%"
      effort "2 weeks"
    }
  }
}

Stakeholder Personas

Creating Personas

// Persona 1: Primary user
Sarah = person "Sarah (Customer)" {
  description "Busy professional, 35, shops on mobile"
  metadata {
    goals ["Fast checkout", "Mobile-friendly", "Easy returns"]
    frustrations ["Complex forms", "Slow loading"]
    context ["Shops during commute", "Uses iPhone"]
  }
}

// Persona 2: Secondary user
John = person "John (Administrator)" {
  description "Operations manager, 45, manages inventory"
  metadata {
    goals ["Quick updates", "Bulk operations", "Real-time data"]
    frustrations ["Slow interface", "Lack of filters"]
    context ["Desktop user", "Excel background"]
  }
}

Stakeholder-System Relationships

Direct Users

// Interact directly with the system
Customer -> Shop.WebApp "Uses"
Administrator -> Shop.WebApp "Manages"

Indirect Users

// System serves their needs without direct interaction
BusinessOwner -> Shop "Reviews revenue"
// Business owner doesn't use the app directly

External Stakeholders

// Affected by system but don't use it
ComplianceOfficer = person "Compliance Officer"
ComplianceOfficer -> Shop "Reviews audit logs"

Documenting Stakeholder Needs

Using Requirements

// Customer needs
R1 = requirement functional "Guest checkout available"
R2 = requirement performance "Page load < 2s"

// Administrator needs
R3 = requirement functional "Bulk product upload"
R4 = requirement usability "Intuitive dashboard"

// Business owner needs
R5 = requirement reporting "Daily revenue reports"
R6 = requirement analytics "Conversion funnel tracking"

Using SLOs

Shop = system "Shop" {
  slo {
    availability {
      target "99.9%"
    }
    latency {
      p95 "200ms"
      p99 "500ms"
    }
    errorRate {
      target "0.1%"
    }
  }
}

Exercise

Identify stakeholders for a hospital appointment scheduling system:

"The system allows patients to book appointments, doctors to view their schedules, and receptionists to manage appointments. Hospital administrators need reporting on utilization. The system integrates with insurance APIs and sends SMS reminders."

Identify:

1. Primary stakeholders: _
2. Secondary stakeholders: _
3. Business stakeholders: _
4. Technical stakeholders: _

For each, document:

• Their role
• What they need from the system
• Any concerns or pain points

Key Takeaways

1. Identify all stakeholders: Users, business, technical, compliance
2. Categorize them: Primary, secondary, business, technical
3. Document needs: Goals, frustrations, context
4. Prioritize: Focus on most important stakeholders
5. Model relationships: Show how stakeholders interact with the system
6. Use personas: Create detailed user profiles

Next Lesson

In Lesson 3, you'll learn how to document dependencies, constraints, and success criteria.

Lesson 3: Dependencies and Constraints

Learning Goals

• Identify and document external dependencies
• Define constraints and limitations
• Capture success criteria and SLOs
• Use Sruja features to model context

External Dependencies

What Are Dependencies?

Dependencies are external systems, services, or resources your system relies on to function.

// Your system
Shop = system "Shop"

// External dependencies
PaymentGateway = system "Payment Gateway"
EmailService = system "Email Service"
AnalyticsService = system "Analytics Service"
CDN = system "Content Delivery Network"

Categorizing Dependencies

Critical Dependencies

System cannot function without:

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external", "critical", "pci-compliant"]
    sla "99.9% uptime"
    impact "If down, checkout fails"
  }
}

Important Dependencies

System can function but degraded:

EmailService = system "Email Service" {
  metadata {
    tags ["external", "important"]
    sla "99.0% uptime"
    impact "If down, notifications delayed but system works"
  }
}

Optional Dependencies

System works fine without:

AnalyticsService = system "Analytics Service" {
  metadata {
    tags ["external", "optional"]
    sla "98.0% uptime"
    impact "If down, analytics lost but core functionality works"
  }
}

Documenting Dependencies

Using Metadata

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external", "vendor"]
    owner "Stripe Inc."
    sla "99.9% uptime"
    mttr "4 hours"
    contact "support@stripe.com"
    fallback "Manual payment processing"
    cost "$0.30 per transaction"
    compliance ["PCI-DSS Level 1"]
  }
}

Using Relationships

// Shows dependency
Shop.API -> PaymentGateway "Process payment" [critical]
Shop.API -> EmailService "Send notifications" [important]
Shop.API -> AnalyticsService "Track events" [optional]

Using Fallbacks

// Primary provider
PrimaryPayment = system "Primary Payment Gateway"
BackupPayment = system "Backup Payment Gateway"

Shop.API -> PrimaryPayment "Process payment" [primary]
Shop.API -> BackupPayment "Process payment" [fallback]

Constraints

What Are Constraints?

Constraints are limitations that affect your design and implementation choices.

Types of Constraints

Technical Constraints

Shop = system "Shop" {
  metadata {
    technical_constraints {
      "Must use PostgreSQL for transactions",
      "Must support 10k concurrent users",
      "Maximum API response time: 2s",
      "Must be deployable to AWS"
    }
  }
}

Business Constraints

Shop = system "Shop" {
  metadata {
    business_constraints {
      "Launch date: Q4 2024",
      "Budget: $500k/year infrastructure",
      "Team size: 3 engineers",
      "Must support multi-currency"
    }
  }
}

Compliance Constraints

Shop = system "Shop" {
  metadata {
    compliance_constraints {
      "PCI-DSS Level 1 for payments",
      "GDPR for EU customer data",
      "CCPA for California customers",
      "SOX compliance for financial reporting"
    }
  }
}

Security Constraints

Shop = system "Shop" {
  metadata {
    security_constraints {
      "All data encrypted at rest",
      "All API calls authenticated",
      "No PII in logs",
      "Minimum TLS 1.3"
    }
  }
}

Success Criteria

What Is Success?

Define what "good" looks like for your system.

Using overview Block

overview {
  summary "E-commerce platform for online retail"
  audience "Customers, administrators, business owners"

  goals [
    "Fast and reliable checkout",
    "Easy product discovery",
    "Real-time inventory tracking",
    "Scalable to 10k concurrent users"
  ]

  non_goals [
    "Social features",
    "Mobile app (web-only)",
    "Marketplace (first-party only)"
  ]

  success_criteria [
    "Checkout completion rate > 80%",
    "Average checkout time < 2 minutes",
    "Page load time < 2s",
    "Customer satisfaction > 4.5/5"
  ]
}

Using slo Block

Shop = system "Shop" {
  slo {
    availability {
      target "99.9%"
      window "30 days"
    }

    latency {
      p95 "200ms"
      p99 "500ms"
      window "7 days"
    }

    errorRate {
      target "0.1%"
      window "7 days"
    }

    throughput {
      target "10000 req/s"
      window "peak hour"
    }
  }
}

Complete Context Example

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

// OVERVIEW
overview {
  summary "E-commerce platform for online retail"
  audience "Customers, administrators, business owners"
  scope "Shopping, checkout, order management, inventory"
  goals [
    "Fast and reliable checkout",
    "Real-time inventory",
    "Scalable architecture"
  ]
  non_goals [
    "Social features",
    "Marketplace"
  ]
  risks [
    "Payment gateway downtime",
    "Database scaling limits",
    "High traffic surges"
  ]
}

// STAKEHOLDERS
Customer = person "Customer"
Administrator = person "Administrator"
BusinessOwner = person "Business Owner"
SupportAgent = person "Support Agent"

// SYSTEM
Shop = system "Shop" {
  metadata {
    team ["platform-team"]
    budget "$500k/year"
    launch_date "2024-12-01"
  }

  WebApp = container "Web Application"
  API = container "API Service"
  Database = database "PostgreSQL"
  Cache = database "Redis"

  // CONSTRAINTS
  constraints {
    "Must support 10k concurrent users",
    "Maximum response time: 2s",
    "PCI-DSS Level 1 compliance",
    "All data encrypted at rest"
  }

  // SUCCESS CRITERIA (SLOs)
  slo {
    availability {
      target "99.9%"
      window "30 days"
    }

    latency {
      p95 "200ms"
      p99 "500ms"
    }
  }
}

// DEPENDENCIES
PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external", "critical", "vendor"]
    owner "Stripe Inc."
    sla "99.9% uptime"
    mttr "4 hours"
    cost "$0.30/transaction"
    compliance ["PCI-DSS Level 1"]
  }
}

EmailService = system "Email Service" {
  metadata {
    tags ["external", "important", "vendor"]
    owner "SendGrid"
    sla "99.0% uptime"
    fallback "Queue for later"
  }
}

AnalyticsService = system "Analytics Service" {
  metadata {
    tags ["external", "optional", "vendor"]
    owner "Google"
    sla "98.0% uptime"
  }
}

// RELATIONSHIPS
Customer -> Shop.WebApp "Purchases products"
Administrator -> Shop.WebApp "Manages system"

Shop.API -> PaymentGateway "Process payment" [critical]
Shop.API -> EmailService "Send notifications" [important]
Shop.API -> AnalyticsService "Track events" [optional]

view index {
  include *
}

Requirements and Constraints

Using requirements

// Functional requirements
R1 = requirement functional "Must support multiple payment methods"
R2 = requirement functional "Guest checkout available"
R3 = requirement functional "Order tracking"

// Non-functional requirements
R4 = requirement performance "Page load time < 2s"
R5 = requirement availability "99.9% uptime"
R6 = requirement scalability "Support 10k concurrent users"

// Security requirements
R7 = requirement security "All data encrypted at rest"
R8 = requirement security "TLS 1.3 for all connections"

// Compliance requirements
R9 = requirement constraint "PCI-DSS Level 1"
R10 = requirement constraint "GDPR compliance for EU users"

Using constraints Block

constraints {
  "All APIs must use HTTPS",
  "Database must be encrypted at rest",
  "No PII in logs",
  "Maximum API response time: 2s",
  "Must support 99.9% uptime",
  "PCI-DSS compliance required"
}

Documenting Trade-offs

Decision Records (ADRs)

ADR001 = adr "Use PostgreSQL for primary database" {
  status "accepted"
  context "Need ACID transactions, strong consistency for orders"
  decision "Use PostgreSQL over MongoDB"
  consequences {
    benefits "Strong consistency, ACID transactions",
    tradeoffs "Scaling requires more effort than NoSQL"
  }
}

ADR002 = adr "Use Stripe for payments" {
  status "accepted"
  context "Need PCI-compliant payment processing"
  decision "Use Stripe over building in-house"
  consequences {
    benefits "PCI compliance, focus on core product",
    tradeoffs "Per-transaction fee, vendor lock-in"
  }
}

Exercise

Document context for a fitness tracking app:

"A fitness tracking app allows users to log workouts and view progress. Users can sync data from wearables. The app integrates with HealthKit and Google Fit. The app must work offline and sync when online. HIPAA compliance required for health data. Target 1 million users by year-end."

Document:

1. Stakeholders
2. External dependencies (with criticality)
3. Constraints (technical, business, compliance)
4. Success criteria (SLOs)

Key Takeaways

1. Document dependencies: External systems you rely on
2. Categorize by importance: Critical, important, optional
3. Define constraints: Limitations affecting design
4. Set success criteria: What "good" looks like
5. Capture trade-offs: ADRs for important decisions

Module 6 Complete

You've completed Context! You now understand:

• What context is and why it matters
• How to model stakeholders
• How to document dependencies and constraints

🎉 Course Complete!

You've finished Systems Thinking 101! You now understand:

• ✅ Fundamentals of systems thinking
• ✅ Parts and relationships
• ✅ Boundaries
• ✅ Flows
• ✅ Feedback loops
• ✅ Context

What's Next?

• Try the System Design 101 course
• Explore the Systems Thinking tutorial
• Review the Beginner path
• Build your own systems thinking architecture!

Congratulations on completing the course! 🚀

System Design 101

title: "System Design 101: Fundamentals" summary: "Master the art of designing scalable, reliable, and maintainable systems. From load balancers to caching strategies, learn the building blocks of modern architecture." weight: 1

System Design 101: Fundamentals

Note

Who is this for? Developers moving into senior roles, students preparing for interviews, or anyone curious about how massive systems like Netflix or Uber work.

Why Learn System Design?

Writing code is only half the battle. As you grow in your career, the challenges shift from "how do I write this function?" to "how do I ensure this system handles 10 million users?".

System design is the skill of defining the architecture, components, modules, interfaces, and data for a system to satisfy specified requirements. It's about making the right trade-offs.

What You Will Learn

By the end of this course, you will be able to:

1. Speak the Language: Confidently use terms like latency, throughput, consistency, and availability.
2. Use the Toolbox: Know when to use a relational database vs. NoSQL, or when to introduce a cache or message queue.
3. Draw the Blueprint: Visualise your ideas using industry-standard diagrams (C4 model).
4. Scale for Success: Understand how to take a system from 1 user to 1,000,000 users.

Course Structure

This course is broken down into digestible modules:

Module 1: Core Concepts

The foundational pillars of distributed systems. We cover Scalability (Vertical vs Horizontal), Reliability, and Maintainability.

Module 2: The Building Blocks

A deep dive into the components that make up a system:

• Load Balancers: The traffic cops of the internet.
• Databases: SQL vs NoSQL, replication, and sharding.
• Caches: speeding up access with Redis/Memcached.
• Message Queues: Decoupling services with Kafka/RabbitMQ.

Module 3: Architectural Patterns

How to organize code and services:

• Monolith vs Microservices
• Event-Driven Architecture
• API Gateway Pattern

Module 4: The Interview Guide

Practical tips for acing the system design interview, including a framework for tackling open-ended problems.

Prerequisites

• Basic understanding of how the web works (HTTP, DNS, Client-Server).
• Familiarity with at least one programming language.
• No prior distributed systems knowledge required.

Let's Begin

Start your journey with Module 1: Fundamentals.

Fundamentals

title: "Module 1: Fundamentals" weight: 0 summary: "Lay the groundwork. Learn the language of system design, how to dissect problems, and master the art of trade-offs."

Module 1: Fundamentals

Tip

The Interview Secret: Most candidates fail not because they don't know the tech, but because they dive into solutions too early. This module fixes that.

What's Inside?

This isn't just theory. It's the playbook for how senior engineers approach broad, ambiguous problems.

1. What is System Design?: Defining the game we're playing.
2. The Art of Requirements: How to extract the real problem from a vague prompt.
3. The C4 Model: A standardized way to draw your ideas so others actually understand them.
4. Trade-offs: Why "it depends" is the only correct answer (and how to explain what it depends on).
5. Sruja Basics: Your first architecture-as-code model.

Learning Goals

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

• ✅ Distinguish between Functional and Non-Functional Requirements.
• ✅ Calculate rough capacity estimates (back-of-the-envelope math).
• ✅ Draw a high-level System Context diagram.
• ✅ Explain the CAP theorem in plain English.

Ready?

Let's start your journey with Lesson 1: What is System Design?

title: "Lesson 1: The Mindset" weight: 1 summary: "Stop coding. Start designing. Why system design is different from application development." learning_objectives:

• Understand the difference between coding and system design
• Learn the 'House vs Skyscraper' analogy
• Master the Functional vs Non-Functional distinction estimated_time: "15 minutes" difficulty: "beginner"

Lesson 1: The Mindset

The Shift

When you write code, you are building a single room. You care about the furniture (variables), the flow (logic), and the usability (UI).

System Design is city planning.

You stop caring about the furniture in every room. Instead, you care about:

• Traffic flow: Can the roads handle rush hour? (Throughput)
• Utilities: Is there enough water and electricity? (Capacity)
• Disaster recovery: What happens if the power plant explodes? (Reliability)
• Expansion: Can we add a new suburb next year? (Scalability)

Important

The golden rule: In system design, there are no right answers, only trade-offs.

Functional vs Non-Functional

Every system has two sets of requirements. In an interview (and real life), 90% of your initial grade comes from clarifying these before you draw a single box.

1. Functional Requirements (The "What")

These are the features. If the system doesn't do this, it's useless.

• User can post a tweet.
• User can follow others.
• User sees a news feed.

2. Non-Functional Requirements (The "How")

These are the constraints. If the system doesn't meet these, it will crash/fail/be too slow.

• Scalability: Must handle 100M daily active users.
• Latency: Feed must load in < 200ms.
• Consistency: A tweet must appear on followers' feeds within 5 seconds.

graph TD
    A[Requirements] --> B[Functional]
    A --> C[Non-Functional]
    B --> B1[Features]
    B --> B2[APIs]
    B --> B3[User Flows]
    C --> C1[Scalability]
    C --> C2[Reliability]
    C --> C3[Latency]
    C --> C4[Cost]

    style A fill:#f9f,stroke:#333
    style B fill:#bbf,stroke:#333
    style C fill:#bfb,stroke:#333

The "It Depends" Game

Junior engineers search for the "best" database. Senior engineers ask "what are we optimizing for?"

Sruja Integration

In Sruja, we treat requirements as code. This keeps your constraints right next to your architecture.

Why Kinds and Types Matter

In Sruja, you declare kinds to establish the vocabulary of your architecture. This isn't just syntax—it provides real benefits:

1. Early Validation: If you typo an element type (e.g., sytem instead of system), Sruja catches it immediately.
2. Better Tooling: IDEs can provide autocomplete and validation based on your declared kinds.
3. Self-Documentation: Anyone reading your model knows exactly which element types are available.
4. Custom Vocabulary: You can define your own kinds (e.g., microservice = kind "Microservice") to match your domain.
5. Flat and Clean: With Sruja's flat syntax, these declarations live at the top of your file—no specification wrapper block required.

Example: Requirements-Driven Architecture

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

// 1. Defining the "What" (Functional)
requirement R1 functional "Users can post short text messages (tweets)"

// 2. Defining the "How" (Non-Functional)
requirement R2 performance "500ms p95 latency for reading timeline"
requirement R3 scale "Store 5 years of tweets (approx 1PB)"
requirement R4 availability "99.9% uptime SLA"

// 3. The Architecture follows the requirements
Twitter = system "The Platform" {
    description "Satisfies R1, R2, R3, R4"

    TimelineAPI = container "Timeline API" {
        technology "Rust"
        description "Satisfies R2 - optimized for low latency"

        slo {
            latency {
                p95 "500ms"
                window "7 days"
            }
            availability {
                target "99.9%"
                window "30 days"
            }
        }
    }

    TweetDB = database "Tweet Storage" {
        technology "Cassandra"
        description "Satisfies R3 - distributed storage for 1PB scale"
    }

    TimelineAPI -> TweetDB "Reads/Writes"
}

// 4. Document the decision
ADR001 = adr "Use Cassandra for tweet storage" {
    status "Accepted"
    context "Need to store 1PB of tweets with high write throughput"
    decision "Use Cassandra for distributed, scalable storage"
    consequences "Excellent scalability, eventual consistency trade-off"
}

view index {
title "Twitter Platform Overview"
include *
}

// Performance-focused view
view performance {
title "Performance View"
include Twitter.TimelineAPI Twitter.TweetDB
}

Knowledge Check

Next Steps

Now that we have the mindset, let's learn the language. 👉 Lesson 2: The Vocabulary of Scale

title: "Lesson 2: The Vocabulary of Scale" weight: 2 summary: "Vertical vs. Horizontal Scaling, Latency vs. Throughput. The words you need to know." learning_objectives:

• Explain Vertical vs Horizontal scaling
• Understand why distributed systems are hard
• Master the difference between Latency and Throughput estimated_time: "15 minutes" difficulty: "beginner"

Lesson 2: The Vocabulary of Scale

To design big systems, you need to speak the language.

1. Scaling: Up vs Out

When your website crashes because too many people are using it, you have two choices.

Vertical Scaling (Scaling Up)

"Get a bigger machine." You upgrade from a 4GB RAM server to a 64GB RAM server.

• Pros: Easy. No code changes.
• Cons: Expensive. Finite limit (you can't buy a 100TB RAM server... easily). Single point of failure.

Horizontal Scaling (Scaling Out)

"Get more machines." You buy 10 cheap servers and split the traffic between them.

• Pros: Infinite scale (google has millions of servers). Resilient (if one dies, others take over).
• Cons: Complex. You need load balancers and data consistency strategies.

graph TD
    subgraph Vertical [Vertical Scaling]
        Small[Server] -- Upgrade --> Big[SERVER]
    end

    subgraph Horizontal [Horizontal Scaling]
        One[Server] -- Add More --> Many1[Server]
        One -- Add More --> Many2[Server]
        One -- Add More --> Many3[Server]
    end

2. Speed: Latency vs Throughput

In interviews, never just say "it needs to be fast". Be specific.

• Latency: The time it takes for one person to get a result.
  • Metaphor: The time it takes to drive from A to B.
  • Unit: Milliseconds (ms).
• Throughput: The number of people the system can serve at the same time.
  • Metaphor: The width of the highway (how many cars per hour).
  • Unit: Requests per Second (RPS).

Tip

Use the right word: A system can have low latency (fast response) but low throughput (crashes if 5 people use it). A highway can have high throughput (10 lanes) but high latency (traffic jam).

3. Sruja in Action

Sruja allows you to define horizontal scaling requirements explicitly using the scale block.

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


ECommerce = system "E-Commerce System" {
    WebServer = container "Web App" {
        technology "Rust, Axum"

        // Explicitly defining Horizontal Scaling
        scale {
            min 3            // Start with 3 servers
            max 100          // Scale up to 100
            metric "cpu > 80%"
        }
    }

    Database = database "Primary DB" {
        technology "PostgreSQL"
        // Describing Vertical Scaling via comments/description
        description "Running on a massive AWS r5.24xlarge instance (Vertical Scaling)"
    }

    WebServer -> Database "Reads/Writes"
}

view index {
include *
}

Knowledge Check

Next Steps

We have the mindset, and we have the words. Now let's draw. 👉 Lesson 3: The C4 Model (Visualizing Architecture)

Lesson 3

title: "Lesson 3: Availability & Reliability" weight: 3 summary: "Redundancy, Failover, and SLAs."

Lesson 3: Availability & Reliability

Reliability vs. Availability

• Reliability: The probability that a system will function correctly without failure for a specified period. It's about correctness.
• Availability: The percentage of time a system is operational and accessible. It's about uptime.

A system can be available but not reliable (e.g., it returns 500 errors but is "up").

Measuring Availability

Availability is often measured in "nines":

Achieving High Availability

Redundancy

The key to availability is eliminating Single Points of Failure (SPOF). This is done via redundancy.

• Active-Passive: One server handles traffic; the other is on standby.
• Active-Active: Both servers handle traffic. If one fails, the other takes over the full load.

Failover

The process of switching to a redundant system upon failure. This can be manual or automatic.

🛠️ Sruja Perspective: Modeling Redundancy

You can explicitly model redundant components in Sruja to visualize your high-availability strategy.

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


Payments = system "Payment System" {
    PaymentService = container "Payment Service" {
        technology "Java"
    }

    // Modeling a primary and standby database
    PrimaryDB = database "Primary Database" {
        technology "MySQL"
        tags ["primary"]
    }

    StandbyDB = database "Standby Database" {
        technology "MySQL"
        tags ["standby"]
        description "Replicates from PrimaryDB. Promoted to primary if PrimaryDB fails."
    }

    PaymentService -> PrimaryDB "Reads/Writes"
    PrimaryDB -> StandbyDB "Replicates data"
}

view index {
include *
}

Lesson 4

title: "Lesson 4: CAP Theorem & Consistency" weight: 4 summary: "Consistency, Availability, and Partition Tolerance."

Lesson 4: CAP Theorem & Consistency

The CAP Theorem

Proposed by Eric Brewer, the CAP theorem states that a distributed data store can only provide two of the following three guarantees:

1. Consistency (C): Every read receives the most recent write or an error. All nodes see the same data at the same time.
2. Availability (A): Every request receives a (non-error) response, without the guarantee that it contains the most recent write.
3. Partition Tolerance (P): The system continues to operate despite an arbitrary number of messages being dropped or delayed by the network between nodes.

The Reality: P is Mandatory

In a distributed system, network partitions (P) are inevitable. Therefore, you must choose between Consistency (CP) and Availability (AP) when a partition occurs.

• CP (Consistency + Partition Tolerance): Wait for data to sync. If a node is unreachable, return an error. (e.g., Banking systems).
• AP (Availability + Partition Tolerance): Return the most recent version of data available, even if it might be stale. (e.g., Social media feeds).

Consistency Models

• Strong Consistency: Once a write is confirmed, all subsequent reads see that value.
• Eventual Consistency: If no new updates are made, eventually all accesses will return the last updated value. (Common in AP systems).

🛠️ Sruja Perspective: Documenting Guarantees

When defining data stores in Sruja, it is helpful to document their consistency guarantees, especially for distributed databases.

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


DataLayer = system "Data Layer" {
    UserDB = database "User Database" {
        technology "Cassandra"
        // Explicitly stating the consistency model
        description "configured with replication factor 3. Uses eventual consistency for high availability."

        // You could also use custom tags
        tags ["AP-System", "Eventual-Consistency"]
    }

    BillingDB = database "Billing Database" {
        technology "PostgreSQL"
        description "Single primary with synchronous replication to ensure strong consistency."
        tags ["CP-System", "Strong-Consistency"]
    }
}

view index {
include *
}

Lesson 5

title: "Lesson 5: User Scenarios" weight: 5 summary: "Modeling user flows and interactions."

Lesson 5: User Scenarios

Understanding User Journeys

A User Scenario describes the series of steps a user takes to achieve a specific goal within your system. While static architecture diagrams show structure, user scenarios show behavior.

Why Model Scenarios?

1. Validation: Ensures that all components required for a feature actually exist and are connected.
2. Clarity: Helps stakeholders understand how the system works from a user's perspective.
3. Testing: Serves as a blueprint for integration and end-to-end tests.

Example Scenario: Buying a Ticket

1. User searches for events.
2. User selects a ticket.
3. User enters payment details.
4. System processes payment.
5. System sends confirmation email.

🛠️ Sruja Perspective: Modeling Scenarios

Sruja provides a dedicated scenario keyword to model these interactions explicitly. This allows you to visualize the flow of data across your defined architecture.

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


R1 = requirement functional "User can buy a ticket"
R2 = requirement performance "Process payment in < 2s"

// Define the actors and systems first
User = person "Ticket Buyer"

TicketingApp = system "Ticketing Platform" {
    WebApp = container "Web Frontend"
    PaymentService = container "Payment Processor"
    EmailService = container "Notification Service"

    WebApp -> PaymentService "Process payment"
    PaymentService -> EmailService "Trigger confirmation"
}

// Define the scenario
BuyTicket = scenario "User purchases a concert ticket" {
    User -> TicketingApp.WebApp "Selects ticket"
    TicketingApp.WebApp -> TicketingApp.PaymentService "Process payment"
    TicketingApp.PaymentService -> TicketingApp.EmailService "Trigger confirmation"
    TicketingApp.EmailService -> User "Send email"
}

view index {
include *
}

By defining scenarios, you can automatically generate sequence diagrams or flowcharts that map directly to your code.

Building Blocks

Lesson 1

title: "Lesson 1: Load Balancers" weight: 1 summary: "L4 vs L7 Load Balancing, Algorithms."

Lesson 1: Load Balancers

What is a Load Balancer?

A load balancer sits between clients and servers, distributing incoming network traffic across a group of backend servers. This ensures that no single server bears too much load.

Types of Load Balancing

Layer 4 (Transport Layer)

• Decisions based on IP address and TCP/UDP ports.
• Faster, less CPU intensive.
• Does not inspect the content of the request.

Layer 7 (Application Layer)

• Decisions based on the content of the message (URL, HTTP headers, cookies).
• Can route traffic to different services based on URL (e.g., /images to image servers).
• More CPU intensive but smarter.

Algorithms

• Round Robin: Requests are distributed sequentially.
• Least Connections: Sends request to the server with the fewest active connections.
• IP Hash: The client's IP address is used to determine which server receives the request (useful for session stickiness).

🛠️ Sruja Perspective: Modeling Load Balancers

In Sruja, a load balancer is typically modeled as a container or component that sits in front of your application servers.

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


LB = container "Nginx Load Balancer" {
    technology "Nginx"
    tags ["load-balancer"]
    description "Layer 7 load balancer routing traffic based on URL paths."
}

AppServer = container "App Server" {
    technology "Python, Django"
    tags ["scaled"]
}

// Traffic flow
LB -> AppServer "Distributes requests (Round Robin)"

view index {
include *
}

Lesson 2

title: "Lesson 2: Databases" weight: 2 summary: "SQL vs NoSQL, Replication, and Sharding."

Lesson 2: Databases

SQL vs. NoSQL

SQL (Relational Databases)

• Structure: Structured data with predefined schemas (Tables, Rows, Columns).
• Query Language: SQL (Structured Query Language).
• ACID Compliance: Strong guarantees for Atomicity, Consistency, Isolation, Durability.
• Examples: MySQL, PostgreSQL, Oracle.
• Best for: Complex queries, financial transactions.

NoSQL (Non-Relational Databases)

• Structure: Flexible schemas (Key-Value, Document, Graph, Column-Family).
• Scalability: Designed for horizontal scaling.
• Examples: MongoDB (Document), Redis (Key-Value), Cassandra (Column).
• Best for: Rapidly changing data, massive scale, unstructured data.

Scaling Databases

Replication

Copying data to multiple servers.

• Master-Slave: Writes go to Master, Reads go to Slaves. Good for read-heavy systems.
• Master-Master: Writes can go to any node. Complex conflict resolution needed.

Sharding

Partitioning data across multiple servers (e.g., Users A-M on Server 1, N-Z on Server 2).

• Pros: Handles massive data volumes.
• Cons: Complex joins, rebalancing data is hard.

🛠️ Sruja Perspective: Modeling Databases

Sruja allows you to define the type of database and its role in the system.

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


UserDB = container "User Database" {
    technology "PostgreSQL"
    tags ["relational", "primary"]
    description "Stores user profiles and authentication data."
}

SessionStore = container "Session Cache" {
    technology "Redis"
    tags ["key-value", "cache"]
    description "Stores active user sessions for fast access."
}

view index {
include *
}

Lesson 3

title: "Lesson 3: Caching" weight: 3 summary: "Caching strategies and eviction policies."

Lesson 3: Caching

Why Cache?

Caching is the process of storing copies of data in a temporary storage location (cache) so that future requests for that data can be served faster.

• Reduce Latency: Memory is faster than disk.
• Reduce Load: Fewer queries to the database.

Caching Strategies

Cache-Aside (Lazy Loading)

1. App checks cache.
2. If miss, App reads from DB.
3. App writes to cache.

• Pros: Only requested data is cached.
• Cons: Initial request is slow (cache miss).

Write-Through

1. App writes to cache and DB simultaneously.

• Pros: Data in cache is always fresh.
• Cons: Slower writes.

Write-Back (Write-Behind)

1. App writes to cache only.
2. Cache writes to DB asynchronously.

• Pros: Fast writes.
• Cons: Data loss risk if cache fails before syncing.

Eviction Policies

When the cache is full, what do you remove?

• LRU (Least Recently Used): Remove the item that hasn't been used for the longest time.
• LFU (Least Frequently Used): Remove the item used least often.
• FIFO (First In, First Out): Remove the oldest item.

🛠️ Sruja Perspective: Modeling Caches

In Sruja, caches are often modeled as separate containers or components.

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


Catalog = system "Product Catalog System" {
    WebApp = container "Storefront" {
        technology "Node.js"
    }

    ProductCache = container "Product Cache" {
        technology "Memcached"
        description "Caches product details using LRU eviction."
    }

    ProductDB = container "Product Database" {
        technology "MongoDB"
    }

    WebApp -> ProductCache "Read (Cache-Aside)"
    WebApp -> ProductDB "Read on Miss"
}

view index {
include *
}

Advanced Modeling

Lesson 1

title: "Lesson 1: Microservices Architecture" weight: 1 summary: "Monolith vs Microservices, Service Boundaries."

Lesson 1: Microservices Architecture

Monolith vs. Microservices

Monolithic Architecture

A single application where all functionality is packaged together.

• Pros: Simple to develop, deploy, and test initially.
• Cons: Hard to scale specific parts, tight coupling, single point of failure.

Microservices Architecture

A collection of small, independent services that communicate over a network.

• Pros: Independent scaling, technology diversity, fault isolation.
• Cons: Distributed system complexity, network latency, data consistency challenges.

Defining Service Boundaries

The hardest part of microservices is deciding where to draw the lines. Common strategies include:

• Business Capability: Group by what the business does (e.g., Billing, Shipping).
• Subdomain: Group by Domain-Driven Design (DDD) subdomains.

🛠️ Sruja Perspective: Modeling Microservices

In Sruja, microservices are typically modeled as separate container items within a system, or even as separate system items if they are large enough.

Basic Example

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

Customer = person "Customer"

OrderSystem = system "Order Management" {
    OrderService = container "Order Service" {
        technology "Rust"
        description "Handles order placement and tracking."
    }
    OrderDB = database "Order Database" {
        technology "PostgreSQL"
    }
    OrderService -> OrderDB "Reads/Writes"
}

InventorySystem = system "Inventory Management" {
    InventoryService = container "Inventory Service" {
        technology "Java"
        description "Tracks stock levels."
    }
    InventoryDB = database "Inventory Database" {
        technology "PostgreSQL"
    }
    InventoryService -> InventoryDB "Reads/Writes"
}

// Inter-service communication
Customer -> OrderSystem.OrderService "Places order"
OrderSystem.OrderService -> InventorySystem.InventoryService "Reserves stock"

// Requirements drive architecture
requirement R1 functional "Must handle 10k orders/day"
requirement R2 performance "Order placement < 500ms"
requirement R3 scalability "Scale order processing independently"

// Document decisions
adr ADR001 "Split into microservices" {
    status "Accepted"
    context "Need independent scaling for order vs inventory"
    decision "Separate OrderSystem and InventorySystem"
    consequences "Better scalability, network latency overhead"
}

view index {
title "System Overview"
include *
}

// Developer perspective: Focus on services and APIs
view developer {
title "Developer View - Service Architecture"
include OrderSystem OrderSystem.OrderService OrderSystem.OrderDB
include InventorySystem InventorySystem.InventoryService InventorySystem.InventoryDB
exclude Customer
}

// Product perspective: Focus on user experience
view product {
title "Product View - User Journey"
include Customer
include OrderSystem
exclude InventorySystem InventorySystem.InventoryDB
}

// Data flow perspective: Show data dependencies
view dataflow {
title "Data Flow View"
include OrderSystem.OrderService OrderSystem.OrderDB
include InventorySystem.InventoryService InventorySystem.InventoryDB
exclude Customer
}

Key Benefits of Multiple Views

1. Different Audiences: Developers see technical details, product managers see user flows
2. Reduced Complexity: Each view focuses on what matters for that perspective
3. Better Communication: Stakeholders get diagrams tailored to their needs
4. Documentation: Multiple views serve as different types of documentation

Lesson 2

title: "Lesson 2: Event-Driven Architecture" weight: 2 summary: "Pub/Sub, Message Queues, Event Sourcing."

Lesson 2: Event-Driven Architecture

Synchronous vs. Asynchronous

• Synchronous (Request/Response): Client waits for the server to respond (e.g., HTTP REST).
• Asynchronous (Event-Driven): Client sends a message and continues work. The receiver processes it later.

Core Concepts

Message Queues (Point-to-Point)

A message is sent to a queue and processed by exactly one consumer.

• Use Case: Background jobs (e.g., image resizing).

Pub/Sub (Publish/Subscribe)

A message (event) is published to a topic. Multiple subscribers can receive a copy.

• Use Case: notifying multiple services (e.g., "UserSignedUp" -> EmailService, AnalyticsService).

🛠️ Sruja Perspective: Modeling Events

Sruja supports queue as a first-class citizen to model asynchronous communication.

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


User = person "End User"

Notifications = system "Notification System" {
    AuthService = container "Auth Service" {
        technology "Node.js"
        description "Handles user authentication and publishes events"
    }

    // Define a queue or topic
    UserEvents = queue "User Events Topic" {
        technology "Kafka"
        description "Events related to user lifecycle (signup, login, profile updates)."
    }

    EmailService = container "Email Service" {
        technology "Python"
        description "Sends transactional emails"
    }

    AnalyticsService = container "Analytics Service" {
        technology "Spark"
        description "Processes user events for analytics"
    }

    NotificationDB = database "Notification Database" {
        technology "PostgreSQL"
        description "Stores notification preferences and history"
    }

    // Pub/Sub flow
    User -> AuthService "Signs up"
    AuthService -> UserEvents "Publishes 'UserSignedUp' event"
    UserEvents -> EmailService "Consumes - sends welcome email"
    UserEvents -> AnalyticsService "Consumes - tracks signup"
    EmailService -> NotificationDB "Logs email sent"
}

// Model the event flow as a scenario
UserSignupFlow = scenario "User Signup Event Flow" {
    User -> AuthService "Submits registration"
    AuthService -> UserEvents "Publishes UserSignedUp"
    UserEvents -> EmailService "Triggers welcome email"
    UserEvents -> AnalyticsService "Tracks signup event"
    EmailService -> User "Sends welcome email"
}

// Data flow for analytics processing
flow AnalyticsPipeline "Analytics Data Pipeline" {
    UserEvents -> AnalyticsService "Streams events"
    AnalyticsService -> AnalyticsService "Processes batch"
    AnalyticsService -> AnalyticsService "Generates reports"
}

view index {
title "Notification System Overview"
include *
}

// Event flow view: Focus on async communication
view eventflow {
title "Event Flow View"
include Notifications.AuthService
include Notifications.UserEvents
include Notifications.EmailService
include Notifications.AnalyticsService
exclude User Notifications.NotificationDB
}

// Data view: Focus on data storage
view data {
title "Data Storage View"
include Notifications.EmailService
include Notifications.NotificationDB
include Notifications.AnalyticsService
exclude Notifications.AuthService Notifications.UserEvents
}

Key Concepts

1. Scenarios model behavioral flows (user journeys, use cases)
2. Flows model data pipelines (ETL, streaming, batch processing)
3. Views let you focus on different aspects (events vs data vs user experience)

Lesson 3

title: "Lesson 3: Advanced Scenarios" weight: 3 summary: "Modeling user journeys and technical sequences with Scenarios."

Lesson 3: Advanced Scenarios

In Sruja, use scenario (and its alias story) to model runtime interactions: user journeys and technical sequences.

When to Use Scenarios

• Modeling user interactions
• Modeling technical sequences across elements

1. User Flows (Stories)

When modeling a user flow, you focus on the value delivered to the user. Sruja provides the story keyword (an alias for scenario) to make these definitions semantic and clear.

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


User = person "Customer"

Ticketing = system "Ticketing System" {
    WebApp = container "Web Application" {
        technology "React"
    }
    PaymentService = container "Payment Service" {
        technology "Rust"
    }
    TicketDB = database "Ticket Database" {
        technology "PostgreSQL"
    }

    WebApp -> PaymentService "Processes payment"
    PaymentService -> TicketDB "Stores transaction"
}

// High-level user flow
BuyTicket = story "User purchases a ticket" {
    User -> Ticketing.WebApp "Selects ticket"
    Ticketing.WebApp -> Ticketing.PaymentService "Process payment" {
        latency "500ms"
        protocol "HTTPS"
    }
    Ticketing.PaymentService -> User "Sends receipt"
}

view index {
include *
}

Notice how we can add properties like latency and protocol to steps using the { key "value" } syntax. This adds richness to your model without cluttering the diagram.

2. Technical Sequences

When modeling technical sequences, you dive deeper into the architecture, showing how containers and components interact to fulfill a request. You can stick with the scenario keyword here.

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


User = person "End User"

AuthSystem = system "Authentication System" {
    WebApp = container "Web Application" {
        technology "React"
    }
    AuthServer = container "Auth Server" {
        technology "Node.js, OAuth2"
    }
    Database = database "User Database" {
        technology "PostgreSQL"
    }

    WebApp -> AuthServer "Validates tokens"
    AuthServer -> Database "Queries user data"
}

// Detailed technical flow
AuthFlow = scenario "Authentication" {
    User -> AuthSystem.WebApp "Provides credentials"
    AuthSystem.WebApp -> AuthSystem.AuthServer "Validates token"
    AuthSystem.AuthServer -> AuthSystem.Database "Looks up user"
    AuthSystem.Database -> AuthSystem.AuthServer "Returns user data"
    AuthSystem.AuthServer -> AuthSystem.WebApp "Confirms token valid"
    AuthSystem.WebApp -> User "Shows login success"
}

view index {
include *
}

🛠️ Syntax Flexibility

Sruja offers flexible syntax to suit your needs:

Simple Syntax

Great for quick sketches or simple flows.

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


User = person "User"

AuthSystem = system "Auth System" {
    WebApp = container "Web App"
}

LoginFailure = scenario "Login Failure" {
    User -> AuthSystem.WebApp "Enters wrong password"
    AuthSystem.WebApp -> User "Shows error message"
}

view index {
include *
}

Formal Syntax

Better for documentation and referencing. Includes an ID and optional description.

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


Customer = person "Customer"

ECommerce = system "E-Commerce System" {
    Cart = container "Shopping Cart" {
        technology "React"
    }
    Payment = container "Payment Service" {
        technology "Rust"
    }
}

Inventory = system "Inventory System" {
    InventoryService = container "Inventory Service" {
        technology "Java"
    }
}

Customer -> ECommerce.Cart "Adds items"
ECommerce.Cart -> Inventory.InventoryService "Checks availability"
ECommerce.Cart -> ECommerce.Payment "Processes payment"

Checkout = scenario "Checkout Process" {
    description "The complete checkout flow including payment and inventory check."

    Customer -> ECommerce.Cart "Initiates checkout"
    ECommerce.Cart -> Inventory.InventoryService "Reserves items"
    Inventory.InventoryService -> ECommerce.Cart "Confirms reserved"
    ECommerce.Cart -> ECommerce.Payment "Charges payment"
    ECommerce.Payment -> Customer "Sends confirmation"
}

view index {
include *
}

Visualizing Scenarios

Studio/Viewer can highlight scenario paths over your static architecture so readers can follow behavior step‑by‑step.

Data-Oriented Scenarios

Use scenario for data‑oriented flows too—keep steps focused on interactions and outcomes between elements.

Lesson 4

title: "Lesson 4: Architectural Perspectives" weight: 4 summary: "Understanding context, containers, and components without special DSL keywords."

Lesson 4: Architectural Perspectives

As your system grows, a single diagram becomes too cluttered. You need different "maps" for different audiences:

• Executives: Need a high-level overview (Context).
• Architects: Need to see service boundaries (Containers).
• Developers: Need to see internal details (Components).

Sruja models naturally support multiple perspectives without special keywords. Use the built‑in elements, and tooling presents the right level of detail.

One Model, Multiple Perspectives

Sruja's views block lets you create custom perspectives from a single model. This is powerful for communicating with different audiences.

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


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

Shop = system "E-Commerce Shop" {
WebApp = container "Web Application" {
  technology "React"
  CartComponent = component "Shopping Cart"
  ProductComponent = component "Product Catalog"
}
API = container "API Service" {
  technology "Rust"
  OrderController = component "Order Controller"
  PaymentController = component "Payment Controller"
}
DB = database "Database" {
  technology "PostgreSQL"
}
Cache = database "Cache" {
  technology "Redis"
}
}

PaymentGateway = system "Payment Gateway" {
  metadata {
    tags ["external"]
  }
}

// Relations
Customer -> Shop.WebApp "Browses products"
Admin -> Shop.WebApp "Manages inventory"
Shop.WebApp -> Shop.API "Fetches data"
Shop.API -> Shop.DB "Reads/Writes"
Shop.API -> Shop.Cache "Caches queries"
Shop.API -> PaymentGateway "Processes payments"

// Executive view: High-level context
view executive {
title "Executive Overview"
include Customer
include Admin
include Shop
include PaymentGateway
exclude Shop.WebApp
exclude Shop.API
exclude Shop.DB
exclude Shop.Cache
}

// Architect view: Container-level architecture
view architect {
title "Architectural View"
include Shop Shop.WebApp Shop.API Shop.DB Shop.Cache
include PaymentGateway
exclude Customer Admin
exclude Shop.CartComponent Shop.ProductComponent Shop.OrderController Shop.PaymentController
}

// Developer view: Component-level details
view developer {
title "Developer View"
include Shop.WebApp Shop.WebApp.CartComponent Shop.WebApp.ProductComponent
include Shop.API Shop.API.OrderController Shop.API.PaymentController
include Shop.DB Shop.Cache
exclude Customer Admin PaymentGateway
}

// Data flow view: Focus on data dependencies
view dataflow {
title "Data Flow View"
include Shop.API Shop.DB Shop.Cache
exclude Customer Admin Shop.WebApp PaymentGateway
}

// Default view: Everything
view index {
title "Complete System View"
include *
}

Key Benefits

1. Context View (Executive): Shows systems and actors - perfect for stakeholders
2. Container View (Architect): Shows deployable units and their relationships
3. Component View (Developer): Shows internal structure and implementation details
4. Data Flow View: Focuses on data dependencies and storage
5. Complete View: Shows everything for comprehensive documentation

When to Use Views

• Different Audiences: Tailor diagrams to what each audience needs to see
• Reduce Complexity: Hide irrelevant details for specific discussions
• Documentation: Create multiple diagrams from one source of truth
• Presentations: Switch views during presentations to zoom in/out

Lesson 5

title: "Lesson 5: Views & Styling" weight: 5 summary: "Focus diagrams with views; improve legibility with styling."

Lesson 5: Views & Styling

Why Views?

Views let you spotlight specific paths (API, data, auth) without redrawing the whole system.

Sruja: Views and Styles

Views let you create focused diagrams from a single model. Styles make them visually clear.

Basic Views Example

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


User = person "User"

Shop = system "E-Commerce Shop" {
WebApp = container "Web Application"
API = container "API Service"
DB = database "Database"
}

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

// Default view: Everything
view index {
title "Complete System View"
include *
}

// API-focused view
view api {
title "API Focus View"
include Shop.API
include Shop.DB
exclude Shop.WebApp
exclude User
}

// User experience view
view user {
title "User Experience View"
include User
include Shop.WebApp
include Shop.API
exclude Shop.DB
}

Views with Custom Styling

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


Customer = person "Customer"

ECommerce = system "E-Commerce System" {
WebApp = container "Web Application"
API = container "API Service"
OrderDB = database "Order Database"
ProductDB = database "Product Database"
}

Customer -> ECommerce.WebApp "Browses"
ECommerce.WebApp -> ECommerce.API "Fetches data"
ECommerce.API -> ECommerce.OrderDB "Stores orders"
ECommerce.API -> ECommerce.ProductDB "Queries products"

// Global styles
style {
element "Database" {
  shape cylinder
  color "#22c55e"
}
relation "Fetches data" {
  color "#3b82f6"
}
relation "Stores" {
  color "#ef4444"
}
}

view index {
title "Complete View"
include *
}

// Data flow view with custom styling
view dataflow {
title "Data Flow View"
include ECommerce.API
include ECommerce.OrderDB
include ECommerce.ProductDB
exclude Customer
exclude ECommerce.WebApp

// View-specific styles override global styles
style {
  element "API" { color "#0ea5e9" }
  relation "Stores" { color "#10b981" }
}
}

Practice

• Create an "Data Flow" view focusing on DB reads/writes.
• Use view styles to highlight critical edges.

Lesson 6

title: "Lesson 6: Advanced DSL Features" weight: 6 summary: "Master views, scenarios, flows, and element kinds to create production-ready models."

Lesson 6: Advanced DSL Features

The Sruja DSL provides a flat syntax where all declarations—from element kinds to views—are top-level. This lesson covers the advanced capabilities that make your models more maintainable, understandable, and useful.

Kinds and Types: Your Foundation

Before creating instances of your architecture (like a "Database"), you must establish what kinds of elements exist. This isn't just documentation—it provides real benefits:

Benefits

1. Early Validation: Catches typos in element types before runtime
2. Better Tooling: Enables autocomplete, validation, and refactoring
3. Documentation: Makes available element types explicit
4. Organization: Separates structure definition from instantiation

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


// Now you can use any of the declared element types
Customer = person "Customer"
App = system "Application" {
API = container "API"
DB = datastore "Database"
}

Best Practice

Declare all element types you'll use upfront. This makes your model self-documenting and enables better tooling support.

Multiple Views: One Model, Many Perspectives

Use view blocks to create custom perspectives from your architecture. This is essential for communicating with different audiences. Unlike some other tools, Sruja allows defining views anywhere in your file, though keeping them at the bottom is a common convention.

Real-World Example: E-Commerce Platform

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


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

ECommerce = system "E-Commerce Platform" {
WebApp = container "Web Application" {
  CartComponent = component "Shopping Cart"
  ProductComponent = component "Product Catalog"
}
API = container "API Service" {
  OrderController = component "Order Controller"
  PaymentController = component "Payment Controller"
}
OrderDB = datastore "Order Database"
ProductDB = datastore "Product Database"
Cache = datastore "Redis Cache"
EventQueue = queue "Event Queue"
}

PaymentGateway = system "Payment Gateway" {
metadata {
    tags ["external"]
  }
}

Customer -> ECommerce.WebApp "Browses"
ECommerce.WebApp -> ECommerce.API "Fetches data"
ECommerce.API -> ECommerce.OrderDB "Stores orders"
ECommerce.API -> ECommerce.Cache "Caches queries"
ECommerce.API -> PaymentGateway "Processes payments"

// Executive view: High-level business context
view executive {
title "Executive Overview"
include Customer
include Admin
include ECommerce
include PaymentGateway
exclude ECommerce.WebApp
exclude ECommerce.API
exclude ECommerce.OrderDB
exclude ECommerce.ProductDB
exclude ECommerce.Cache
exclude ECommerce.EventQueue
}

// Architect view: Container-level architecture
view architect {
title "Architectural View"
include ECommerce
include ECommerce.WebApp
include ECommerce.API
include ECommerce.OrderDB
include ECommerce.ProductDB
include ECommerce.Cache
include ECommerce.EventQueue
include PaymentGateway
exclude Customer
exclude Admin
}

// Developer view: Component-level implementation
view developer {
title "Developer View"
include ECommerce.WebApp
include ECommerce.API
include ECommerce.OrderDB
include ECommerce.ProductDB
include ECommerce.Cache
exclude Customer
exclude Admin
exclude PaymentGateway
}

// Data flow view: Focus on data dependencies
view dataflow {
title "Data Flow View"
include ECommerce.API
include ECommerce.OrderDB
include ECommerce.ProductDB
include ECommerce.Cache
include ECommerce.EventQueue
exclude Customer
exclude Admin
exclude ECommerce.WebApp
exclude PaymentGateway
}

// User journey view: Customer experience
view userjourney {
title "User Journey View"
include Customer
include ECommerce.WebApp
include ECommerce.API
include PaymentGateway
exclude Admin
exclude ECommerce.OrderDB
exclude ECommerce.ProductDB
exclude ECommerce.Cache
exclude ECommerce.EventQueue
}

// Default view: Complete system
view index {
title "Complete System View"
include *
}

View Strategies

1. By Audience: Executive, Architect, Developer, Product Manager
2. By Concern: Data flow, Security, Performance, User experience
3. By Layer: Context, Container, Component
4. By Feature: Checkout flow, User management, Analytics

Scenarios: Modeling User Journeys

Scenarios model behavioral flows—what happens when users interact with your system. They're perfect for documenting user stories and use cases.

Example: Checkout Flow

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


Customer = person "Customer"

ECommerce = system "E-Commerce System" {
WebApp = container "Web Application"
API = container "API Service"
OrderDB = datastore "Order Database"
}

Inventory = system "Inventory System" {
InventoryService = container "Inventory Service"
}

PaymentGateway = system "Payment Gateway" {
metadata {
    tags ["external"]
  }
}

// Model the checkout journey
// EXPECTED_FAILURE: Layer violation (scenarios model bidirectional user journeys)
CheckoutFlow = scenario "User Checkout Journey" {
Customer -> ECommerce.WebApp "Adds items to cart"
ECommerce.WebApp -> ECommerce.API "Submits checkout"
ECommerce.API -> Inventory.InventoryService "Reserves stock"
Inventory.InventoryService -> ECommerce.API "Confirms availability"
ECommerce.API -> PaymentGateway "Processes payment"
PaymentGateway -> ECommerce.API "Confirms payment"
ECommerce.API -> ECommerce.OrderDB "Saves order"
ECommerce.API -> ECommerce.WebApp "Returns confirmation"
ECommerce.WebApp -> Customer "Shows order confirmation"
}

// Alternative happy path
CheckoutSuccess = scenario "Successful Checkout" {
Customer -> ECommerce.WebApp "Completes checkout"
ECommerce.WebApp -> ECommerce.API "Processes order"
ECommerce.API -> Customer "Confirms order"
}

// Error scenario
CheckoutFailure = scenario "Checkout Failure" {
Customer -> ECommerce.WebApp "Attempts checkout"
ECommerce.WebApp -> ECommerce.API "Validates order"
ECommerce.API -> Inventory.InventoryService "Checks stock"
Inventory.InventoryService -> ECommerce.API "Out of stock"
ECommerce.API -> ECommerce.WebApp "Returns error"
ECommerce.WebApp -> Customer "Shows out of stock message"
}

view index {
include *
}

When to Use Scenarios

• User Stories: Document how users interact with your system
• Use Cases: Model specific business processes
• Error Handling: Document failure paths and recovery
• Integration Testing: Define test scenarios

Flows: Modeling Data Pipelines

Flows model data-oriented processes—how data moves through your system. Use them for ETL, streaming, and batch processing.

Example: Analytics Pipeline

// EXPECTED_FAILURE: Layer violation (flows model bidirectional data movement)
import { * } from 'sruja.ai/stdlib'


Analytics = system "Analytics Platform" {
IngestionService = container "Data Ingestion"
ProcessingService = container "Data Processing"
QueryService = container "Query Service"
EventStream = queue "Event Stream"
RawDataDB = datastore "Raw Data Store"
ProcessedDataDB = datastore "Processed Data Warehouse"
}

// Data flow: Event ingestion pipeline
EventIngestion = flow "Event Ingestion Pipeline" {
Analytics.IngestionService -> Analytics.EventStream "Publishes events"
Analytics.EventStream -> Analytics.ProcessingService "Streams events"
Analytics.ProcessingService -> Analytics.RawDataDB "Stores raw data"
Analytics.ProcessingService -> Analytics.ProcessedDataDB "Stores processed data"
Analytics.QueryService -> Analytics.ProcessedDataDB "Queries analytics"
}

// Batch processing flow
BatchProcessing = flow "Daily Batch Processing" {
Analytics.RawDataDB -> Analytics.ProcessingService "Extracts daily data"
Analytics.ProcessingService -> Analytics.ProcessingService "Transforms data"
Analytics.ProcessingService -> Analytics.ProcessedDataDB "Loads aggregated data"
}

view index {
include *
}

Scenario vs Flow

• Scenario: Behavioral flows (user actions, business processes)
• Flow: Data flows (ETL, streaming, batch processing)

Integrating Requirements, ADRs, and Policies

Sruja's flat syntax makes it easy to integrate requirements, ADRs, and policies directly into your architecture model as top-level declarations.

Complete Example

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


Customer = person "Customer"

// Requirements drive architecture
R1 = requirement "Must handle 10k concurrent users" { tags ["functional"] }
R2 = requirement "API response < 200ms p95" { tags ["performance"] }
R3 = requirement "Scale to 1M users" { tags ["scalability"] }
R4 = requirement "All PII encrypted at rest" { tags ["security"] }

// Architecture decisions documented as ADRs
ADR001 = adr "Use microservices for independent scaling" {
status "Accepted"
context "Need to scale order processing independently from inventory"
decision "Split into OrderService and InventoryService"
consequences "Better scalability, increased network complexity"
}

ADR002 = adr "Use PostgreSQL for strong consistency" {
status "Accepted"
context "Need ACID transactions for financial data"
decision "Use PostgreSQL instead of NoSQL"
consequences "Strong consistency, SQL complexity"
}

// Architecture that satisfies requirements
ECommerce = system "E-Commerce Platform" {
API = container "API Service" {
  technology "Rust"
  description "Satisfies R1, R2, R3"
  // adr ADR001 ADR002

  slo {
    availability {
      target "99.99%"
      window "30 days"
    }
    latency {
      p95 "200ms"
      p99 "500ms"
    }
  }
}

OrderDB = datastore "Order Database" {
  technology "PostgreSQL"
  description "Satisfies R4 - encrypted at rest"
  // adr ADR002
}
}

// Policy enforcement
SecurityPolicy = policy "All databases must be encrypted" {
category "security"
enforcement "required"
description "Compliance requirement for PII data"
}

view index {
include *
}

Best Practices

1. Explicit Kinds: Import or declare all element kinds upfront.
2. Use Multiple Views: Create views for different audiences and concerns
3. Document with Scenarios: Model user journeys and business processes
4. Model Data Flows: Use flows for ETL and data pipelines
5. Link Requirements: Connect requirements to architecture decisions
6. Document Decisions: Use ADRs to explain why, not just what
7. Define SLOs: Model service level objectives for production systems

Next Steps

Now that you understand the advanced features, you can create production-ready models that:

• Communicate effectively with different audiences
• Document user journeys and data flows
• Link requirements to architecture decisions
• Enable automated validation and governance

👉 Module 4: Production Readiness - Learn how to make your architecture production-ready.

Lesson 7

title: "Lesson 7: Views Best Practices" weight: 7 summary: "Master the art of creating effective views for different audiences and purposes."

Lesson 7: Views Best Practices

Views are one of the most powerful features in Sruja DSL. They let you create multiple perspectives from a single model, making your architecture documentation accessible to different audiences. This lesson covers best practices for creating effective views.

The Power of Views

A single architecture model can serve:

• Executives: High-level business context
• Product Managers: Feature and user journey focus
• Architects: Technical design and patterns
• Developers: Implementation details
• Operations: Deployment and monitoring concerns
• Security: Compliance and threat modeling

View Creation Strategy

1. Start with Your Audience

Before creating a view, ask:

• Who will use this view? (Executive, Developer, Ops)
• What questions do they need answered? (Cost, Performance, Security)
• What level of detail do they need? (Context, Container, Component)

2. Use Include/Exclude Strategically

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


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

ECommerce = system "E-Commerce Platform" {
WebApp = container "Web Application" {
  CartComponent = component "Shopping Cart"
  ProductComponent = component "Product Catalog"
}
API = container "API Service" {
  OrderController = component "Order Controller"
  PaymentController = component "Payment Controller"
}
OrderDB = database "Order Database"
ProductDB = database "Product Database"
}

PaymentGateway = system "Payment Gateway" {
metadata {
    tags ["external"]
  }
}

Customer -> ECommerce.WebApp "Browses"
ECommerce.WebApp -> ECommerce.API "Fetches data"
ECommerce.API -> ECommerce.OrderDB "Stores orders"
ECommerce.API -> PaymentGateway "Processes payments"

// Executive view: Business context only
view executive {
title "Executive Overview"
include Customer
include Admin
include ECommerce
include PaymentGateway
exclude ECommerce.WebApp
exclude ECommerce.API
exclude ECommerce.OrderDB
exclude ECommerce.ProductDB
}

// Architect view: Container-level architecture
view architect {
title "Architectural View"
include ECommerce
include ECommerce.WebApp
include ECommerce.API
include ECommerce.OrderDB
include ECommerce.ProductDB
include PaymentGateway
exclude Customer
exclude Admin
}

// Developer view: Component-level implementation
view developer {
title "Developer View"
include ECommerce.WebApp
include ECommerce.API
include ECommerce.OrderDB
include ECommerce.ProductDB
exclude Customer
exclude Admin
exclude PaymentGateway
}

3. Create Concern-Specific Views

Focus on specific concerns: performance, security, data flow, deployment.

// Performance view: Components with performance characteristics
view performance {
title "Performance View"
include ECommerce.API
include ECommerce.OrderDB
exclude Customer
exclude Admin
exclude ECommerce.WebApp
}

// Security view: External interactions and data stores
view security {
title "Security View"
include ECommerce.API
include PaymentGateway
include ECommerce.OrderDB
exclude Customer
exclude Admin
exclude ECommerce.WebApp
}

// Data flow view: Data dependencies
view dataflow {
title "Data Flow View"
include ECommerce.API
include ECommerce.OrderDB
include ECommerce.ProductDB
exclude Customer
exclude Admin
exclude ECommerce.WebApp
exclude PaymentGateway
}

View Naming Conventions

Use clear, descriptive names that indicate the view's purpose:

Good Names

• executive - Clear audience
• dataflow - Clear concern
• deployment - Clear purpose
• security-audit - Specific use case

Avoid

• view1, view2 - Not descriptive
• temp - Temporary views should be removed
• test - Test views shouldn't be in production models

View Organization Patterns

Pattern 1: By Audience

Create views for each stakeholder group.

view executive { /* ... */ }
view product { /* ... */ }
view architect { /* ... */ }
view developer { /* ... */ }
view operations { /* ... */ }

Pattern 2: By Concern

Create views for different technical concerns.

view performance { /* ... */ }
view security { /* ... */ }
view dataflow { /* ... */ }
view deployment { /* ... */ }

Pattern 3: By Layer

Create views for different C4 model layers.

view context { /* System context */ }
view container { /* Container diagram */ }
view component { /* Component diagram */ }

Pattern 4: By Feature

Create views for specific features or domains.

view checkout { /* Checkout flow */ }
view search { /* Search functionality */ }
view analytics { /* Analytics pipeline */ }

Best Practices

1. Always Include an Index View

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

2. Use Descriptive Titles

view executive {
  title "Executive Overview - Business Context"
  // ...
}

3. Add Descriptions

view architect {
  title "Architectural View"
  description "Container-level architecture showing system boundaries and interactions"
  // ...
}

4. Keep Views Focused

Each view should answer a specific set of questions. If a view tries to answer too many questions, split it into multiple views.

5. Document View Purpose

Use comments or descriptions to explain why a view exists and when to use it.

// Use this view for:
// - Executive presentations
// - Business stakeholder discussions
// - High-level architecture reviews
view executive {
title "Executive Overview"
// ...
}

Common View Patterns

Executive Dashboard View

view executive {
  title "Executive Dashboard"
  include Customer Admin
  include ECommerce PaymentGateway
  exclude ECommerce.WebApp ECommerce.API
  exclude ECommerce.OrderDB ECommerce.ProductDB
}

Technical Architecture View

view technical {
  title "Technical Architecture"
  include ECommerce ECommerce.WebApp ECommerce.API
  include ECommerce.OrderDB ECommerce.ProductDB
  exclude Customer Admin
}

User Journey View

view userjourney {
  title "User Journey View"
  include Customer
  include ECommerce.WebApp ECommerce.API
  include PaymentGateway
  exclude Admin ECommerce.OrderDB ECommerce.ProductDB
}

Deployment View

view deployment {
  title "Deployment View"
  include ECommerce.WebApp ECommerce.API
  include ECommerce.OrderDB
  exclude Customer Admin PaymentGateway
}

View Maintenance

When to Create New Views

• New stakeholder group needs different perspective
• New concern emerges (e.g., compliance)
• Feature-specific view needed for documentation

When to Remove Views

• View is no longer used
• View duplicates another view
• View is outdated and not maintained

When to Update Views

• Architecture changes affect view scope
• New components need to be included/excluded
• View purpose changes

Advanced: View Composition

You can create views that build on other views by carefully selecting elements:

// Base view: All containers
view containers {
title "Container View"
include ECommerce.WebApp ECommerce.API
include ECommerce.OrderDB ECommerce.ProductDB
}

// Extended view: Containers + external systems
view containers-extended {
title "Container View with External Systems"
include ECommerce.WebApp ECommerce.API
include ECommerce.OrderDB ECommerce.ProductDB
include PaymentGateway
}

Real-World Example: E-Commerce Platform

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


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

ECommerce = system "E-Commerce Platform" {
WebApp = container "Web Application" {
  CartComponent = component "Shopping Cart"
  ProductComponent = component "Product Catalog"
}
API = container "API Service" {
  OrderController = component "Order Controller"
  PaymentController = component "Payment Controller"
}
OrderDB = database "Order Database"
ProductDB = database "Product Database"
Cache = database "Redis Cache"
EventQueue = queue "Event Queue"
}

PaymentGateway = system "Payment Gateway" {
metadata {
    tags ["external"]
  }
}

Customer -> ECommerce.WebApp "Browses"
ECommerce.WebApp -> ECommerce.API "Fetches data"
ECommerce.API -> ECommerce.OrderDB "Stores orders"
ECommerce.API -> ECommerce.Cache "Caches queries"
ECommerce.API -> PaymentGateway "Processes payments"

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

// Executive: Business context
view executive {
title "Executive Overview"
include Customer Admin
include ECommerce PaymentGateway
exclude ECommerce.WebApp ECommerce.API ECommerce.OrderDB ECommerce.ProductDB ECommerce.Cache ECommerce.EventQueue
}

// Product: User journeys
view product {
title "Product View - User Journeys"
include Customer
include ECommerce.WebApp
include ECommerce.API
include PaymentGateway
exclude Admin
exclude ECommerce.OrderDB
exclude ECommerce.ProductDB
exclude ECommerce.Cache
exclude ECommerce.EventQueue
}

// Architect: Container architecture
view architect {
title "Architectural View"
include ECommerce ECommerce.WebApp ECommerce.API
include ECommerce.OrderDB ECommerce.ProductDB ECommerce.Cache ECommerce.EventQueue
include PaymentGateway
exclude Customer Admin
}

// Developer: Component details
view developer {
title "Developer View"
include ECommerce.WebApp
include ECommerce.API
include ECommerce.OrderDB ECommerce.ProductDB ECommerce.Cache
exclude Customer Admin PaymentGateway
}

// Operations: Deployment and monitoring
view operations {
title "Operations View"
include ECommerce.WebApp ECommerce.API
include ECommerce.OrderDB ECommerce.ProductDB ECommerce.Cache ECommerce.EventQueue
exclude Customer Admin PaymentGateway
}

// Data flow: Data dependencies
view dataflow {
title "Data Flow View"
include ECommerce.API ECommerce.OrderDB ECommerce.ProductDB ECommerce.Cache ECommerce.EventQueue
exclude Customer Admin ECommerce.WebApp PaymentGateway
}

// Performance: Performance-critical components
view performance {
title "Performance View"
include ECommerce.API ECommerce.Cache ECommerce.OrderDB
exclude Customer Admin ECommerce.WebApp ECommerce.ProductDB ECommerce.EventQueue PaymentGateway
}

Summary

Views are a powerful tool for making architecture documentation accessible to different audiences. Follow these best practices:

1. Start with your audience - Know who will use the view
2. Use include/exclude strategically - Focus on what matters
3. Create concern-specific views - Performance, security, data flow
4. Use clear naming - Descriptive names that indicate purpose
5. Document view purpose - Explain why the view exists
6. Keep views focused - Each view should answer specific questions
7. Maintain views - Update or remove views as architecture evolves

👉 Module 4: Production Readiness - Learn how to make your architecture production-ready.

Production Readiness

Lesson 1

title: "Lesson 1: Documenting Decisions (ADRs)" weight: 1 summary: "Why document? What is an ADR?"

Lesson 1: Documenting Decisions (ADRs)

What is an ADR?

An Architecture Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences.

Why use ADRs?

• Context: Explains why a decision was made (e.g., "Why did we choose Postgres over Mongo?").
• Onboarding: Helps new team members understand the history of the system.
• Alignment: Ensures everyone agrees on the path forward.

Structure of an ADR

1. Title: Short summary.
2. Status: Proposed, Accepted, Deprecated.
3. Context: The problem we are solving.
4. Decision: What we are doing.
5. Consequences: The pros and cons of this decision.

🛠️ Sruja Perspective: Native ADR Support

Sruja treats ADRs as first-class citizens. You can define them directly in your architecture file.

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


// Define an ADR
adr ADR001 "Use Stripe for Payments" {
    status "Accepted"
    context "We need a reliable payment processor that supports global currencies."

    // Document alternatives considered
    option "PayPal" {
        pros "Easy setup"
        cons "Higher fees"
    }

    option "Stripe" {
        pros "Developer friendly, good API"
        cons "Complex verification"
    }

    decision "Stripe"
    reason "Better developer experience and lower fees at scale."
    consequences "Vendor lock-in, but faster time to market."
}

PaymentService = system "Payment Service" {
    // Link the ADR to the component it affects
    adr ADR001
    description "Handles credit card processing."
}

view index {
include *
}

This ensures that your documentation lives right next to the code it describes, making it harder to ignore or lose.

Lesson 2

title: "Lesson 2: Deployment Architecture" weight: 2 summary: "Cloud, On-prem, Containers, and real-world deployment strategies."

Lesson 2: Deployment Architecture

Real-World Scenario: Startup to Scale

Context: A fintech startup begins with a single server, grows to 10M users, and needs to plan deployment architecture.

Challenge: How do you model and evolve deployment architecture as you scale?

Logical vs. Physical Architecture

• Logical Architecture: The software components and how they interact (Containers, Components).
• Physical Architecture: Where those components actually run (Servers, VMs, Kubernetes Pods).

Why it matters: Understanding this separation helps you:

• Plan migrations (e.g., moving from EC2 to EKS)
• Model multi-cloud strategies
• Document disaster recovery plans
• Communicate with DevOps teams

Deployment Strategies: Real-World Trade-offs

On-Premises

Running on your own hardware in a data center.

Real-world use cases:

• Financial institutions (regulatory compliance)
• Healthcare systems (HIPAA data residency)
• Government systems (sovereignty requirements)

• Pros: Total control, security, data sovereignty.
• Cons: High maintenance, capital expense, slower scaling.
• Cost example: $500K+ initial investment, 3-5 year hardware refresh cycles

Cloud (AWS, GCP, Azure)

Renting infrastructure from a provider.

Real-world use cases:

• SaaS platforms (99% of modern startups)
• E-commerce (seasonal scaling)
• Media streaming (global distribution)

• Pros: Pay-as-you-go, infinite scale, managed services.
• Cons: Vendor lock-in, variable costs, compliance complexity.
• Cost example: $5K/month for small SaaS, $50K+ for mid-size, $500K+ for enterprise

Containers & Orchestration

Packaging code with dependencies (Docker) and managing them at scale (Kubernetes).

Real-world adoption:

• 2024: 70% of enterprises use Kubernetes
• Common pattern: Docker → Kubernetes → Service Mesh (Istio/Linkerd)

Production considerations:

• Resource limits (CPU/memory)
• Health checks and liveness probes
• Rolling updates and rollback strategies
• Multi-region deployments

🛠️ Sruja Perspective: Deployment Nodes

Sruja allows you to map your logical containers to physical deployment nodes, making it clear where code runs in production.

Example: Multi-Region E-Commerce Platform

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


ECommerce = system "E-Commerce Platform" {
    API = container "REST API" {
        technology "Rust"
        scale {
            min 3
            max 100
            metric "cpu > 70%"
        }
    }
    WebApp = container "React Frontend" {
        technology "React"
    }
    PrimaryDB = database "PostgreSQL" {
        technology "PostgreSQL"
    }
    Cache = database "Redis" {
        technology "Redis"
    }
}

// Production deployment across regions
deployment Production "Production Environment" {
    node AWS "AWS Cloud" {
        // Primary region: US-East-1
        node USEast1 "US-East-1 (Primary)" {
            node EKS "EKS Cluster" {
                containerInstance API {
                    replicas 10
                }
                containerInstance WebApp {
                    replicas 5
                }
            }
            node RDS "RDS Multi-AZ" {
                containerInstance PrimaryDB {
                    role "primary"
                }
            }
            node ElastiCache "ElastiCache" {
                containerInstance Cache
            }
        }

        // Secondary region: EU-West-1 (for DR and latency)
        node EUWest1 "EU-West-1 (Secondary)" {
            node EKS "EKS Cluster" {
                containerInstance API {
                    replicas 5
                }
                containerInstance WebApp {
                    replicas 3
                }
            }
            node RDS "RDS Read Replica" {
                containerInstance PrimaryDB {
                    role "read-replica"
                }
            }
        }
    }
}

view index {
include *
}

DevOps Integration: CI/CD Pipeline

Model your deployment pipeline alongside architecture:

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


CICD = system "CI/CD System" {
    GitHubActions = container "GitHub Actions" {
        description "Triggers on push to main branch"
    }
    BuildService = container "Build Service" {
        technology "Docker"
        description "Builds container images"
    }
    TestRunner = container "Test Runner" {
        description "Runs unit, integration, and E2E tests"
    }
    DeployService = container "Deploy Service" {
        technology "ArgoCD"
        description "Deploys to Kubernetes clusters"
    }

    GitHubActions -> BuildService "Builds image"
    BuildService -> TestRunner "Runs tests"
    TestRunner -> DeployService "Deploys if tests pass"
}

// Link deployment to CI/CD
// Note: Deployment metadata (CI/CD pipeline, strategy) is modeled in the deployment node
deployment Production "Production Deployment" {
    node Infrastructure "Production Infrastructure" {
    }
}

view index {
include *
}

Real-World Patterns

Pattern 1: Blue/Green Deployment

Use case: Zero-downtime deployments for critical services

deployment Production {
    node Blue "Active Environment" {
        containerInstance API {
            traffic 100
        }
    }
    node Green "Staging Environment" {
        containerInstance API {
            traffic 0
            status "ready-for-switch"
        }
    }
}

DevOps workflow:

1. Deploy new version to Green
2. Run smoke tests
3. Switch 10% traffic to Green
4. Monitor for 15 minutes
5. Gradually increase to 100%
6. Keep Blue ready for rollback

Pattern 2: Canary Deployment

Use case: Gradual rollout with automatic rollback

deployment Production {
    node Canary "Canary Cluster" {
        containerInstance API {
            traffic 5
            description "5% of traffic, auto-rollback on error rate > 1%"
        }
    }
    node Stable "Stable Cluster" {
        containerInstance API {
            traffic 95
        }
    }
}

Pattern 3: Multi-Cloud Strategy

Use case: Avoiding vendor lock-in, disaster recovery

deployment Production {
    node AWS "AWS Primary" {
        containerInstance API {
            region "us-east-1"
            traffic 80
        }
    }
    node GCP "GCP Secondary" {
        containerInstance API {
            region "us-central1"
            traffic 20
            description "Failover target"
        }
    }
}

Service Level Objectives (SLOs)

Define reliability targets directly in your architecture model:

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


ECommerce = system "E-Commerce Platform" {
API = container "REST API" {
  technology "Rust"

  // Define SLOs for production monitoring
  slo {
    availability {
      target "99.99%"
      window "30 days"
      current "99.95%"
    }
    latency {
      p95 "200ms"
      p99 "500ms"
      window "7 days"
      current {
        p95 "180ms"
        p99 "450ms"
      }
    }
    errorRate {
      target "< 0.1%"
      window "30 days"
      current "0.05%"
    }
    throughput {
      target "1000 req/s"
      window "1 hour"
      current "950 req/s"
    }
  }
}

Database = database "PostgreSQL" {
  technology "PostgreSQL"
  slo {
    availability {
      target "99.9%"
      window "30 days"
    }
    latency {
      p95 "50ms"
      p99 "100ms"
    }
  }
}
}

view index {
include *
}

Benefits of Modeling SLOs

1. Clear Targets: Everyone knows what "good" looks like
2. Monitoring Guidance: SLOs define what metrics to track
3. Stakeholder Communication: Clear reliability commitments
4. Living Documentation: SLOs live with architecture, not separate docs

Monitoring & Observability

Model your observability stack:

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


Observability = system "Observability Stack" {
Prometheus = container "Metrics" {
  technology "Prometheus"
  description "Collects metrics from all services"
}
Grafana = container "Dashboards" {
  technology "Grafana"
  description "Visualizes metrics and alerts"
}
ELK = container "Logging" {
  technology "Elasticsearch, Logstash, Kibana"
  description "Centralized logging"
}
Jaeger = container "Tracing" {
  technology "Jaeger"
  description "Distributed tracing"
}
}

ECommerce = system "E-Commerce" {
  API = container "API"
}

// Link to your services
ECommerce.API -> Observability.Prometheus "Exposes metrics"
ECommerce.API -> Observability.ELK "Sends logs"
ECommerce.API -> Observability.Jaeger "Sends traces"

Key Takeaways

1. Separate logical from physical: Model what your system does (logical) separately from where it runs (physical)
2. Document deployment strategies: Use deployment nodes to show Blue/Green, Canary, or multi-region setups
3. Link to CI/CD: Show how code flows from commit to production
4. Model observability: Include monitoring, logging, and tracing in your architecture
5. Plan for scale: Document scaling strategies (min/max replicas, regions)

Exercise: Model Your Deployment

1. Choose a real system you work on (or a hypothetical one)
2. Model the logical architecture (containers, datastores)
3. Map to physical deployment (cloud regions, clusters)
4. Add deployment strategy (Blue/Green, Canary, or Rolling)
5. Include observability components

Time: 20 minutes

Further Reading

• Tutorial: Deployment Modeling
• Docs: Deployment Concepts
• Course: E-Commerce Platform - Module 5: Ops

Lesson 3

title: "Lesson 3: Governance as Code" weight: 3 summary: "Automating architectural compliance with Policies and Rules."

Lesson 3: Governance as Code

As your organization scales, manually reviewing every architectural change becomes impossible. You need automated guardrails to ensure consistency and security.

What is Governance as Code?

Governance as Code treats architectural policies (e.g., "All databases must be encrypted", "No circular dependencies") as executable code that can be validated automatically in your CI/CD pipeline.

Built-in Validation Rules

Sruja validates common architectural concerns automatically:

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


PaymentService = system "Payment Service" {
    API = container "Payment API" {
        technology "Rust"
        tags ["encrypted", "pci-compliant"]

        // SLOs for payment processing
        slo {
            availability {
                target "99.99%"
                window "30 days"
                current "99.98%"
                description "Payment processing must be highly available"
            }
            latency {
                p95 "100ms"
                p99 "200ms"
                window "7 days"
                current {
                    p95 "95ms"
                    p99 "190ms"
                }
                description "Fast payment processing critical for UX"
            }
            errorRate {
                target "< 0.01%"
                window "30 days"
                current "0.008%"
                description "Payment errors must be extremely rare"
            }
            throughput {
                target "500 req/s"
                window "1 hour"
                current "480 req/s"
                description "Handle peak payment volumes"
            }
        }
    }

    DB = database "Payment Database" {
        technology "PostgreSQL"
        tags ["encrypted", "backed-up"]

        // Database SLOs
        slo {
            availability {
                target "99.95%"
                window "30 days"
                current "99.92%"
            }
            latency {
                p95 "20ms"
                p99 "50ms"
                window "7 days"
            }
        }
    }
}

Auditor = person "Security Auditor"
Auditor -> PaymentService.API "Reviews"
PaymentService.API -> PaymentService.DB "Reads/Writes"

view index {
title "Payment Service with Governance"
include *
}

// SLO monitoring view
view slos {
title "SLO Monitoring View"
include PaymentService.API PaymentService.DB
exclude Auditor
description "Focuses on components with SLOs defined"
}

// Compliance view
view compliance {
title "Compliance View"
include PaymentService.API PaymentService.DB
exclude Auditor
description "Shows components with compliance tags"
}

Automated Validation

The real power comes when you run the Sruja CLI. It can check your architecture against these policies and fail the build if violations are found.

sruja validate architecture.sruja

This ensures that your architecture isn't just a diagram—it's a specification that is continuously verified.

Lesson 4

title: "Lesson 4: SLOs & Scale Integration" weight: 4 summary: "Define SLOs and align scale to meet targets."

Lesson 4: SLOs & Scale Integration

Why SLOs?