diff --git a/README.md b/README.md index 8e3f2c2a3..f46238913 100644 --- a/README.md +++ b/README.md @@ -26,11 +26,11 @@ Transform the landscape of **Application Architecture** by bridging the **gap** Documenting Application Architecture with diagram drawing tools like Visio, Miro, LucidCharts etc., while popular and often effective, poses several key (genetically unsolved) problems that stem from the inherent limitations of these tools and the complex nature of software architecture. Here are some of these problems -- **Complexity Management**: Modern Application Architecture can become very complex, with many layers, setvices, components and technologies. Diagrams can get too crowded and hard to understand, making it **hard to clearly express the Architecture**. +- **Complexity Management**: Modern Application Architecture can become very complex, with many layers, services, components and technologies. Diagrams can get too crowded and hard to understand, making it **hard to clearly express the Architecture**. - **Dynamic and Evolving Architectures**: Architecture structures change over time. Manually updating diagrams is slow and error-prone, causing **documentation** to become **inaccurate** and **outdated**. -- **Architecture Model - Code gap**: There is a mismatch between diagraming and coding tools. Changes in code don't automatically update diagrams, causing **inconsistencies** between **Architecture representation** and the **actual code**. +- **Architecture Model - Code gap**: There is a mismatch between diagramming and coding tools. Changes in code don't automatically update diagrams, causing **inconsistencies** between **Architecture representation** and the **actual code**. - **Standardisation and Consistency**: Different diagramming tools and different diagram authors use different symbols and styles, leading to **inconsistent documentation**. This can **confuse** and **slow down communication among team members**. @@ -40,9 +40,9 @@ Documenting Application Architecture with diagram drawing tools like Visio, Miro - **Interoperability and Exporting**: Sharing diagrams between different tools or platforms can lose details, as there's no common standard for diagram formats. This makes it **harder to share and collaborate** on architectural designs. -- **Architecture Analysis**: Diagraming tools often provide **static** representations that lack interactive capabilities for in-depth analysis. This limitation makes it **difficult to understand** how changes in one component might affect others, leading to **inefficient planning** and potential oversights in managing complex systems. +- **Architecture Analysis**: Diagramming tools often provide **static** representations that lack interactive capabilities for in-depth analysis. This limitation makes it **difficult to understand** how changes in one component might affect others, leading to **inefficient planning** and potential oversights in managing complex systems. -- **Business Process Modelling**: Diagraming tools require users to create **new static diagrams** each time they want to model **new interactions** between different structures, their behaviors, and actors, such as **business processes**. This method leads to significant **duplication** of structures and behaviors across diagrams, making it **cumbersome** to **update**, **maintain**, and **understand** the holistic view of the system. +- **Business Process Modelling**: Diagrmaming tools require users to create **new static diagrams** each time they want to model **new interactions** between different structures, their behaviours, and actors, such as **business processes**. This method leads to significant **duplication** of structures and behaviours across diagrams, making it **cumbersome** to **update**, **maintain**, and **understand** the holistic view of the system. ## Solutions 💡 @@ -51,17 +51,17 @@ The table below maps Problems to Possible Solutions and C4InterFlow Capabilities | ❗ Problem | 💡 Proposed solution | 🌟 C4Interflow Capability | |---------|-------------------|------------------------| | **Complexity Management** | **Modular Architecture Definitions**: define **architecture in code**, so that it can be modularised into smaller, manageable components, making complex systems easier to understand and manage. | Definition of **Architecture as Code** in **C#** or **YAML** at any level of modularity e.g. Software System, Container, Component, Interface etc. | -| **Complexity Management** | **Adaptive Visualization**: allow the user to **adjust the number of structures and their relationships** (boxes and lines) they see, and at what **level of detail** when they visualise Application Architecture. Manage complexity by displaying only relevant informationcan based on the user's **context**, **focus**, or specific **task at hand**. | Generation of Architecture diagrams of different **Types** (e.g. C4, C4 Static and Sequence), of different **Scopes** (e.g. all Software Systems, Software System, Container, Interface(s), Business Process etc.) and at different **Levels of Details** (e.g. Context, Container and Component) | +| **Complexity Management** | **Adaptive Visualization**: allow the user to **adjust the number of structures and their relationships** (boxes and lines) they see, and at what **level of detail**, when they visualise Application Architecture. Manage complexity by displaying only relevant information based on the user's **context**, **focus**, or specific **task at hand**. | Generation of Architecture diagrams of different **Types** (e.g. C4, C4 Static and Sequence), of different **Scopes** (e.g. all Software Systems, Software System, Container, Interface(s), Business Process etc.) and at different **Levels of Details** (e.g. Context, Container and Component) | | **Dynamic and Evolving Architectures** | **Continuous Integration/Continuous Deployment (CI/CD) for Architecture**: implement of CI/CD pipelines for architecture code, managing evolving architecture through automated integration, and deployment processes. | Using **Command Line Interface** (CLI) in CI/CD pipelines for automating AaC **generation**, AaC **querying** and **diagrams** and other documentation **generation**| -| **Architecture Model - Code gap** | **Code-driven Architecture and Diangams generation**: generate architecture diagrams directly from metadata in the codebase, using code analysis and other techniques. | Automatic generation of Architecture as Code in **C#** or **YAML** from **.NET (C#) source code**. Extensible C4InterFlow architecture allows generation of Architecture as Code from codebases in **other languages** as well as from **Infrastructure as Code** (IaC) | +| **Architecture Model - Code gap** | **Code-driven Architecture and Diagrams generation**: generate architecture diagrams directly from metadata in the codebase, using code analysis and other techniques. | Automatic generation of Architecture as Code in **C#** or **YAML** from **.NET (C#) source code**. Extensible C4InterFlow architecture allows generation of Architecture as Code from codebases in **other languages** as well as from **Infrastructure as Code** (IaC) | | **Standardization and Consistency** | **Architecture Domain-Specific Languages (DSLs)**: create standardized DSLs for defining architectures, ensuring **consistency** in how architectures are described and understood across tools and teams. | Use C4InterFlow **Architecture as Code DSL**, inspired by C4 Model and ArchiMate, to express architecture **Structures** and **Behaviours** in **C#** and **YAML** | | **Standardization and Consistency** | **Adopt Standards for Diagramming**: work towards a **widely adopted standard(s)** for software architecture diagramming that includes symbols, notation, and abstraction levels, similar to UML. | Automatic generation of **C4 Model** and UML **Sequence** diagrams using a single **Visualisation Engine** that guaranties **consistency** in visual architecture represenattions | | **Duplication** | **Architecture Model driven visualisation**: allows for **generation** of architecture diagrams for different view points from a single **Architecture Model** | Create multiple architecture views by **querying** Architecture as Code to find **relevant** Structures and Behaviours (Interfaces) and generating diagrams using **query results** | -| **Collaboration and Version Control** | **Architecture Catalog**: use it as a collaborative platform where teams can contribute, share, and discuss architectural components and patterns. | **Excel Architecture Catalogue** template with **validation** and **CSV export** Macro. Automatic **generation** of Architecture as Code in **C#** or **YAML** form **CSV Architecture Catalogue** | +| **Collaboration and Version Control** | **Architecture Catalog**: use it as a collaborative platform where teams can contribute, share, and discuss architectural structures and their relationships. | **Excel Architecture Catalogue** template with **validation** and **CSV export** Macro. Automatic **generation** of Architecture as Code in **C#** or **YAML** form **CSV Architecture Catalogue** | | **Collaboration and Version Control** | **Version-Controlled Architecture Repositories**: store architecture code in version-controlled repositories, enabling collaborative editing, branching, and merging, similar to how source code is managed. | Storing **Architecture as Code** in **C#** or **YAML** in **version-controlled** repositories e.g. Git | | **Interoperability and Exporting** | **Exportable and Importable Code and Diagram Formats**: Ensure architecture code and diagrams are written/published in formats that are easily exportable and importable across different tools and platforms, facilitating interoperability. | **Architecture as Code** can be written/generated in **YAML** format (JSON is coming soon). **Diagrams** can be generated in a variety of formats including **Plant UML** (.puml), **SVG**, **PNG** and **Markdown** (.md files with embedded PNG diagrams). With a bit of additional **custom automation**, these diagrams can be published to other platforms e.g. **GitHub Pages**, **Confluence** etc. | -| **Architecture Analysis** | **Query Language for Architecture**: Develop (or adopt existing) query language specifically for **Architecture as Code** or **Architecture Catalogue**. Users could use this language to ask complex questions about dependencies, impacts, and architecture dynamics, with the tools parsing the architecture to provide results. | Advanced **querying** of Architecture as Code, with support for **JSON Path**-like syntax, to uncover dependencies or to perform any other AaC analysis. **Custom diagram generation** based on query results | -| **Business Process Modelling** | **Business Process Domain-Specific Languages (DSLs)**: Develop a **Business Process modelling language** that allows for **dynamic linking** between different architectural **structures** and their **behaviors**. This would enable users to define a **single instance** of a structure or behavior that can be **referenced** across multiple Business Processes, ensuring **consistency** and **reducing duplication**. | Describe **Business Process as Code** in **C#** or **YAML** through **Activities** and **Flows** utilising existing **Interfaces**. Add and Edit **Business Processes** via the **Excel Architecture Catalogue**. C4InterFlow can **automatically generate** Business Process as Code in C# or YAML from Excel/CSV Architecture Catalogue | +| **Architecture Analysis** | **Query Language for Architecture**: Develop (or adopt existing) **query** language specifically for **Architecture as Code** or **Architecture Catalogue**. Users could use this language to ask complex questions about **dependencies**, **impact of changes**, and **architecture dynamics**, with the tools parsing the architecture to provide results. | Advanced **querying** of Architecture as Code, with support for **JSON Path**-like syntax, to uncover dependencies or to perform any other AaC analysis. **Custom diagram generation** based on query results | +| **Business Process Modelling** | **Business Process Domain-Specific Languages (DSLs)**: Develop a **Business Process modelling language** that allows for **dynamic linking** between different architectural **structures** and their **behaviour**. This would enable users to define a **single instance** of a structure or behaviours that can be **referenced** across multiple Business Processes, ensuring **consistency** and **reducing duplication**. | Describe **Business Process as Code** in **C#** or **YAML** through **Activities** and **Flows** utilising existing **Interfaces**. Add and Edit **Business Processes** via the **Excel Architecture Catalogue**. C4InterFlow can **automatically generate** Business Process as Code in C# or YAML from Excel/CSV Architecture Catalogue | ## Capabilities map