Architectural Decision Log (ADL) System

A comprehensive system for managing architectural decisions with GraphQL backend, MCP server integration, and a web-based UI.

Architecture

• GraphQL Backend (Port 4000): Provides data layer with CRUD operations for ADL entries

• MCP HTTP Server (Port 5000): HTTP wrapper for MCP protocol, bridges UI and GraphQL

• MCP Stdio Server: Model Context Protocol server for AI assistant integration

• Web UI (Port 3000): React-based interface for managing ADL entries

Data Flow

UI (Port 3000) → MCP HTTP Server (Port 5000) → GraphQL Backend (Port 4000) → JSON Database

AI Assistants → MCP Stdio Server → GraphQL Backend (Port 4000) → JSON Database

Features

• Create, Read, Update, Delete architectural decision entries

• Track decision metadata (author, timestamps, status)

• Integration with SAP/LeanIX fact sheets

• Table-based UI with filtering and sorting

• Linux-compatible deployment

Data Model

Each ADL entry contains:

• ID: Unique indexed key

• Created: Creation timestamp

• Last Edited: Last modification timestamp

• Author: Decision author name

• Title: Decision title

• Decision: Detailed decision description

• Fact Sheets: List of related SAP/LeanIX Fact Sheet names

• Status: Proposed or Approved

Installation

# Install dependencies
npm install

# Start all services
npm start

# Or start services individually
npm run start:graphql  # GraphQL server on port 4000
npm run start:mcp      # MCP server (stdio)
npm run start:ui       # UI server on port 3000

Docker Deployment (Linux)

# Build Docker image
docker build -t adl-system .

# Run container
docker run -p 3000:3000 -p 4000:4000 -v $(pwd)/data:/app/data adl-system

Usage

Via UI

1. Navigate to http://localhost:3000

2. Use the web interface to manage ADL entries

Via MCP Server

The MCP server exposes the following tools:

• adl_create: Create a new ADL entry

• adl_read: Read ADL entries (all or by ID)

• adl_update: Update an existing ADL entry

• adl_delete: Delete an ADL entry

Via GraphQL

Access GraphQL Playground at http://localhost:4000/graphql

Example query:

query {
  adlEntries {
    id
    title
    status
    author
  }
}

License

MIT

ADL-MCP