justmegaara/reverse-architecture-web

Reverse Architecture Turborepo

This is an official npm starter turborepo.

What's inside?

This turborepo uses npm as a package manager. It includes the following packages/apps:

Apps and Packages

• apps/restruct-app: an application for creating and managing arhitecture workspaces and projects using C4 model and Structurizr language syntax.
• apps/structurizr-preview-extensions: a Visual Studio Code extension for previewing the diagrams of a code written in Structurizr language.
• apps/structurizr-preview-webview: a React app that is hosted inside the webview of the Visual Studio Code extension.
• packages/@justmegaara/mxgraph: a TypeScript library that defines types for MXGrap vector diagrams (draw.io diagrams).
• packages/@justmegaara/graphviz-dot: a very simple and limited builder of the Graphviz graphs in dot syntax (used internally).
• packages/@monaco-editor/structurizr: a Structurizr DSL language definition types for Monaco editor.
• packages/@restruct: a set of packages with common commponents and styles for the product suite.
• packages/@structurizr/: a set of packages to work with Structurizr DSL and C4 model.
• packages/@structurizr-preview: a set of common packages shared between Visual Studio Code extension project and React webview app.
• @yjs/react: a set of components and providers to work with Yjs framework in React.
• eslint-config-custom: eslint configurations (includes eslint-config-next and eslint-config-prettier)
• tsconfig: tsconfig.jsons used throughout the monorepo

Each package/app is 100% TypeScript.

Utilities

This turborepo has some additional tools already setup for you:

• TypeScript for static type checking
• ESLint for code linting
• Prettier for code formatting

Build

To build all apps and packages, run the following command:

cd ./reverse-architecture-web
turbo run build

Develop

To develop all apps and packages, run the following command:

cd ./reverse-architecture-web
turbo run dev

Remote Caching

Turborepo can use a technique known as Remote Caching to share cache artifacts across machines, enabling you to share build caches with your team and CI/CD pipelines.

By default, Turborepo will cache locally. To enable Remote Caching you will need an account with Vercel. If you don't have an account you can create one, then enter the following commands:

cd ./reverse-architecture-web
npx turbo login

This will authenticate the Turborepo CLI with your Vercel account.

Next, you can link your Turborepo to your Remote Cache by running the following command from the root of your turborepo:

npx turbo link

Useful Links

Learn more about the power of Turborepo:

• Tasks
• Caching
• Remote Caching
• Filtering
• Configuration Options
• CLI Usage

reverse-architecture-web's Issues

Workspace explore mode (only zoom, pan and views navigation)

• Support implied relationships
• Support workspace name as first item in breadcrumbs navigation

Create and account by signing in via GitHub

User Story

As a user I need to have an account to save progress and have an authorized access to it.

Resources

• https://blog.bytebytego.com/p/password-session-cookie-token-jwt
• https://docs.github.com/en/rest/repos?apiVersion=2022-11-28
• https://docs.github.com/en/rest/repos/contents?apiVersion=2022-11-28#get-repository-content
• https://docs.github.com/en/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps
• https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps

View workspace version history (or change log)

Share project with users via email

User Story

As a user I want to be able to collaborate on a project or share a project to get feedback.

Upvote an architecture reference

Create workspace stack with a name

Filter architecture references using tags

Support automatic layout in modeling view

Resources

• ELK API
• elkjs GitHub

Subscribe for architecture reference changes on the community template page

Delete a workspace

Add an empty workspace to the project

Change workspace stack name

View account information (like username, avatar, full name, etc.)

User Story

As a user I need to see some basic account information like avatar and a username to be able to identify with which account I am signed in.

Export workspace to various formats (drawio, structurizr dsl, structurizr json, etc.)

• Export to Structurizr DSL
• Export to drawio
• Export to Structurizr JSON

Explore existing architecture references via categories (finance, media, secutiry, etc.)

Explore architecture references

User Story

As a user I need to explore existing architectures for reference.

Workspace code mode (write code and auto render, with ability to only position elements)

• Structurizr syntax highlighting
• Workspace parsing
• Workspace error highlight

Support themes and introduce default system theme

Checklist:

• Support "theme" property parsing in the DSL
• Apply theme to the workspace object
• Introduce default theme for Reverse Architecture platform
• Support existing themes from *.json metadata files

Resources:

• Example: https://structurizr.com/dsl?example=amazon-web-services
• Themes: https://structurizr.com/help/themes
• Default: https://static.structurizr.com/themes/default/theme.json

Switch between accounts

User Story

As a user I might want to have a personal account and a work account with different emails.

Modeling mode for creating hierarchies of elements

User Story

As a user I would like to switch to a modeling mode, so that I can create a hierarchy of architecture elements, before moving to the diagramming.

Search workspaces and commands in home page search bar

Tasks

• Search workspaces and commands by entering text
• Navigate through options via keyboard arrows
• Select and execute any search result using Enter or a mouse click
• Show more results in a separate page by clicking "see all" or pressing Enter

Create a workspace from a selected architecture reference

Manage workspace stacks (stack, unstack, rename)

User Story

As a user I might work on different projects and model different systems, so I need a way to separate those.

Manage settings (like default layout, account type, dark or light theme, etc.)

User Story

As a user I need to change personal preferences like light or dark theme.

Open workspace code editor

See active user cursors and changes in real-time

Share collaboration link (share in explore or build mode)

Tasks

• Share link popover on workspace page
• Save shared links in "Shared" tab on workspace explorer page
• Use access code for shared links to connect

Workspace build mode (manage elements, relationships and details with a mouse or touch screen)

• Add Software System
• Add Container
• Add Component
• Add Person
• Add Group
• Connect elements
• Remove elements
• Remove connections
• Edit element text
• Edit connection text

Open workspace in workspace viewer (explorer)

Resources

• reaflow storybook
• reaflow github

Write code according to Structurizr DSL and get basic syntax highlighting

Sign out from account (to be able to sign in with a different one)

User Story

As a user I need to be able to sign out from my account for security reasons or to change accounts.

Suggest personal workspace to the community

Import workspace from various formats (structurizr dsl, json, etc.)

Search architecture references by name

See syntax errors with decriptions, codes and links to documentation

Comment thread for architecture reference in general

Undo/redo changes in workspace editor page

Pin comment threads on the diagram

User Story

• As a user I want to leave comment anywhere on the diagram to highlight a section of the diagram
• As a user I want to be able to reply to a comment in a thread to continue the conversation
• As a user I want to mark thread as resolved when the conversation reached a conclusion

Show workspace version history (based on git commit history)

Sign in into existing account via GitHub

User Story

As a user I need to be able to sign in back into my account to access previous progress.