Setup docs (#3)

* Add docs project using Docusaurus
* Setup Action to deploy docs to GitHub Pages
* Rename the core schema to 'core' to make it clearly identifable as we add domain schemas.
* Rename schema to exclude version as we'll use tags to manage the versioning

.github/workflows/docs-deploy.yml

@@ -0,0 +1,46 @@
+name: Build Docs for GitHub Pages
+
+on:
+  # Triggers the workflow on push or pull request events but only for the "main" branch
+  push:
+    branches: [ "main" ]
+    paths: [ "docs/**" ]
+  pull_request:
+    branches: [ "main" ]
+    paths: [ "docs/**" ]
+
+jobs:
+  deploy:
+    name: Build for GitHub Pages
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: npm
+          cache-dependency-path: ./docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+      - name: Build website
+        run: npm run build
+
+      # Popular action to deploy to GitHub Pages:
+      # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # Build output to publish to the `gh-pages` branch:
+          publish_dir: ./docs/build
+          # The following lines assign commit authorship to the official
+          # GH-Actions bot for deploys to `gh-pages` branch:
+          # https://github.com/actions/checkout/issues/13#issuecomment-724415212
+          # The GH actions bot is used by default if you didn't specify the two fields.
+          # You can swap them out with your own user credentials.
+          user_name: github-actions[bot]
+          user_email: 41898282+github-actions[bot]@users.noreply.github.com

README.md

@@ -2,11 +2,11 @@
 
 # Architecture as Code
 
-"Architecture as Code" (AasC) aims to devise and manage software architecture via a readable and version-controlled
+**Architecture as Code (AasC)** aims to devise and manage software architecture via a readable and version-controlled
 codebase, fostering a robust understanding, efficient development, and seamless maintenance of complex software
 architectures.
 
-This repository contains the AasC manifest specification, as well as capabilities being built to utilize the
+This repository contains the Common Architecture Language Model (CALM) Specification, as well as capabilities being built to utilize the
 specification. This page lists the domains and capabilities being built by the official AasC community.
 
 Whilst others are welcome to build their own capabilities, away from the AasC monorepo, we encourage you to join the
@@ -16,7 +16,8 @@ your project.
 
 ## Projects
 
-* [AasC Manifest Specification](./manifest/README.md)
+* [Common Architecture Language Model](./calm)
+* [Docs](./docs)
 
 ## Contributing
 

manifest/schema/aasc-schema-0.1.json → calm/schema/core.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "id": "http://devops.finos.org/devops-automation/aasc/0.1",
-  "title": "Architecture As Code 0.1",
+  "id": "http://devops.finos.org/devops-automation/calm/core/0.0.1",
+  "title": "Common Architecture Language Model",
   "type": "object",
   "defs": {
     "definitions": {

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/calm/intro.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 1
+slug: /
+---
+
+# CALM
+

docs/community/intro.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 1
+slug: /
+---
+
+# Community
+

docs/docs/calm-core/example.md

@@ -0,0 +1,24 @@
+---
+sidebar_position: 2
+slug: /calm-core/example
+---
+
+# Getting Started
+As we discussed in the [Fast Track](/#fast-track) the CALM Core Manifest is structured around **nodes** and **relationships**. In this section we're going to look at how to model a super simple three tier application using the CALM Core Manifest.
+
+Let's look at the following simple C4 Container Diagram.
+
+```mermaid
+    C4Container
+    
+    Container_Boundary(c1, "Three Tier App") {
+        Container(spa, "Single-Page App", "JavaScript, Angular", "Exposes amazing features to customers via their web browser")
+        Container(web_app, "Web Application", "Java, Spring MVC", "Delivers the amazing features of the application to the Single-Page App")
+        ContainerDb(database, "Database", "SQL Database", "Stores user info, and details of the users interactions")
+    }
+
+    Rel(web_app, spa, "Delivers")
+    Rel_Back(database, web_app, "Reads from and writes to", "JDBC")
+    
+    UpdateLayoutConfig($c4ShapeInRow="1", $c4BoundaryInRow="1")
+```

docs/docs/calm-core/index.md

@@ -0,0 +1,9 @@
+---
+sidebar_position: 2
+title: CALM Core
+slug: /calm-core
+---
+
+# Setup
+To be able to use the CALM Manifest you need to ensure you have the JSON Schemas configured in your IDE. These instructions will assume you're using IntelliJ IDEA.
+

docs/docs/domains/index.md

@@ -0,0 +1,6 @@
+---
+sidebar_position: 3
+title: Domains
+slug: /domains
+---
+

docs/docs/intro.md

@@ -0,0 +1,87 @@
+---
+sidebar_position: 1
+slug: /
+---
+
+# Introduction
+
+The **Architecture as Code** community publishes and maintains the **Common Architecture Language Model (CALM) Manifest** and related capabilities, which are tools built on top of the CALM framework to support System Architects in modelling and managing the architecture of a system. 
+
+But more than that, our capabilities enable you to bring your architecture to life, by generating code and documentation and by providing tools to ensure that what you said you'd build is what you actually built. 
+
+## Fast Track
+
+Understand Architecture as Code in **5 minutes**:
+
+### Keep CALM and Model Your Architecture
+
+**CALM** is a collection of JSON Schemas that enable you to model your system architecture in a structured way. The core schema is very simple and consists of just 2 collections of elements **nodes** and **relationships**. 
+
+```js showLineNumbers
+{
+  "nodes": [],
+  "relationships": []
+}
+```
+
+### Nodes 
+**Nodes** tell us what the system is made of. 
+
+```js showLineNumbers
+{
+  "nodes": [
+    {
+      "uniqueId": "web-client",
+      "type": "webclient",
+      "name": "Web  Client",
+      "description": "Browser based web interface",
+      "data-classification": "Confidential",
+      "run-as": "user"
+    },
+    {
+      "uniqueId": "some-service",
+      "type": "service",
+      "name": "An Important Service",
+      "description": "Server process which does something fascinating",
+      "data-classification": "Confidential",
+      "run-as": "systemId"
+    }
+  ]
+}
+```
+
+You will notice that there is no structure applied in the **nodes** collection, it purely lists out anything you may consider drawing as a 'box' in a traditional architecture diagram. That includes people, systems, networks, services, databases, etc. which may be at different logical levels in your architecture.
+
+Depending on the type of node the schema requires different attributes to be specified to ensure we have captured appropriate information about the node.
+
+### Relationships
+**Relationships** tell us how those things are connected.
+
+```js showLineNumbers
+{
+  "relationships": [
+    {
+      "uniqueId": "web-client-uses-some-service",
+      "type": "connects",
+      "parties": {
+        "source": "web-client",
+        "destination": "some-service"
+      },
+      "protocol": "HTTPS",
+      "authentication": "OAuth2"
+    }
+  ]
+}
+```
+
+It is the **relationships** which add the context and enable us to connect nodes or encapsulate one or more nodes within another. Depending on the type of relationship the schema requires different attributes to be set, as with the nodes, these additional details help us to enable the capabilities we build which make the model so useful.
+
+Having such a simple core schema may seem limiting, but it's actually very powerful. Having no set hierarchy enforced by the structure of the schema means we can model arbitrarily complex systems and capture multiple views of the same system in a single model. This makes it a lot easier to model real world applications rather than idealised ones.
+
+What you have seen here is just the beginning and shows you just the core schema which is deliberately kept simple. To see more about how you can make use of the **CALM** Manifest and it's supplementary domains see the [CALM](calm-core/) section.
+
+### Capabilities
+
+**Capabilities** are tools built on top of the CALM framework to support System Architects in modelling and managing the architecture of a system but also to provide the ability to bootstrap and extend you development work, perform drift detection and more.
+
+We are just beginning to build the initial capabilities based on CALM so please come back soon to see what's happening or join the [DevOps Automation Mailing List](https://devops.finos.org/docs/home#mailing-list) to be sent notifations of new releases.