Architecture

Architecture

This page describes the overall system architecture of the Vitruv-UI-Methodologist — the two repositories, how they communicate, and how the frontend codebase is organized internally.

---

System overview

The tool consists of two independent services that are deployed separately and communicate over HTTP and WebSocket.

graph TD
    FE["Vitruv-UI-Methodologist\n React"]

    BE["methodologistUI-backend\nSpring Boot · Port 9811\nREST API"]

    KC["Keycloak\nOIDC provider · Port 7668\nSSO login · token issuance"]

    DB["PostgreSQL\nPort 3454\n"]

    FE -->|"REST (JWT)"| BE
    FE -->|"WebSocket — Reactions DSL LSP"| BE

    FE -->|"SSO redirect"| KC
    BE -->|"token validation"| KC
    BE --> DB

Loading

---

Repository structure

Frontend — Vitruv-UI-Methodologist

src/
├── components/
│   ├── auth/          # Sign in, sign up, OTP verification, Keycloak redirect
│   ├── canvas/        # Canvas chrome: project tabs, model drawer, UML panels
│   ├── constraints/   # Constraints mode overlay
│   ├── flow/          # ReactFlow canvas, nodes, edges, Code Editor, LSP wiring
│   ├── layout/        # App sidebar (Home page navigation)
│   └── ui/            # Shared modals and views: Projects, Library, Profile, etc.
│
├── pages/
│   ├── HomePage.tsx   # Sidebar layout, switches between home/library/projects/profile
│   ├── CanvasPage.tsx # Canvas page: mode toggle, tab management, toolbar, save/build
│   └── OtpVerificationPage.tsx
│
├── contexts/
│   └── AuthContext.tsx  # Global auth state, user object, token lifecycle
│
├── hooks/               # Custom hooks (useFlowState, useViewTypes, useUndoRedo, …)
├── services/
│   ├── api.ts           # All REST calls to the backend (fetch-based, JWT-injected)
│   └── auth.ts          # Token storage, refresh, sign-in/sign-out
│
├── types/               # TypeScript interfaces (Vsum, VsumDetails, flow types, …)
├── utils/               # Pure functions (ecore parsing, UML layout, JWT parsing, …)
└── config/
    └── environment.ts   # Reads REACT_APP_* env vars, exported as config object

Backend — methodologistUI-backend

Layer	Technology
Web framework	Spring Boot 3, Java 17
Database	PostgreSQL (Flyway migrations)
Authentication	Keycloak (OIDC / JWT); Spring
Build	Maven
Code quality	SonarQube, Checkstyle
LSP processes	WebSocket session, managed by the backend

---

Frontend tech stack

Concern	Library / tool	Version
UI framework	React	19
Language	TypeScript	4.9
Routing	React Router DOM	6
Canvas / diagram	ReactFlow	11
Code editor	Monaco Editor (@monaco-editor/react)	4.7
LSP client	monaco-languageclient, vscode-ws-jsonrpc	—
Drag and drop	React DnD	16
Testing	React Testing Library, Jest	—
Build tooling	Create React App (react-scripts)	5
Static analysis	SonarQube	—

---

Local service ports

Service	URL
Frontend (dev server)	http://localhost:3000
Backend REST API	http://localhost:9811
Swagger UI	http://localhost:9811/swagger-ui.html
Keycloak	http://localhost:7668
PostgreSQL	localhost:3454