finos / finos/architecture-as-code

Add End-to-End Examples for CALM Standards, Patterns, and Validation

Open
#2,985 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
399
Forks
138
Avg merge
2d 14h
Merged PRs (30d)
37

Description

## Feature Proposal

### Target Project:

FINOS `architecture-as-code` monorepo.

The existing architectures in the following locations are candidates for this work:

- `calm/architectures`
- `examples`, including the **FluxNova architectures**
- `conferences/qcon`

The repository's existing **CALM tutorials** should also be considered when designing the feature. The tutorials already demonstrate CALM concepts and workflows and should be reused or complemented rather than unnecessarily duplicating existing instructional material.

The feature may use architectures from **one or both candidate locations**, depending on which provide the clearest examples for demonstrating standards, patterns, and validation.

### Description of Feature:

Enhance the existing CALM examples and learning experience with practical, end-to-end demonstrations of how **standards and patterns can be applied to architectures and evaluated using CALM validation**.

The repository already contains CALM tutorials that provide useful demonstrations of CALM capabilities. This feature should build upon those tutorials while addressing an important limitation: the tutorials primarily operate on **local files contained within the repository or local development environment**.

The proposed feature should demonstrate a more realistic usage model in which CALM architectures, standards, or patterns can be obtained from **web-accessible repositories** and used as part of the validation workflow.

Potential sources include public repositories and resources hosted through FINOS, such as those available through `finos.org`, as well as other publicly accessible locations appropriate for CALM artifacts.

The examples should illustrate a workflow such as:

**Discover/Retrieve Architecture and Standards → Apply Standards and Patterns → Validate → Review Results**

This would complement the existing local-file tutorials by demonstrating how CALM artifacts can participate in a broader ecosystem where architectures, standards, and patterns are published and reused.

The examples should show users:

- How a CALM standard can express expectations for an architecture.
- How a CALM pattern can describe an expected architectural structure or practice.
- How standards and patterns relate to an existing CALM architecture.
- How architectures, standards, or patterns can be obtained from web-accessible repositories.
- How remotely hosted CALM artifacts can be incorporated into a validation workflow.
- How validation evaluates an architecture against applicable standards and patterns.
- What successful validation looks like.
- What happens when an architecture does not satisfy an applicable standard or pattern.
- How validation findings can be understood and addressed.

The goal is to provide **clear, executable examples demonstrating how CALM standards, patterns, and validation work together using both existing CALM examples and web-accessible CALM resources**.

### User Stories:

- As an **architect**, I want to validate an architecture using standards or patterns retrieved from a web-accessible repository so that I can understand how CALM can support reusable architecture assets.

- As a **developer**, I want examples of successful and unsuccessful validation so that I can understand how architecture changes affect validation results.

- As a **CALM adopter**, I want examples that demonstrate both local and web-based CALM resources so that I can understand how CALM could be used across repositories and organizational boundaries.

### Current Limitations:

The repository already contains CALM tutorials that demonstrate important CALM concepts and provide a useful starting point for users.

However, the existing tutorials primarily use **local files** as the source for architectures and other CALM artifacts. The closest that comes to the intent of this features is scenario 3 in `conferences/qcon`. The `calm validate` commands are contained in a shell script, which may hinder a new user's understanding.

This makes the tutorials effective for learning individual CALM capabilities but does not fully demonstrate how CALM could be used when architecture assets are published and shared through web-accessible repositories.

The recently available `hub.calm.finos.org` CALM Hub read-only repo does not contain full set of CALM artifacts that can be used to demonstrate how `calm validate` would be used with web-based repository.

### Proposed Implementation:

Review the existing CALM tutorials and identify opportunities to **extend or complement them** rather than duplicating their existing functionality.

Also review the existing architectures under:

- `calm/architectures`
- `examples`
- `conferences/qcon`
- `hub.calm.finos.org`

These architectures should be treated as candidates. The feature may use architectures from either location or both.

In addition, identify suitable **web-accessible repositories containing CALM-related resources**, preferably using public FINOS-hosted resources where appropriate.

The implementation does not require all three artifact types to be remotely hosted. A useful example could demonstrate combinations such as:

```text
Remote Architecture + Local Standard/Pattern

Local Architecture + Remote Standard/Pattern

Remote Architecture + Remote Standard/Pattern
```

#### API Changes

No API changes are assumed as part of this feature.

#### Data Model Changes

No CALM schema or data model changes are expected.

#### Dependencies on Other Components

The implementation will depend on existing CALM schemas, standards and patterns capabilities, validation tooling, and any existing support for resolving web-accessible CALM resources.

The examples may also depend on publicly accessible FINOS-hosted resources.

Where remote resources are used, consideration should be given to:

- Stable URLs.
- Versioned resources.
- Availability.
- Reproducibility.
- Network failures.
- Changes to remotely hosted content.

### Alternatives Considered:

**Continue using only local files**

This maintains the simplicity and reproducibility of the existing tutorial approach but does not demonstrate how CALM artifacts can be shared and reused through web-accessible repositories.

Local examples should remain useful for introductory learning, while this feature should demonstrate the next step.

**Replace the existing tutorials**

The existing tutorials already provide useful introductory material and should not be replaced.

The proposed examples should instead complement them and provide a progression toward more realistic usage scenarios.

**Require all CALM artifacts to be remotely hosted**

This would strongly demonstrate distributed CALM resources but introduces unnecessary complexity.

The feature should be able to demonstrate a mixture of local and remote architectures, standards, and patterns where that provides a clearer example.

**Require architectures from both `calm/architectures` and `examples`**

Directory coverage is not the objective.

Both locations should be evaluated as candidate sources, with the implementation selecting whichever architecture or architectures best demonstrate the intended capabilities.

**Create new architectures specifically for the examples**

Purpose-built architectures could simplify the demonstrations but would introduce additional architecture models when suitable examples may already exist.

Existing architectures should therefore be preferred where practical.

### Testing Strategy:

Manual testing should confirm that the examples accurately demonstrate standards, patterns, remote resources, and validation.

### Documentation Requirements:

If Tutorials minimal documentation.

### Implementation Checklist:

- [ ] Tutorial available

### Additional Context:

The existing tutorials provide the foundation for learning CALM using local resources. This feature should complement those tutorials by demonstrating a more realistic model in which **architectures, standards, and patterns can be published, discovered, referenced, and reused through web-accessible repositories**.

The primary goal is to give users concrete, executable examples showing how **CALM standards, patterns, web-accessible resources, and validation work together**, while building upon the learning experience already provided by the CALM tutorials.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the existing CALM tutorials, `calm/architectures`, `examples` including FluxNova, `conferences/qcon` scenario 3, and `hub.calm.finos.org`; inspect the QCon shell script and its `calm validate` commands first. Done means executable examples show local and web-accessible architectures, standards, and patterns, including successful and failing validation with understandable results.

Written by the indexing model from the issue text.

Assessment

Tech stack
shell
Domain
documentation, testing-qa
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.