Skip to content

Commit d04ea7d

Browse files
rocketstack-mattrocketstack-matt
authored
Merge pull request #2342 from jimthompson5802/iss-2017-migrate-aoc-part2
feat(docs): Migrate Days 8 to 20 to calm.finos.org Learning section
2 parents e0d6b1c + 4369599 commit d04ea7d

17 files changed

Lines changed: 3007 additions & 18 deletions

‎docs/docs/tutorials/beginner/07-complete-architecture.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -246,6 +246,7 @@ Your e-commerce architecture should look something like this:
246246
🎉 **Congratulations!** You've completed the beginner tutorials and can now model complete architectures with CALM.
247247

248248
**Continue Learning:**
249+
- Continue with the **Intermediate** level tutorials.
249250
- Explore the [Core Concepts](../../core-concepts/) for deeper understanding
250251
- Check out [Working with CALM](../../working-with-calm/) for CLI and tooling details
251252
- Join the [FINOS Architecture as Code community](https://github.com/finos/architecture-as-code/discussions)

‎docs/docs/tutorials/index.md‎

Lines changed: 91 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -15,27 +15,44 @@ Welcome to the CALM learning path! These tutorials take you from zero CALM knowl
1515
│ YOUR CALM LEARNING PATH │
1616
├─────────────────────────────────────────────────────────────────────────────┤
1717
│ │
18-
│ BEGINNER TUTORIALS │
18+
│ 🟢 BEGINNER TUTORIALS │
1919
│ ├── Setup & CLI │
2020
│ ├── First Node │
2121
│ ├── Relationships │
2222
│ ├── VSCode Extension │
2323
│ ├── Interfaces │
2424
│ ├── Metadata │
2525
│ └── Complete Architecture │
26-
│ │
27-
│ PRACTITIONER TUTORIAL │
26+
│ │ │
27+
│ ▼ │
28+
│ 🟡 INTERMEDIATE TUTORIALS │
29+
│ ├── Controls │
30+
│ ├── Business Flows │
31+
│ ├── ADR Linking │
32+
│ ├── Docify │
33+
│ ├── CALM Widgets │
34+
│ ├── Handlebars Templates │
35+
│ ├── AI Advisor │
36+
│ ├── Ops Advisor │
37+
│ ├── Ops Documentation │
38+
│ ├── Patterns │
39+
│ ├── Standards │
40+
│ ├── Enforcing Standards │
41+
│ └── Multi-Pattern Validation │
42+
│ │ │
43+
│ ▼ │
44+
│ 🛠️ PRACTITIONER TUTORIAL │
2845
│ ├── Tool Setup │
2946
│ ├── Understand the Business Context │
3047
│ ├── Define Initial Architecture │
3148
│ ├── Refine Architecture Definition │
32-
│ ├── Generate Architecture Documentation │
49+
│ ├── Generate Architecture Documentation │
3350
│ └── Key Takeaways │
3451
│ │
3552
└─────────────────────────────────────────────────────────────────────────────┘
3653
```
3754

38-
## Start Here: Beginner Tutorials
55+
## Start Here: Beginner
3956

4057
### 🟢 Beginner Tutorials
4158

@@ -49,11 +66,7 @@ Learn the core building blocks of CALM architectures:
4966

5067
**Time commitment:** ~15-45 minutes per tutorial
5168

52-
[Start with Beginner Tutorials →](./beginner/)
53-
54-
---
55-
56-
## Prerequisites
69+
### Prerequisites
5770

5871
Before you begin, make sure you have:
5972

@@ -62,30 +75,84 @@ Before you begin, make sure you have:
6275
- **VSCode** editor (version 1.96+)
6376
- **GitHub Copilot** access (optional but recommended, requires VSCode 1.106+)
6477

65-
## Getting Started
78+
### Getting Started
6679

6780
1. **[Start with Setup & CLI](./beginner/01-setup)** — Set up your CALM workspace and tools
6881
2. **Work through each tutorial** — They build on each other progressively
6982
3. **Ask questions** — Join the [FINOS Architecture as Code community](https://github.com/finos/architecture-as-code/discussions)
7083

71-
## Skills You'll Acquire
84+
### Skills You'll Acquire
7285

73-
By completing all tutorials, you'll be able to:
86+
By completing all beginner tutorials, you'll be able to:
7487

7588
✅ **Create** complete architecture documents from scratch
7689
✅ **Model** nodes, relationships, interfaces, and metadata
7790
✅ **Use** the VSCode extension for visualization
7891
✅ **Build** realistic multi-service architectures
7992

80-
Ready to begin? [Start your CALM journey →](beginner/01-setup)
93+
[Start your CALM journey →](./beginner/01-setup)
94+
95+
---
96+
97+
## Start Here: Intermediate
98+
99+
### 🟡 Intermediate Tutorials
100+
101+
**Complete the Beginner Tutorials before starting here**
102+
103+
Go beyond the basics and learn how to build richer, governance-ready architectures:
104+
- Adding controls and business flows to architectures
105+
- Linking Architecture Decision Records (ADRs)
106+
- Publishing architecture docs with `docify`
107+
- Building custom templates and widgets
108+
- Using CALM as an AI-powered advisor
109+
- Creating reusable Patterns and organizational Standards
110+
- Enforcing compliance with multi-pattern validation
111+
112+
**Time commitment:** ~30-60 minutes per tutorial
113+
114+
### Prerequisites
115+
116+
- **Completed all Beginner Tutorials** (see [Start Here: Beginner](#start-here-beginner) above)
117+
118+
### Getting Started
119+
120+
1. **[Start with Controls](./intermediate/08-controls)** — Add governance controls to your architecture
121+
2. **Work through each tutorial** — They build on each other progressively
122+
3. **Ask questions** — Join the [FINOS Architecture as Code community](https://github.com/finos/architecture-as-code/discussions)
123+
124+
### Skills You'll Acquire
125+
126+
By completing all intermediate tutorials, you'll be able to:
127+
128+
✅ **Add** controls and business flows to architectures
129+
✅ **Link** Architecture Decision Records (ADRs) to architecture elements
130+
✅ **Publish** architecture documentation using `docify`
131+
✅ **Build** custom templates and widgets for visualization
132+
✅ **Use** CALM as an AI-powered architecture advisor
133+
✅ **Create** reusable Patterns and organizational Standards
134+
✅ **Enforce** compliance through multi-pattern validation
135+
136+
[Start Intermediate Tutorials →](./intermediate/)
137+
138+
---
81139

82140
## Start Here: Practitioner
83141

84142
### 🛠️ Practitioner Tutorial
85143

86-
**Some CALM knowledge required, similar to what is covered in the Beginner tutorial.**
144+
**Some CALM knowledge required, similar to what is covered in the Beginner and Intermediate tutorials.**
145+
146+
Apply your CALM knowledge to build a complete, real-world architecture end-to-end with AI assistance:
147+
- Setting up your practitioner toolset
148+
- Understanding business context for architecture decisions
149+
- Defining and refining an initial architecture
150+
- Generating architecture documentation
151+
- Applying key takeaways for future projects
87152

88-
## Prerequisites
153+
**Time commitment:** ~2-3 hours for the complete tutorial
154+
155+
### Prerequisites
89156

90157
Before you begin, make sure you have:
91158

@@ -95,13 +162,19 @@ Before you begin, make sure you have:
95162
- **CALM AI Assistant** Copilot, Claude or KIRO AI Assistant is enabled
96163
- **calm cli** installed
97164

98-
## Skills You'll Acquire
165+
### Getting Started
166+
167+
1. **[Start with Tool Setup](./build-a-calm-architecture/tool-setup)** — Configure your practitioner environment
168+
2. **Work through each section** — They build a complete architecture from start to finish
169+
3. **Ask questions** — Join the [FINOS Architecture as Code community](https://github.com/finos/architecture-as-code/discussions)
170+
171+
### Skills You'll Acquire
99172

100173
By completing this tutorial, you'll see how to use the CALM AI Assistant to:
101174

102175
✅ **Create** complete architecture document from a business design
103176
✅ **Enhance** definition of nodes, relationships, interfaces, and metadata with organizational specific information
104-
✅ **Use** the VSCode extension for visualization
177+
✅ **Use** the VSCode extension for visualization
105178
✅ **Generate** views of the architecture
106179
✅ **Learn** best practices in working with CALM architectures
107180

‎docs/docs/tutorials/intermediate/08-controls.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
---
2+
id: 08-controls
3+
title: "Controls for Non-Functional Requirements"
4+
sidebar_position: 2
5+
---
6+
7+
# Controls for Non-Functional Requirements
8+
9+
🟡 **Difficulty:** Intermediate | ⏱️ **Time:** 30-45 minutes
10+
11+
## Overview
12+
13+
Document security, performance, and compliance requirements using CALM's controls feature to capture non-functional requirements (NFRs).
14+
15+
## Learning Objectives
16+
17+
By the end of this tutorial, you will:
18+
- Understand the structure of CALM controls
19+
- Add architecture-level and node-level controls
20+
- Distinguish between inline `config` and external `config-url` implementations
21+
- Know which control domains are available (security, compliance, performance, operational)
22+
23+
## Prerequisites
24+
25+
Complete the [Beginner Tutorials](../beginner/07-complete-architecture) section first. You will need your `architectures/ecommerce-platform.json` from the [Build a Complete Architecture](../beginner/07-complete-architecture) lesson.
26+
27+
## Step-by-Step Guide
28+
29+
### 1. Understand Controls
30+
31+
Controls in CALM consist of:
32+
- **Domain key:** Category (e.g., `security`, `compliance`, `performance`, `operational`)
33+
- **Description:** What the control addresses
34+
- **Requirements:** Array of requirement specifications with:
35+
- `requirement-url`: Link to the requirement definition
36+
- Plus ONE of:
37+
- `config-url`: Link to external configuration, OR
38+
- `config`: Inline configuration object
39+
40+
> **Important:** Each requirement MUST specify how it's implemented — either via `config-url` or inline `config`. This enforces that controls are not just declared but actually configured.
41+
42+
Controls can be applied at multiple levels:
43+
- **Architecture level:** Apply to the entire system
44+
- **Node level:** Apply to specific components
45+
- **Relationship level:** Apply to specific connections between components
46+
- **Flow level:** Apply to business processes and data flows
47+
48+
### 2. Add an Architecture-Level Security Control
49+
50+
Open your `architectures/ecommerce-platform.json` from the [Build a Complete Architecture](../beginner/07-complete-architecture) lesson.
51+
52+
**Prompt:**
53+
```text
54+
Add a controls section at the top level of architectures/ecommerce-platform.json
55+
56+
Add a "security" control with:
57+
- description: "Data encryption and secure communication requirements"
58+
- requirements array with two items:
59+
1. requirement-url: "https://internal-policy.example.com/security/encryption-at-rest"
60+
config (inline): { "algorithm": "AES-256", "scope": "all-data-stores" }
61+
2. requirement-url: "https://internal-policy.example.com/security/tls-1-3-minimum"
62+
config-url: "https://configs.example.com/security/tls-config.yaml"
63+
64+
Place it after the metadata section and before nodes.
65+
```
66+
67+
### 3. Add an Architecture-Level Performance Control
68+
69+
**Prompt:**
70+
```text
71+
Add a "performance" control at the architecture level of architectures/ecommerce-platform.json
72+
73+
Add with:
74+
- description: "System-wide performance and scalability requirements"
75+
- requirements array with two items:
76+
1. requirement-url: "https://internal-policy.example.com/performance/response-time-sla"
77+
config (inline): { "p99-latency-ms": 200, "p95-latency-ms": 100 }
78+
2. requirement-url: "https://internal-policy.example.com/performance/availability-target"
79+
config-url: "https://configs.example.com/infra/ha-config.yaml"
80+
81+
Place it alongside the security control in the controls section.
82+
```
83+
84+
### 4. Add a Node-Level Compliance Control
85+
86+
Add a control to the `payment-service` node.
87+
88+
**Prompt:**
89+
```text
90+
Add a controls section to the payment-service node in architectures/ecommerce-platform.json
91+
92+
Add a "compliance" control with:
93+
- description: "PCI-DSS compliance for payment processing"
94+
- requirements array with one item:
95+
- requirement-url: "https://www.pcisecuritystandards.org/documents/PCI-DSS-v4.0"
96+
config-url: "https://configs.example.com/compliance/pci-dss-config.json"
97+
```
98+
99+
### 5. Add a Node-Level Performance Control
100+
101+
Add a performance control to the `api-gateway` node.
102+
103+
**Prompt:**
104+
```text
105+
Add a controls section to the api-gateway node in architectures/ecommerce-platform.json
106+
107+
Add a "performance" control with:
108+
- description: "API Gateway rate limiting and caching requirements"
109+
- requirements array with two items:
110+
1. requirement-url: "https://internal-policy.example.com/performance/rate-limiting"
111+
config-url: "https://configs.example.com/gateway/rate-limits.yaml"
112+
2. requirement-url: "https://internal-policy.example.com/performance/caching-policy"
113+
config (inline): { "default-ttl-seconds": 300, "cache-control": "private" }
114+
```
115+
116+
### 6. Validate
117+
118+
```bash
119+
calm validate -a architectures/ecommerce-platform.json
120+
```
121+
122+
Should pass! ✅
123+
124+
Now is a good time to use git to snapshot your progress. Stage your changes and commit them with a meaningful message before moving on.
125+
126+
## Key Concepts
127+
128+
### Control Domains
129+
130+
| Domain | Purpose | Example Requirements |
131+
|--------|---------|---------------------|
132+
| `security` | Data protection, access control | Encryption, TLS, authentication |
133+
| `compliance` | Regulatory adherence | PCI-DSS, GDPR, SOC2 |
134+
| `performance` | Non-functional requirements | SLAs, rate limits, availability |
135+
| `operational` | Runtime concerns | Logging, monitoring, backup |
136+
137+
### Inline Config vs Config URL
138+
139+
```json
140+
{
141+
"requirements": [
142+
{
143+
"requirement-url": "https://policy.example.com/encryption",
144+
"config": { "algorithm": "AES-256", "scope": "all-data-stores" }
145+
},
146+
{
147+
"requirement-url": "https://policy.example.com/tls",
148+
"config-url": "https://configs.example.com/tls-config.yaml"
149+
}
150+
]
151+
}
152+
```
153+
154+
Use **inline `config`** for simple, self-contained settings. Use **`config-url`** when configuration is managed externally or is too complex to inline.
155+
156+
### Multi-Level Controls
157+
158+
Controls can be placed at four levels:
159+
- **Architecture level** — system-wide requirements
160+
- **Node level** — component-specific requirements
161+
- **Relationship level** — connection-specific requirements
162+
- **Flow level** — business-process-specific requirements
163+
164+
## Resources
165+
166+
- [CALM Controls Schema](https://github.com/finos/architecture-as-code/blob/main/calm/release/1.2/meta/control.json)
167+
- [PCI-DSS Standards](https://www.pcisecuritystandards.org/)
168+
169+
## Next Steps
170+
171+
In the [next tutorial](./09-business-flows), you'll model business flows that trace how business processes traverse your architecture!

0 commit comments

Comments
 (0)
⚡