Structurizr Architecture Scanner

A comprehensive system for scanning, tracking, and visualizing your architecture landscape across multiple applications.

Overview

This project provides a complete solution for:

Scanning GitLab repositories to extract architecture information
Storing application metadata, technology stacks, interfaces, and dependencies in a versioned database
Identifying and managing shared components (e.g., KeyCloak for SSO)
Tracking application evolution over time
Browsing and analyzing your architecture landscape through a web UI
Generating Structurizr DSL for visualization

Architecture

The system consists of four main components:

Backend (Spring Boot): REST API and database layer
Frontend (Angular): Web UI for browsing and analyzing applications
Database (PostgreSQL): Stores all architecture data with versioning
MCP Server (Node.js): Model Context Protocol server for Claude integration

Technology Stack

Backend

Java 21
Spring Boot 3.2.1
Spring Data JPA
PostgreSQL 15
Maven
GitLab4J API

Frontend

Angular 17
Angular Material
TypeScript
RxJS

Infrastructure

Docker & Docker Compose
PostgreSQL 15

MCP Server

Node.js 20+
TypeScript
MCP SDK
Axios

Prerequisites

Docker and Docker Compose
(Optional) Java 21 and Maven for local development
(Optional) Node.js 20+ and npm for frontend development
GitLab access token for repository scanning

Quick Start

1. Clone the Repository

git clone <repository-url>
cd structurizr-db

2. Configure Environment Variables

Create a .env file in the root directory:

# GitLab Configuration
GITLAB_URL=https://your-gitlab-instance.com
GITLAB_TOKEN=your-gitlab-access-token

# Database Configuration (optional, defaults are fine for local dev)
DB_HOST=postgres
DB_PORT=5432
DB_NAME=architecturedb
DB_USER=postgres
DB_PASSWORD=postgres

# Backend Configuration
SERVER_PORT=8080

3. Start the Application

docker-compose up -d

This will start:

PostgreSQL database on port 5432
Spring Boot backend on port 8080
Angular frontend on port 4200

4. Access the Application

Frontend UI: http://localhost:4200
Backend API: http://localhost:8080/api
API Health Check: http://localhost:8080/actuator/health

MCP Server Integration

The project includes a Model Context Protocol (MCP) server that allows Claude Desktop, Claude Code CLI, and other MCP clients to directly interact with your architecture landscape.

What is MCP?

MCP is an open protocol that enables AI assistants to securely interact with external data sources and tools. The Structurizr MCP server exposes 11 tools, 5 resources, and 4 pre-configured prompts for architecture analysis.

Quick Setup

Install and Build the MCP Server:
```
cd mcp-server
npm install
npm run build
```

Configure Claude Desktop:

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "structurizr": {
      "command": "node",
      "args": ["/absolute/path/to/structurizr-db/mcp-server/build/index.js"],
      "env": {
        "STRUCTURIZR_API_URL": "http://localhost:8080/api"
      }
    }
  }
}

Restart Claude Desktop

Available Capabilities

11 Tools:

List, search, and create applications
Query technology stacks
Analyze interfaces and dependencies
View version history
Get statistics

5 Resources:

All applications
Shared components
Statistics
Departments and technologies

4 Prompts:

Comprehensive application analysis
Technology usage analysis
Architecture overview generation
Dependency identification

Example Usage

Once configured, you can interact with Claude naturally:

You: "Show me all applications using PostgreSQL 15"
Claude: [uses find_applications_by_technology tool]

You: "Analyze the Customer Service application"
Claude: [uses analyze_application prompt for comprehensive analysis]

You: "What are the shared components in our landscape?"
Claude: [uses list_applications tool with sharedOnly filter]

For detailed MCP documentation, see mcp-server/README.md

Database Schema

Core Entities

Application

Represents an application in the architecture landscape.

UUID: Unique identifier for cross-referencing
Name: Application name
Description: Application description
Repository URL: GitLab repository URL
Department: Responsible team/department
Author: Repository creator
Is Shared Component: Flag for reusable building blocks
Current Version: Latest scan version number
Last Scanned At: Timestamp of last scan

ApplicationVersion

Tracks version history for applications.

Version Number: Incremental version
Scanned Branch: Git branch that was scanned
Commit Hash: Git commit at scan time
Technology Stack Snapshot: JSON snapshot
Interfaces Snapshot: JSON snapshot
Scan Notes: Additional information

TechnologyStack

Technologies used by applications.

Name: Technology name (e.g., "Spring Boot")
Version: Technology version
Category: Framework, Database, MessageQueue, etc.
Detection Source: Where it was detected (e.g., "pom.xml")

ApplicationInterface

Connections between applications.

UUID: Unique identifier
Source Application: Calling application
Target Application: Receiving application
Protocol: REST, gRPC, AMQP, etc.
Destination: Hostname, URL, or queue name
Port: Port number (if applicable)
Direction: OUTBOUND, INBOUND, or BIDIRECTIONAL

ApplicationUser

Users of applications.

User Name: User or group name
User Type: INDIVIDUAL, GROUP, DEPARTMENT, EXTERNAL
Role: Permission level

ApplicationMetadata

Flexible key-value metadata.

Key: Metadata key
Value: Metadata value
Value Type: STRING, NUMBER, BOOLEAN, JSON
Category: Grouping category

REST API Endpoints

Applications

