finos / finos/architecture-as-code
Proposal to add a rich Use Cases page to docs
- Dominant language
- TypeScript
- Stars
- 399
- Forks
- 138
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 38
Description
## Feature Proposal
### Target Project:
**CALM Documentation** (contained within the `docs` directory of the `finos/architecture-as-code` repository).
### Description of Feature:
I propose adding a new top-level section to the [calm.finos.org](https://calm.finos.org) documentation titled **"Use Cases"**.
As the CALM (Common Architecture Language Model) specification matures, there is an increasing need to showcase practical applications and community prototypes. This section will serve as a curated gallery for illustrations and integrations (e.g., combining CALM with security platforms or cloud frameworks), helping users move from theoretical understanding to practical implementation.
### User Stories:
* **For a Software Architect**, they might want to see real-world examples and prototypes of CALM in action so that I can understand how to apply it to my own infrastructure challenges.
* **As a Community Contributor**, they might want a designated place to link my CALM-related prototypes (like the CALM-MISP integration) so that others can benefit from and build upon my work.
* **As FINOS Project Maintainer**, they might want to see how CALM can interact with other open source projects in the ecosystem.
### Current Limitations:
New potential CALM adopters often don't understand the wide breadth of potential CALM-usages, and it would be good to have a single place to link to related implementations (e.g. hackathon projects).
### Proposed Implementation:
* **Navigation Update:** Add "Use Cases" to the left-hand sidebar navigation.
* **Content Structure:** Create a new directory `/docs/use-cases/`. Each use case will be a standalone markdown file.
* **Standardized Format:** Each use case entry should include:
* A brief write-up of the problem/scenario.
* How CALM is utilized.
* Links to relevant external GitHub repositories.
* **Initial Content:** Seed the section with the [calm-misp](https://github.com/denisurusov/calm-misp) prototype as a first example.
### Alternatives Considered:
* **"Related Projects" naming:** Decided on "Use Cases" as it is more descriptive of functional applications.
* **A single `prototypes.md` in the root:** Rejected in favor of the documentation site to ensure better visibility, searchability, and a better user experience for non-developers.
### Testing Strategy:
* **Docusaurus Build:** Ensure the site builds without errors with the new directory structure.
* **Broken Link Check:** Verify all outbound links to external prototypes are valid.
* **UI Review:** Ensure the sidebar renders correctly and is logically ordered.
### Documentation Requirements:
* Update the project's contribution guide to explain how users can submit their own use cases via Pull Request.
### Implementation Checklist:
- [ ] Design/Naming reviewed and approved by maintainers
- [ ] Create `/docs/use-cases/` directory
- [ ] Update sidebar configuration (e.g., `sidebars.js`)
- [ ] Add initial use case: CALM + MISP integration
- [ ] Documentation build and deployment verified
- [ ] Contribution guidelines updated for new use case submissions
### Additional Context:
This request is based on community discussions regarding the need to bridge the gap between architectural intent and implementation. Below is a screenshot of the proposed location in the navigation:

*(Note: Referencing the existing navigation structure: Introduction > Core Concepts > Working with CALM > **Use Cases**)*
```
Contributor guide
Assessment
This issue has not been assessed yet.