scope42 / scope42 Goto Github PK

View Code? Open in Web Editor NEW

8.0 2.0 2.0 18.98 MB

🎯 Improve your software architecture with precision!

Home Page: https://scope42.org

License: GNU General Public License v3.0

TypeScript 94.14% CSS 1.05% HTML 1.34% JavaScript 3.47%

aim42 architecture arc42 docs-as-code webapp scope42

scope42's Introduction

Improve your software architecture with precision!

This tool helps you to keep track of issues, arising risks and possible improvements of your existing architecture. The terminology and concepts are based on aim42, the Architecture Improvement Method.

scope42 is a Progressive Web App that runs entirely inside your browser. Click the link below to access the app.

🔗 app.scope42.org

Features

✨ Management of items with a fancy UI

Filtering • Sorting • Full text search • Learn about aim42

💑 Graphs for visualizing the relationships between items

Quick overview • Drag & Drop • Navigate

📝 Docs-as-Code principle and full data ownership

Human-readable • Check into version control • Process programatically • No vendor lock-in

title: Upgrade Spring Boot version
created: 2022-05-02T17:25:16.909Z
modified: 2022-05-02T18:09:42.952Z
status: implemented
tags:
  - backend
  - urgent
  - security
ticket: https://github.com/scope42/scope42/issues/91
description: The current version of Spring Boot upgrades dependencies to secure
  versions of Log4j.
resolves:
  - issue-3
modifies:
  - risk-1
comments:
  - author: Jane Doe
    created: 2022-05-02T17:27:17.630Z
    content: Accepted and placed into the fast lane on the board.

Want to learn more? Take a look at our introduction blog post!

Planned Features

WYSIWYG markdown editor
Support for requirements (new item type)
Support for prose documentation of existing architecture (based on arc42)
Support for media files
Customizable dashboard
Export structured data (convenience library)
Export static site
Export markdown

Badge

If you use scope42 in your project, you can add this badge to your README. This way, people visiting your repository can quickly find the architecture documentation. Simply copy the code below and change the link to point to an export (coming soon) or the workspace of your scope42 data.

[![Architecture Documentation](https://img.shields.io/badge/%F0%9F%93%96%20architecture-scope42-blue)](https://github.com/scope42/scope42/tree/main/architecture)

Tech Stack

Develop

Contributions are always welcome!

`npm start`

Runs the app in the development mode. Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits. You will also see any lint errors in the console.

`npm test`

Launches the test runner in the interactive watch mode. See the section about running tests for more information.

License

scope42 is published under the GNU General Public License v3.0.

The data model and basic concepts are based on the aim42 Method Reference by Gernot Starke and community contributors, used under CC BY-SA.

scope42 is not affiliated with aim42.

scope42's People

Contributors

Stargazers

Watchers

Forkers

fossabot mcpride

scope42's Issues

Integration of kroki

https://kroki.io/ is a server for rendering diagrams from text. Requests to external services are not optimal, but it would support a lot of diagram formats with minimal effort.

This should be opt-in and configurable, so that a private self-hosted server can be used.

This would also play together nicely with the docToolchain integration if docToolchain/docToolchain#531 gets implemented.

[Proposal] Pivot to Markdown as universal file format

Advantages:

Items can be browsed on Sites like GitHub and GitLab as is
Editing of files outside of scope42 can be done with any Markdown editor
markdownlint can be applied easily
Enables Markdown processing with things like remark

Disadvantages:

Parsing is harder to implement and propably needs to become more tolerant
Files can not be processed with simple YAML tooling anymore, it basically can only be done with our libraries, if you need the model
#29 would become impossible because it would break links
This is not sufficient for exporting. The Markdown needs to be processed if things like scripting are used.

Additional considerations

We may want to stick with YAML for a 1.0.0 and decide on this later. An automatic migration is trivial because we need Model->Markdown serializer anyways.

Finalize @scope/data

Footnote links in Markdown are converted to external links

Re-enable React strict mode

This needs to be resolved first: plotly/react-cytoscapejs#106

Support for admonitions (info, warning, etc. boxes) in Markdown

GitHub has a Functionality for this based on Blockquotes: community/community#16925

Warning Example

Note Example

There is also this, based on the generic directive syntax: https://www.npmjs.com/package/remark-admonitions

We could implement the same directives with Ant Design alerts.

Create importer for Markdown ADRs

This is commonly used: https://github.com/adr/madr
To aid adoption, we should provide an importer that does as much automatically as possible.

Relies on #215.

Consider switching to Vite

I recently switched from NextJS to CRA as per ADR-0004. Startup time is somewhat annoying now. We may want to try switching to Vite when the MVP is established.

We need a little bit of migration, see https://medium.com/codex/you-should-choose-vite-over-cra-for-react-apps-heres-why-47e2e7381d13

Improve landing UX

Get rid of "splash screen" style landing page.
Always show basic layout (header, navigation, footer). Navigation is partly disabled if there is no workspace present.
If on /, show introduction with an embedded workspace picker.
If item list/details page, show directory picker.
Static pages like "about" work without workspace.

App doesn't render anymore

The current version of the app on main just displays an empty page. There is an error in the React initialization.
Probably caused by #269 🤔

Only load full item content when needed

Currently, the whole workspace is loaded into memory at once. For some item properties this is needed because they are displayed in many places. The majority of the content, however, is typically only displayed on the item details page.

For large workspaces, it may become necessary to only load the full item content when it is actually needed.

This is especially relevant for the static site export. There, the workspace is not loaded from local disk but transferred over the network.

One problem is populating the full-text search index. Maybe we can at least do this lazily (and cache it somehow?).

There is no style for markdown blockquotes

The <blockquote> HTML tag is rendered but it looks the same as any other text.

Create a formal specification of the data format

It should reside in a seperate repository so we can impose semantic versioning on the specification.

[Proposal] Improve file names

Current file names have the form issue-42.yml which directly relates to the item ID.

Disadvantages:

Does not give a clue about the file content beside the item type
Files are not sorted correctly because there are no leading zeroes

Proposal: file names of the form 00042-slug-form-of-the-title.yml. The ID for references would still be issue-42 and can be derived from the file name and directory. This would also allow for shorter refs like "imp" (improvement) and "req" (requirement).

Disadvantages:

ID is not directly visible from the file name
IDs are not automatically unique, we have to verify this
If the title changes, the slug may not be suitable anymore. I think we should not provide a UI for editing slugs for now. They can always be edited manually if desired. This would also not break refs because we use IDs for this.

(Related to #11)

Embed code from file

This would for example be helpful for embedding mermaid diagrams from a file.

Possible solutions:

A custom directive
Use systax of https://github.com/zakhenry/embedme. It would be cool to use this library directly but it currently has no abstraction for the file system.

Relation form fields should use full-text search

Currently, this is a custom-implemented select box. It looks different from the Crtl+K suggestions. The matching is very rudementary, for example typing an item ID doesn't work.

We need to be able to limit the item types and search by only title and ID (or boost them?). This means we probably need to switch from Index to Document in Flexsearch.

Convert our ADRs to scope42 format

Currently, we have some Markdown ADRs. These sould be converted to scope42.

We could do this after #223 but it may take a while.

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Rate-Limited

These updates are currently rate-limited. Click on a checkbox below to force their creation now.

Pending Status Checks

These updates await pending status checks. To force their creation now, click the checkbox below.

chore(deps): update dependency @tsconfig/docusaurus to v1.0.7
chore(deps): update dependency @types/wicg-file-system-access to v2020.9.8
chore(deps): update dependency @changesets/cli to v2.27.1
chore(deps): update dependency @types/node to v18.19.10
chore(deps): update dependency zod to v3.22.4

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

chore(deps): update dependency prettier to v2.8.8
chore(deps): update dependency @mdx-js/react to v3
chore(deps): update dependency antd to v5
chore(deps): update dependency mermaid to v10
chore(deps): update dependency react-hotkeys-hook to v4
Click on this checkbox to rebase all open PRs at once

Ignored or Blocked

These are blocked by an existing closed PR and will not be recreated unless you click a checkbox below.

chore(deps): update react monorepo to v18 (major) (react, react-dom)

Detected dependencies

github-actions

.github/workflows/build.yml

actions/checkout v3

actions/setup-node v3

.github/workflows/release.yml

actions/checkout v3

actions/setup-node v3

changesets/action v1

sergeysova/jq-action v2

npm

app/package.json

@ant-design/icons 5.0.1

@hookform/resolvers 2.9.11

@scope42/structured-aim42 1.0.0

@testing-library/jest-dom 5.16.5

@testing-library/react 14.0.0

@testing-library/user-event 14.4.3

@types/jest 29.4.0

@types/js-yaml 4.0.5

@types/node 18.14.6

@types/react 18.0.28

@types/react-cytoscapejs 1.2.2

@types/react-dom 18.0.11

@types/wicg-file-system-access 2020.9.5

@xinra/prettier-config 2.0.0

antd 4.24.8

antd-button-color 1.0.4

avvvatars-react 0.4.2

copyfiles 2.4.1

cytoscape 3.23.0

cytoscape-cose-bilkent 4.1.0

cytoscape-fcose 2.2.0

dayjs 1.11.7

eslint 8.35.0

flexsearch 0.7.21

html-to-react 1.5.0

immer 9.0.19

js-yaml 4.1.0

liquid-loading 1.0.0

mermaid 9.4.3

npm-run-all 4.1.5

prettier 2.8.1

react 18.2.0

react-cytoscapejs 2.0.0

react-dom 18.2.0

react-hook-form 7.43.5

react-hotkeys-hook 3.4.7

react-markdown 8.0.5

react-router-dom 6.8.2

react-scripts 5.0.1

react-syntax-highlighter 15.5.0

remark-directive 2.0.1

remark-gfm 3.0.1

scope-css 1.2.1

superjson 1.12.2

typescript 4.9.5

web-vitals 3.1.1

yaml 2.2.1

zustand 4.3.6

@types/flexsearch 0.7.3

@types/mermaid 9.1.0

@types/react-syntax-highlighter 15.5.6

ts-node 10.9.1

package.json

@changesets/cli 2.26.0

@xinra/prettier-config 2.0.0

netlify-plugin-out-of-minutes 1.1.0

turbo 1.8.3

@types/react 18.0.28

@types/react-dom 18.0.11

packages/eslint-config-scope42/package.json

eslint-plugin-prettier 4.2.1

eslint-config-prettier 8.7.0

eslint-config-turbo 0.0.9

eslint-config-react-app 7.0.1

packages/scope42-data/package.json

yaml ^2.1.3

zod ^3.19.1

@types/jest 29.4.0

@xinra/prettier-config 2.0.0

eslint 8.35.0

jest 29.5.0

prettier 2.8.1

ts-jest 29.0.5

tsup 6.6.3

typescript 4.9.5

packages/scope42-tsconfig/package.json

website/package.json

@docusaurus/core 2.3.1

@docusaurus/preset-classic 2.3.1

@mdx-js/react 1.6.22

clsx 1.2.1

prism-react-renderer 1.3.5

react 17.0.2

react-awesome-button 7.0.5

react-dom 17.0.2

@docusaurus/module-type-aliases 2.3.1

@tsconfig/docusaurus 1.0.6

docusaurus-plugin-typedoc 0.18.0

typedoc 0.23.26

typedoc-plugin-markdown 3.14.0

typescript 4.9.5

Check this box to trigger a request for Renovate to run again on this repository

Improve or replace locking

The locking mechanism has been disabled for now, see #187.

We need to find a mechanism with better UX.

Ideas:

Scanning all files for modifications in the background. This feels like it could be a performance issue, but we could try it.
When starting to edit an item, re-read that specific file and check for modifications.

Create actual releases

configure semantic-release
place version number in the app
only deploy releases

For the last point, we need to turn off automatic deployment of the main branch (basically every commit turns into a release but it would be deployed twice). We can then use an action to trigger the deployment on release: https://github.com/netlify/actions

Example Issue

Hello!

This is just an example issue. It demonstrates the functionality of the "Ticket URL" field. It is used to link you scope42 items to existing tickets in your ticketing system. If it points to a GitHub issue, the link is automatically formatted like you are used to on GitHub.

Settle data format

Try current approach in a real-life project
Use findings to improve and then commit to a stable data model
Decide on YAML vs. Markdown (with frontmatter) format -> for now, we stick with YAML and may come back to this later with #84
Implement tests to ensure stability of data format -> we will do this in connection with #214 after the 1.0.0

Concept for "risk turns into issue"

We currently have two seperate entity classes "issue" and "risk". (Not that per aim42 data model, risk inherits from issue). When a risk occurs, it becomes an issue. How do we model this?

Turning a risk into an issue is not really possible because the UID changes. We can only create a new issue that is based on the risk. We then have two options:

Delete the risk. This is a proper "turns into" with ID change but is not ideal. Especially external references to the risk are now broken.
Give the risk a status "occured" (or similar) which is inactive. This keeps references intakt. It leaves us with a bit kind of "junk" data. This is probably acceptable because letting turn a risk into an issue should be an exception and not happen often.

Release on dependency upgrades

Separate dependencies and devDependencies
Configure Renovate to commit dependencies upgrades as fix

Integrate docs into monorepo

Problem: We currently force resolution of React 18 at the repository root because otherwise the app wouldn't work. Docusaurus does not support React 18 at the moment, see facebook/docusaurus#7264. It seems to take a while until this will be solved.

We could consider switching from Docusaurus to something simpler since we did hardly customize it.

Structurizr integration

Structurizr is a very great tool for creating architecture diagrams. We should make an effort to integrate with it. There are multiple angles at which we can approach this.

Use exported diagrams. This would be possible for mermaid with #210
Embed live diagrams of Structurizr Lite. This could work similar to how Structurizr does this itself https://structurizr.com/help/documentation/diagrams. See https://structurizr.com/help/embed-iframe
Make docs exportable to Structurizr, see https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#documentation
Importer for Structurizr ADRs (maybe also exporter?)

Improve markdown rendering

Create package that implements the static export

Create a library to support programmatic processing of item files

In principle, you can already use a simple YAML parser to work with the files.
This is, however, not very convenient. A small library that enriches the data model would help with making the data more accessible.

We will start with a JavaScript (TypeScript) library and may add a JVM implementation later. Other platform would probably need to be supported by the community.

The library should somehow sit on top of the specification (#214).

Relation for marking improvements as mutually exclusive

Regularly, an issue has two or more possible improvements that are mutually exclusive. Issues may also be (partly) solved by multiple improvements that don't affect each other.

Label suggestion: excludes and excluded by. A symmetric label like mutually exclusive hides the direction (good and bad).

Maybe something less absolute like alternative to is better?

Restructure code?

https://dev.to/profydev/screaming-architecture-evolution-of-a-react-folder-structure-4g25

scope42 / scope42 Goto Github PK

scope42's Introduction

Improve your software architecture with precision!

🔗 app.scope42.org

Features

✨ Management of items with a fancy UI

💑 Graphs for visualizing the relationships between items

📝 Docs-as-Code principle and full data ownership

Planned Features

Badge

Tech Stack

Develop

npm start

npm test

License

scope42's People

Contributors

Stargazers

Watchers

Forkers

scope42's Issues

Advantages:

Disadvantages:

Additional considerations

Rate-Limited

Pending Status Checks

Open

Ignored or Blocked

Detected dependencies

Recommend Projects

Recommend Topics

Recommend Org

`npm start`

`npm test`