GET    /api/applications                    # Get all applications
GET    /api/applications/{id}               # Get application by ID
GET    /api/applications/uuid/{uuid}        # Get application by UUID
GET    /api/applications/search?term={term} # Search applications
GET    /api/applications/department/{dept}  # Get by department
GET    /api/applications/departments        # Get all departments
GET    /api/applications/shared-components  # Get shared components
GET    /api/applications/statistics         # Get statistics
POST   /api/applications                    # Create application
PUT    /api/applications/{id}               # Update application
DELETE /api/applications/{id}               # Delete application

Technology Stack

GET /api/technology-stack/application/{id}           # Get by application ID
GET /api/technology-stack/application/uuid/{uuid}    # Get by application UUID
GET /api/technology-stack/technologies               # Get all technologies
GET /api/technology-stack/categories                 # Get all categories
GET /api/technology-stack/search?name={name}&version={version} # Search

Interfaces

GET /api/interfaces/application/{id}    # Get all interfaces for application
GET /api/interfaces/source/{id}         # Get outbound interfaces
GET /api/interfaces/target/{id}         # Get inbound interfaces
GET /api/interfaces/protocols           # Get all protocols
GET /api/interfaces/protocol/{protocol} # Get by protocol
GET /api/interfaces/uuid/{uuid}         # Get by UUID

Versions

GET /api/versions/application/{id}         # Get versions by application ID
GET /api/versions/application/uuid/{uuid}  # Get versions by UUID
GET /api/versions/{id}                     # Get version by ID

Development

Backend Development

Prerequisites

Java 21
Maven 3.9+
PostgreSQL 15

Running Locally

# Start PostgreSQL
docker run -d -p 5432:5432 \
  -e POSTGRES_DB=architecturedb \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  postgres:15-alpine

# Run Spring Boot application
cd structurizr-db
mvn spring-boot:run

Building

mvn clean package

Frontend Development

Prerequisites

Node.js 20+
npm

Running Locally

cd frontend
npm install
npm start

The application will be available at http://localhost:4200

Building

npm run build

Usage Guide

Dashboard

View high-level statistics about your architecture landscape:

Total number of applications
Number of shared components
Number of departments

Applications

Browse all applications in your landscape:

Search by name or description
Filter by department
View application details including technology stack, interfaces, and version history

Shared Components

View reusable building blocks used across multiple applications:

KeyCloak for SSO
Shared databases
Shared message queues
Other shared services

Technology Overview

Analyze technology usage across your landscape:

See which applications use specific technologies
Track technology versions
Identify outdated dependencies

Data Model Philosophy

UUID-based Identification

Applications and interfaces use UUIDs to:

Ensure uniqueness across the landscape
Enable proper identification of shared components
Allow cross-referencing between different scans

Versioning Strategy

Each successful scan increments the version number
Historical snapshots are stored in ApplicationVersion
Enables tracking of application evolution over time
Supports queries like "what changed between version X and Y?"

Flexible Metadata

The ApplicationMetadata table allows storing arbitrary key-value pairs:

Extensible without schema changes
Supports custom attributes per organization
Enables future analytics capabilities

Next Steps

GitLab Scanner Component

The next phase will implement the actual repository scanner:

Connect to GitLab API
Scan repositories (development or main branch)
Extract technology information from build files
Detect interfaces from configuration files
Populate the database

Structurizr DSL Generation

Generate Structurizr workspace from the aggregated data:

Create workspace with all applications
Define relationships based on interfaces
Group by departments
Highlight shared components

Notion Integration

Create Notion overview cards:

One card per application
Sync description and metadata
Enable documentation workflow

Contributing

Code Structure

structurizr-db/
├── src/main/java/com/structurizr/scanner/
│   ├── entity/              # JPA entities
│   ├── repository/          # Spring Data repositories
│   ├── dto/                 # Data Transfer Objects
│   ├── controller/          # REST controllers
│   ├── mapper/              # Entity-DTO mappers
│   └── service/             # Business logic (future)
├── src/main/resources/
│   └── application.yml      # Configuration
├── frontend/
│   └── src/app/
│       ├── components/      # Angular components
│       ├── services/        # API services
│       ├── models/          # TypeScript interfaces
│       └── environments/    # Environment configs
├── mcp-server/
│   ├── src/
│   │   └── index.ts         # MCP server implementation
│   ├── build/               # Compiled JavaScript
│   ├── package.json         # Node.js dependencies
│   └── README.md            # MCP documentation
├── docker-compose.yml       # Docker orchestration
├── Dockerfile               # Backend container
└── README.md                # Main documentation

License

[Your License Here]

Support

For issues, questions, or contributions, please contact [your-contact-info].

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
frontend		frontend
mcp-server		mcp-server
src/main		src/main
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
pom.xml		pom.xml

Folders and files

Latest commit

History

Repository files navigation

Structurizr Architecture Scanner

Overview

Architecture

Technology Stack

Backend

Frontend

Infrastructure

MCP Server

Prerequisites

Quick Start

1. Clone the Repository

2. Configure Environment Variables

3. Start the Application

4. Access the Application

MCP Server Integration

What is MCP?

Quick Setup

Available Capabilities

Example Usage

Database Schema

Core Entities

Application

ApplicationVersion

TechnologyStack

ApplicationInterface

ApplicationUser

ApplicationMetadata

REST API Endpoints

Applications

Technology Stack

Interfaces

Versions

Development

Backend Development

Prerequisites

Running Locally

Building

Frontend Development

Prerequisites

Running Locally

Building

Usage Guide

Dashboard

Applications

Shared Components

Technology Overview

Data Model Philosophy

UUID-based Identification

Versioning Strategy

Flexible Metadata

Next Steps

GitLab Scanner Component

Structurizr DSL Generation

Notion Integration

Contributing

Code Structure

License

Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages