Architect Graph Service

A Spring Boot microservice for managing and visualizing architectural graphs using Neo4j. This service provides REST APIs for creating, querying, and comparing architectural diagrams and system relationships based on the C4 model.

Features

Graph Management: Create and manage local and global architectural graphs
Diagram Generation: Generate various types of C4 model diagrams (Context, Container, Deployment)
System Search: Search for software systems, containers, and deployment nodes
Version Comparison: Compare different versions of systems
Influence Analysis: Analyze relationships and dependencies between systems
Neo4j Integration: Full integration with Neo4j graph database
RESTful API: Comprehensive REST API with Swagger/OpenAPI documentation
DOT Format Support: Export diagrams in Graphviz DOT format

Technology Stack

Java: 17 (Eclipse Temurin)
Framework: Spring Boot 2.7.3
Database: Neo4j 5 Community Edition
Build Tool: Maven 3.9
API Documentation: Swagger/OpenAPI (SpringDoc)

Prerequisites

Docker and Docker Compose installed
Java 17+ (for local development)
Maven 3.9+ (for local development)

Quick Start with Docker Compose

The easiest way to run the service is using Docker Compose, which will start both the application and Neo4j database:

# Build and start all services
docker-compose up --build

# Or run in detached mode
docker-compose up -d --build

This will start:

Architect Graph Service on http://localhost:8080
Neo4j Database on bolt://localhost:7687
Neo4j Browser (web interface) on http://localhost:7474

Accessing Neo4j Browser

Open your browser and navigate to http://localhost:7474
Use the following credentials:
- Username: neo4j
- Password: password

Stopping the Services

# Stop services
docker-compose down

# Stop and remove volumes (this will delete all data)
docker-compose down -v

API Documentation

Once the service is running, you can access the Swagger API documentation at:

http://localhost:8080/swagger-ui.html

Or the OpenAPI JSON specification at:

http://localhost:8080/v3/api-docs

API Endpoints

Graph Operations

Create Local Graph

POST /api/v1/graph/local/json
Content-Type: application/json

{
  "workspace": { ... }
}

Creates a local graph from JSON document. All vertices and relationships are tagged with graphTag: Local.

Create Global Graph

POST /api/v1/graph/json
Content-Type: application/json

{
  "workspace": { ... }
}

Adds a system from the specified JSON document to the global graph. All vertices and relationships are tagged with graphTag: Global.

Get Graph Status

GET /api/v1/graph/{graph-type}/task/{task-id}

Retrieves the status of a graph by task key and graph type.

Search Operations

Search Deployment Nodes

GET /api/v1/search/deployment-node?search={query}

Search Containers

GET /api/v1/search/container?search={query}

Search Software Systems

GET /api/v1/search/software-system?search={query}

Diagram Generation

Context Diagram

GET /api/v1/context/{softwareSystemMnemonic}?rankDirection={direction}
GET /api/v1/diagram/context?cmdb={cmdb}&rankDirection={direction}&communicationDirection={direction}

Container Diagram

GET /api/v1/context/{softwareSystemMnemonic}/{containerMnemonic}?rankDirection={direction}

Deployment Diagram

GET /api/v1/deployment/{environment}/{softwareSystemMnemonic}?rankDirection={direction}
GET /api/v1/diagram/deployment?cmdb={cmdb}&env={env}&rank-direction={direction}&deployment-name={name}

DOT Format Diagrams

GET /api/v1/diagram/dot?id={id}
GET /api/v1/context/dot?cmdb={cmdb}
GET /api/v1/context/influence/dot?cmdb={cmdb}
GET /api/v1/influence/dot?id={id}

Influence Analysis

Get Container Influence

GET /api/v1/influence?cmdb={cmdb}&name={name}

Get Product Influence

GET /api/v1/graph/product/{cmdb}/influence

Get Deployment Influence

GET /api/v1/graph/deployment/{cmdb}/influence?name={name}&env={env}

Version Comparison

Compare Two Versions

GET /api/v1/diff/{cmdb}/{firstVersion}/{secondVersion}

Compare with Current Version

GET /api/v1/diff/{cmdb}/{firstVersion}

Custom Cypher Queries

Execute Custom Query

GET /api/v1/elements
Header: CYPHER-QUERY: {cypher_query}

Configuration

Environment Variables

The service can be configured using the following environment variables:

Variable	Description	Default
`SPRING_NEO4J_URI`	Neo4j connection URI	`bolt://neo4j:7687`
`SPRING_NEO4J_AUTHENTICATION_USERNAME`	Neo4j username	`neo4j`
`SPRING_NEO4J_AUTHENTICATION_PASSWORD`	Neo4j password	`password`
`JAVA_OPTS`	JVM options	`-Xmx512m -Xms256m`

Application Properties

Key configuration in application.properties:

spring.application.name=architect-graph
spring.services.graphviz.url=https://structurizr.vimpelcom.ru/graphviz
server.tomcat.relaxed-query-chars=[,]

Local Development

Building the Project

# Build the project
mvn clean package

# Skip tests
mvn clean package -DskipTests

Running Locally

Start Neo4j database (using Docker):

docker run -d \
  --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  neo4j:5-community

Update application.properties or set environment variables:

export SPRING_NEO4J_URI=bolt://localhost:7687
export SPRING_NEO4J_AUTHENTICATION_USERNAME=neo4j
export SPRING_NEO4J_AUTHENTICATION_PASSWORD=password

Run the application:

mvn spring-boot:run

Or run the JAR directly:

java -jar target/architecting_graph-*.jar

Docker

Building the Docker Image

docker build -t architect-graph-service:latest .

Running the Docker Container

docker run -d \
  --name architect-graph-service \
  -p 8080:8080 \
  -e SPRING_NEO4J_URI=bolt://host.docker.internal:7687 \
  -e SPRING_NEO4J_AUTHENTICATION_USERNAME=neo4j \
  -e SPRING_NEO4J_AUTHENTICATION_PASSWORD=password \
  architect-graph-service:latest

Project Structure

architect-graph-service/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── ru/beeline/architecting_graph/
│   │   │       ├── client/          # External service clients
│   │   │       ├── config/          # Spring configuration
│   │   │       ├── controller/      # REST controllers
│   │   │       ├── consumer/        # Message consumers
│   │   │       ├── dto/             # Data transfer objects
│   │   │       ├── exception/       # Custom exceptions
│   │   │       ├── model/           # Domain models
│   │   │       ├── repository/      # Neo4j repositories
│   │   │       ├── service/         # Business logic
│   │   │       └── utils/           # Utility classes
│   │   └── resources/
│   │       └── application.properties
│   └── test/
├── Dockerfile                        # Production Dockerfile
├── docker-compose.yml               # Docker Compose configuration
├── pom.xml                          # Maven configuration
└── README.md                        # This file

Graph Model (Graph Model)

The model is based on a graph data structure where main entities are connected by relationships.

Main entities of the graph model:

Software System - Software System
- Central entity representing a software system
- Connected to containers, components, and infrastructure
Container - Container
- Represents containerized applications
- Connected to container instances and deployment nodes
Component - Component
- Architectural components of the system
- Connected to containers and interfaces
Container Instance - Container Instance
- Specific running instances of containers
- Connected to infrastructure nodes
Infrastructure Node - Infrastructure Node
- Physical or virtual infrastructure nodes
- Connected to deployment nodes
Deployment Node - Deployment Node
- Target nodes for application deployment
- Connected to deployment environments
Deployment Environment - Deployment Environment
- Environments (development, testing, production)
- Connected to deployment nodes

Relationship types:

Child - Hierarchical relationships (parent-child)
Deploy - Deployment relationships
Relationship - Various types of connections between entities

Connections between different elements

Label	Connected elements (Child)	Connected elements (Relationship)	Connected elements (Deploy)
Software System	Container	Software System, Container, Component	Deployment Environment
Container	Component	Software System, Container, Component	Container Instance
Component	Component	Software System, Container, Component
Container Instance
Infrastructure Node		Deployment Node, Infrastructure Node
Deployment Node	Deployment Node, Infrastructure Node, Container Instance	Deployment Node,Infrastructure Node
Deployment Environment	Deployment Node, Infrastructure Node

Examples

Example 1: Create a Local Graph

curl -X POST http://localhost:8080/api/v1/graph/local/json \
  -H "Content-Type: application/json" \
  -d '{
    "workspace": {
      "model": {
        "softwareSystems": [...]
      }
    }
  }'

Example 2: Search for Software Systems

curl "http://localhost:8080/api/v1/search/software-system?search=payment"

Example 3: Generate Context Diagram

curl "http://localhost:8080/api/v1/context/payment-system?rankDirection=TB"

Example 4: Get Product Influence

curl "http://localhost:8080/api/v1/graph/product/PAYMENT-SYS/influence"

Example 5: Compare Versions

curl "http://localhost:8080/api/v1/diff/PAYMENT-SYS/1/2"

Example 6: Get Context Diagram in DOT Format

curl "http://localhost:8080/api/v1/context/dot?cmdb=PAYMENT-SYS"

Troubleshooting

Service won't start

Check if Neo4j is running and accessible:

docker ps | grep neo4j

Verify Neo4j connection:

docker exec -it architect-graph-neo4j cypher-shell -u neo4j -p password

Check application logs:

docker logs architect-graph-service

Connection Issues

Ensure Neo4j is healthy before starting the application
Verify environment variables are set correctly
Check network connectivity between containers

Build Issues

Ensure Docker has enough memory allocated (at least 2GB recommended)
Check internet connection for Maven dependency downloads
Verify Java version compatibility (Java 17 required)

Contributing

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

For issues and questions, please create an issue in the project repository.

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.devcontainer		.devcontainer
.github/workflows		.github/workflows
.mvn/wrapper		.mvn/wrapper
export/neo4j		export/neo4j
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
Dockerfile-local		Dockerfile-local
LICENSE		LICENSE
Patch2.patch		Patch2.patch
README.md		README.md
docker-compose.yml		docker-compose.yml
mvnw		mvnw
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml

License

tech-beeline/beeatlas-architect-graph-service

Folders and files

Latest commit

History

Repository files navigation

Architect Graph Service

Features

Technology Stack

Prerequisites

Quick Start with Docker Compose

Accessing Neo4j Browser

Stopping the Services

API Documentation

API Endpoints

Graph Operations

Create Local Graph

Create Global Graph

Get Graph Status

Search Operations

Search Deployment Nodes

Search Containers

Search Software Systems

Diagram Generation

Context Diagram

Container Diagram

Deployment Diagram

DOT Format Diagrams

Influence Analysis

Get Container Influence

Get Product Influence

Get Deployment Influence

Version Comparison

Compare Two Versions

Compare with Current Version

Custom Cypher Queries

Execute Custom Query

Configuration

Environment Variables

Application Properties

Local Development

Building the Project

Running Locally

Docker

Building the Docker Image

Running the Docker Container

Project Structure

Graph Model (Graph Model)

Main entities of the graph model:

Relationship types:

Connections between different elements

Examples

Example 1: Create a Local Graph

Example 2: Search for Software Systems

Example 3: Generate Context Diagram

Example 4: Get Product Influence

Example 5: Compare Versions

Example 6: Get Context Diagram in DOT Format

Troubleshooting

Service won't start

Connection Issues

Build Issues

Contributing

License

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages