LLM-Driven System Boundary & Responsibility Mapper on Civo

Your architecture knowledge is scattered across Slack threads, wiki pages, and incident postmortems. Teams lose track of system boundaries, component ownership, and who's responsible for what. Manually maintaining system maps? They're outdated the moment you finish them.

This tutorial fixes that. You'll build a tool that automatically generates interactive system maps from messy architecture notes. Paste unstructured text, get color-coded diagrams showing team ownership and component relationships. Everything runs on Civo Kubernetes with relaxAI handling the LLM inference.

This tutorial is aimed at intermediate-level developers comfortable with Python and Docker. Kubernetes experience is helpful but not required.

Prerequisites

Before starting, ensure you have:

Civo Account with GPU access
Docker installed locally
Python installed
relaxAI API Key from the relaxAI dashboard (navigate to API Keys section)
Kubectl installed

Project Structure

Create the following directory structure:

1system-mapper/
2├── backend/
3│   ├── Dockerfile
4│   ├── requirements.txt
5│   └── app.py
6├── frontend/
7│   ├── Dockerfile
8│   ├── index.html
9│   └── app.js
10└── kubernetes/
11    ├── backend-deployment.yaml
12    └── frontend-deployment.yaml

Step 1: Create and connect to your Civo Kubernetes cluster

Log in to the Civo Dashboard
Create a new Kubernetes cluster
Add a GPU node pool (one node is sufficient for this demo)
Download your kubeconfig file
Connect to the cluster by running set KUBECONFIG=path-to-kubeconfig-file in your terminal (use export instead of set on Linux or macOS)
Verify connectivity by running kubectl get nodes

LLM-Driven System Boundary & Responsibility Mapper on Civo

While this demo processes lightweight inputs, the GPU-enabled cluster ensures the setup can handle larger, more compute-intensive inference workloads without redesigning the system.

Step 2: Build the backend

In this step, you’ll build the FastAPI backend that powers the system mapper. This service accepts raw architecture notes, sends them to relaxAI for structured extraction, and returns a clean JSON response containing nodes and edges.

By the end of this step, you’ll have a working /map endpoint running locally that converts unstructured text into a structured system graph. Open app.py. In this file, you’ll add all the code in this step, building the backend incrementally from imports to the /map endpoint and the local run block.

Import necessary libraries:

1from fastapi import FastAPI, HTTPException
2from fastapi.middleware.cors import CORSMiddleware
3from pydantic import BaseModel
4from openai import OpenAI
5import os
6import json

Initialize the FastAPI application:

1app = FastAPI()
2
3
4app.add_middleware(
5   CORSMiddleware,
6   allow_origins=["*"],  # For demo purposes; tighten for production
7   allow_credentials=True,
8   allow_methods=["*"],
9   allow_headers=["*"],
10)

Configure the relaxAI client:

1client = OpenAI(
2   api_key=os.environ.get("RELAXAI_API_KEY"),
3   base_url="https://api.relax.ai/v1"
4)

Define request and response models:

1class ArchitectureNotes(BaseModel):
2   """Input: raw, unstructured architecture notes"""
3   notes: str
4
5
6class SystemMap(BaseModel):
7   """Output: structured system map with nodes and edges"""
8   nodes: list
9   edges: list

Define the extraction prompt:

1EXTRACTION_PROMPT = """You are a system architecture extraction engine.
2
3
4STRICT REQUIREMENTS:
5- OUTPUT ONLY JSON.
6- NO explanation.
7- NO natural language.
8- NO markdown.
9- NO code fences (no ```json or ```).
10- NO commentary.
11- If unsure about a component or relationship, omit it.
12
13
14Extract system components (nodes) and their relationships (edges) from the architecture notes.
15
16
17REQUIRED JSON FORMAT (follow EXACTLY):
18{
19 "nodes": [
20   {
21     "id": "unique-component-id",
22     "label": "Component Name",
23     "team": "Team Name",
24     "type": "service",
25     "description": "Brief description"
26   }
27 ],
28 "edges": [
29   {
30     "source": "component-id-1",
31     "target": "component-id-2",
32     "relationship": "calls"
33   }
34 ]
35}
36
37
38VALID node types: service, database, frontend, queue, boundary
39VALID relationship types: calls, stores_in, publishes_to, reads_from
40
41
42IDs: lowercase-with-hyphens (e.g., "user-service", "postgres-db")
43Descriptions: under 100 characters
44
45
46Architecture notes:
47"""

Add a health check endpoint:

1@app.get("/health")
2def health_check():
3   """Simple health check endpoint for Kubernetes liveness probes"""
4   return {"status": "healthy"}

Implement the /map endpoint:

1@app.post("/map", response_model=SystemMap)
2async def generate_map(input_data: ArchitectureNotes):
3  
4   # Validate input
5   if not input_data.notes or len(input_data.notes.strip()) &lt; 10:
6       raise HTTPException(
7           status_code=400,
8           detail="Notes must contain at least 10 characters"
9       )
10  
11   try:
12       # Call relaxAI with extraction prompt
13       response = client.chat.completions.create(
14           model="Llama-4-Maverick-17B-128E",  # Fast, capable model
15           messages=[
16               {
17                   "role": "system",
18                   "content": "You are a precise system architecture analyzer. Return only valid JSON."
19               },
20               {
21                   "role": "user",
22                   "content": EXTRACTION_PROMPT + input_data.notes
23               }
24           ],
25           temperature=0.3,  # Lower temperature for more consistent structured output
26           max_tokens=2000
27       )
28      
29       # Extract LLM response
30       llm_output = response.choices[0].message.content.strip()
31      
32       # Parse JSON (LLM sometimes wraps in markdown code blocks)
33       if llm_output.startswith("```json"):
34           llm_output = llm_output.split("```json")[1].split("```")[0].strip()
35       elif llm_output.startswith("```"):
36           llm_output = llm_output.split("```")[1].split("```")[0].strip()
37      
38       system_map = json.loads(llm_output)
39      
40       # Basic validation
41       if "nodes" not in system_map or "edges" not in system_map:
42           raise ValueError("LLM output missing required fields: nodes, edges")
43      
44       return SystemMap(**system_map)
45  
46   except json.JSONDecodeError as e:
47       raise HTTPException(
48           status_code=500,
49           detail=f"LLM returned invalid JSON: {str(e)}"
50       )
51   except Exception as e:
52       raise HTTPException(
53           status_code=500,
54           detail=f"Error generating map: {str(e)}"
55       )

Add the local development entry point:

1if __name__ == "__main__":
2   import uvicorn
3   uvicorn.run(app, host="0.0.0.0", port=8000)

At this point, your backend is complete and ready to accept architecture notes and return structured system data. In the next step, you’ll build a minimal frontend to visualize that data as an interactive system map.

Step 3: Build the frontend

Now that your backend can extract structured system maps from unstructured notes, you’ll build a minimal frontend to:

Accept architecture notes
Send them to the /map endpoint
Render the structured output as an interactive diagram

Create the frontend files

Create the following two files inside the frontend/ directory of your project:

The frontend consists of:

index.html → Full UI layout
app.js → Logic

Index.html

1<!DOCTYPE html>
2<html lang="en">
3<head>
4   <meta charset="UTF-8">
5   <meta name="viewport" content="width=device-width, initial-scale=1.0">
6   <title>System Boundary Mapper</title>
7  
8   <!-- Cytoscape.js: JavaScript library for visualizing and interacting with graphs -->
9   <script src="https://cdnjs.cloudflare.com/ajax/libs/cytoscape/3.28.1/cytoscape.min.js"></script>
10  
11   <style>
12       * {
13           margin: 0;
14           padding: 0;
15           box-sizing: border-box;
16       }
17
18
19       body {
20           font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Arial, sans-serif;
21           background: #f5f5f5;
22           padding: 20px;
23       }
24
25
26       .container {
27           max-width: 1400px;
28           margin: 0 auto;
29           background: white;
30           border-radius: 8px;
31           box-shadow: 0 2px 8px rgba(0,0,0,0.1);
32           overflow: hidden;
33       }
34
35
36       .header {
37           background: #2563eb;
38           color: white;
39           padding: 30px;
40           text-align: center;
41       }
42
43
44       .header h1 {
45           margin-bottom: 10px;
46           font-size: 28px;
47       }
48
49
50       .header p {
51           opacity: 0.9;
52           font-size: 16px;
53       }
54
55
56       .content {
57           display: grid;
58           grid-template-columns: 400px 1fr;
59           min-height: 600px;
60       }
61
62
63       .input-panel {
64           padding: 30px;
65           border-right: 1px solid #e5e7eb;
66           background: #fafafa;
67       }
68
69
70       .input-panel h2 {
71           margin-bottom: 15px;
72           font-size: 18px;
73           color: #1f2937;
74       }
75
76
77       .input-panel textarea {
78           width: 100%;
79           height: 300px;
80           padding: 15px;
81           border: 1px solid #d1d5db;
82           border-radius: 6px;
83           font-family: monospace;
84           font-size: 14px;
85           resize: vertical;
86           margin-bottom: 15px;
87       }
88
89
90       .input-panel textarea:focus {
91           outline: none;
92           border-color: #2563eb;
93       }
94
95
96       .input-panel button {
97           width: 100%;
98           padding: 12px;
99           background: #2563eb;
100           color: white;
101           border: none;
102           border-radius: 6px;
103           font-size: 16px;
104           font-weight: 600;
105           cursor: pointer;
106           transition: background 0.2s;
107       }
108
109
110       .input-panel button:hover {
111           background: #1d4ed8;
112       }
113
114
115       .input-panel button:disabled {
116           background: #9ca3af;
117           cursor: not-allowed;
118       }
119
120
121       .status {
122           margin-top: 15px;
123           padding: 10px;
124           border-radius: 6px;
125           font-size: 14px;
126           text-align: center;
127       }
128
129
130       .status.loading {
131           background: #dbeafe;
132           color: #1e40af;
133       }
134
135
136       .status.success {
137           background: #d1fae5;
138           color: #065f46;
139       }
140
141
142       .status.error {
143           background: #fee2e2;
144           color: #991b1b;
145       }
146
147
148       .graph-panel {
149           position: relative;
150       }
151
152
153       #graph {
154           width: 100%;
155           height: 600px;
156           background: #ffffff;
157       }
158
159
160       .node-details {
161           position: absolute;
162           top: 20px;
163           right: 20px;
164           background: white;
165           padding: 20px;
166           border-radius: 6px;
167           box-shadow: 0 4px 12px rgba(0,0,0,0.15);
168           max-width: 300px;
169           display: none;
170       }
171
172
173       .node-details.active {
174           display: block;
175       }
176
177
178       .node-details h3 {
179           margin-bottom: 10px;
180           color: #1f2937;
181           font-size: 18px;
182       }
183
184
185       .node-details .detail-row {
186           margin-bottom: 8px;
187           font-size: 14px;
188       }
189
190
191       .node-details .detail-label {
192           font-weight: 600;
193           color: #6b7280;
194           margin-right: 5px;
195       }
196
197
198       .legend {
199           position: absolute;
200           bottom: 20px;
201           left: 20px;
202           background: white;
203           padding: 15px;
204           border-radius: 6px;
205           box-shadow: 0 2px 8px rgba(0,0,0,0.1);
206       }
207
208
209       .legend h4 {
210           margin-bottom: 10px;
211           font-size: 14px;
212           color: #1f2937;
213       }
214
215
216       .legend-item {
217           display: flex;
218           align-items: center;
219           margin-bottom: 6px;
220           font-size: 13px;
221       }
222
223
224       .legend-color {
225           width: 20px;
226           height: 20px;
227           border-radius: 4px;
228           margin-right: 8px;
229       }
230
231
232       .example-link {
233           margin-top: 15px;
234           padding: 10px;
235           background: #eff6ff;
236           border-radius: 6px;
237           font-size: 13px;
238           color: #1e40af;
239           cursor: pointer;
240           text-align: center;
241       }
242
243
244       .example-link:hover {
245           background: #dbeafe;
246       }
247   </style>
248</head>
249<body>
250   <div class="container">
251       <div class="header">
252           <h1>System Boundary & Responsibility Mapper</h1>
253           <p>Turn messy architecture notes into interactive system diagrams</p>
254       </div>
255
256
257       <div class="content">
258           <div class="input-panel">
259               <h2>Architecture Notes</h2>
260               <textarea
261                   id="notes"
262                   placeholder="Paste your architecture notes here..."
263               ></textarea>
264              
265               <button id="generateBtn">Generate Map</button>
266              
267               <div id="status" class="status" style="display: none;"></div>
268
269
270           </div>
271
272
273           <div class="graph-panel">
274               <div id="graph"></div>
275              
276               <div id="nodeDetails" class="node-details">
277                   <h3 id="nodeName"></h3>
278                   <div class="detail-row">
279                       <span class="detail-label">Team:</span>
280                       <span id="nodeTeam"></span>
281                   </div>
282                   <div class="detail-row">
283                       <span class="detail-label">Type:</span>
284                       <span id="nodeType"></span>
285                   </div>
286                   <div class="detail-row">
287                       <span class="detail-label">Description:</span>
288                       <span id="nodeDescription"></span>
289                   </div>
290               </div>
291
292
293               <div class="legend">
294                   <h4>Team Ownership</h4>
295                   <div class="legend-item">
296                       <div class="legend-color" style="background: #ef4444;"></div>
297                       Commerce
298                   </div>
299                   <div class="legend-item">
300                       <div class="legend-color" style="background: #10b981;"></div>
301                       Catalog
302                   </div>
303                   <div class="legend-item">
304                       <div class="legend-color" style="background: #3b82f6;"></div>
305                       Identity
306                   </div>
307                   <div class="legend-item">
308                       <div class="legend-color" style="background: #8b5cf6;"></div>
309                       Platform
310                   </div>
311                   <div class="legend-item">
312                       <div class="legend-color" style="background: #06b6d4;"></div>
313                       Data
314                   </div>
315                   <div class="legend-item">
316                       <div class="legend-color" style="background: #f59e0b;"></div>
317                       UI
318                   </div>
319                   <div class="legend-item">
320                       <div class="legend-color" style="background: #f97316;"></div>
321                       Operations
322                   </div>
323               </div>
324           </div>
325       </div>
326   </div>
327
328
329   <script src="app.js"></script>
330</body>
331</html>

Here’s how the frontend should look:

LLM-Driven System Boundary & Responsibility Mapper on Civo 2

app.js

Configure backend URL:

1const API_URL = window.location.hostname === 'localhost'
2   ? 'http://localhost:8000'
3   : 'http://<BACKEND-EXTERNAL-IP>:8000';

Important note: The above value is effectively baked into the Docker image when the frontend is built. This means you must:

Deploy the backend first
Wait for the LoadBalancer external IP to be assigned
Replace <BACKEND-EXTERNAL-IP> with that value
Then build and push the frontend image

If you build the frontend before the backend’s external IP is available, the deployed UI will point to an invalid endpoint.

Initialize color mapping, default color, and example notes:

1onst TEAM_COLORS = {
2   'UI': '#f59e0b',
3   'Platform': '#8b5cf6',
4   'Identity': '#3b82f6',
5   'Catalog': '#10b981',
6   'Commerce': '#ef4444',
7   'Data': '#06b6d4',
8   'Operations': '#f97316'
9};
10
11
12const DEFAULT_COLOR = '#6b7280';
13
14
15let cy = null;

Initialize Cytoscape:

1function initGraph() {
2   cy = cytoscape({
3       container: document.getElementById('graph'),
4      
5       // Visual styling for nodes and edges
6       style: [
7           {
8               selector: 'node',
9               style: {
10                   'background-color': 'data(color)',
11                   'label': 'data(label)',
12                   'width': 60,
13                   'height': 60,
14                   'text-valign': 'bottom',
15                   'text-halign': 'center',
16                   'text-margin-y': 5,
17                   'font-size': '12px',
18                   'text-wrap': 'wrap',
19                   'text-max-width': '100px',
20                   'border-width': 2,
21                   'border-color': '#ffffff',
22                   'overlay-opacity': 0
23               }
24           },
25           {
26               selector: 'edge',
27               style: {
28                   'width': 2,
29                   'line-color': '#cbd5e1',
30                   'target-arrow-color': '#cbd5e1',
31                   'target-arrow-shape': 'triangle',
32                   'curve-style': 'bezier',
33                   'arrow-scale': 1.5,
34                   'label': 'data(relationship)',
35                   'font-size': '10px',
36                   'text-rotation': 'autorotate',
37                   'text-margin-y': -10,
38                   'color': '#64748b'
39               }
40           },
41           {
42               selector: 'node:selected',
43               style: {
44                   'border-width': 4,
45                   'border-color': '#2563eb'
46               }
47           }
48       ],
49      
50       // Automatic layout algorithm
51       layout: {
52           name: 'breadthfirst',
53           directed: true,
54           padding: 50,
55           spacingFactor: 1.5
56       },
57      
58       // Enable zoom and pan
59       minZoom: 0.3,
60       maxZoom: 3,
61       wheelSensitivity: 0.2
62   });
63
64
65   // Show node details when clicked
66   cy.on('tap', 'node', function(event) {
67       const node = event.target;
68       showNodeDetails(node.data());
69   });
70
71
72   // Hide details when clicking background
73   cy.on('tap', function(event) {
74       if (event.target === cy) {
75           hideNodeDetails();
76       }
77   });
78}
79

Create the node details panel functions:

1function showNodeDetails(data) {
2   document.getElementById('nodeName').textContent = data.label;
3   document.getElementById('nodeTeam').textContent = data.team || 'Unknown';
4   document.getElementById('nodeType').textContent = data.type || 'Unknown';
5   document.getElementById('nodeDescription').textContent = data.description || 'No description';
6   document.getElementById('nodeDetails').classList.add('active');
7}
8
9
10function hideNodeDetails() {
11   document.getElementById('nodeDetails').classList.remove('active');
12}

Create the status panel functions:

1function showStatus(message, type) {
2   const statusEl = document.getElementById('status');
3   statusEl.textContent = message;
4   statusEl.className = `status ${type}`;
5   statusEl.style.display = 'block';
6}
7
8
9function hideStatus() {
10   document.getElementById('status').style.display = 'none';
11}

Create the generate map function:

1async function generateMap() {
2   const notes = document.getElementById('notes').value.trim();
3  
4   if (!notes) {
5       showStatus('Please enter some architecture notes', 'error');
6       return;
7   }
8
9
10   const generateBtn = document.getElementById('generateBtn');
11   generateBtn.disabled = true;
12   showStatus('Analyzing architecture notes...', 'loading');
13   hideNodeDetails();
14
15
16   try {
17       // Call backend /map endpoint
18       const response = await fetch(`${API_URL}/map`, {
19           method: 'POST',
20           headers: {
21               'Content-Type': 'application/json'
22           },
23           body: JSON.stringify({ notes: notes })
24       });
25
26
27       if (!response.ok) {
28           const error = await response.json();
29           throw new Error(error.detail || 'Failed to generate map');
30       }
31
32
33       const systemMap = await response.json();
34      
35       // Render the graph
36       renderGraph(systemMap);
37       showStatus(`Generated map with ${systemMap.nodes.length} components`, 'success');
38      
39       setTimeout(hideStatus, 3000);
40   } catch (error) {
41       showStatus(`Error: ${error.message}`, 'error');
42       console.error('Map generation error:', error);
43   } finally {
44       generateBtn.disabled = false;
45   }
46}

Create the render graph function:

1function renderGraph(systemMap) {
2
3
4   cy.elements().remove();
5
6
7   const elements = [];
8
9
10   systemMap.nodes.forEach(node => {
11       elements.push({
12           data: {
13               id: node.id,
14               label: node.label,
15               team: node.team,
16               type: node.type,
17               description: node.description,
18               color: TEAM_COLORS[node.team] || DEFAULT_COLOR
19           }
20       });
21   });
22
23
24   systemMap.edges.forEach(edge => {
25       elements.push({
26           data: {
27               source: edge.source,
28               target: edge.target,
29               relationship: edge.relationship
30           }
31       });
32   });
33
34
35   cy.add(elements);
36
37
38   cy.layout({
39       name: 'breadthfirst',
40       directed: true,
41       padding: 50,
42       spacingFactor: 1.5,
43       animate: true,
44       animationDuration: 500
45   }).run();
46
47
48   cy.fit(50);
49}

Configure event listeners and page initialization:

1document.getElementById('generateBtn').addEventListener('click', generateMap);
2
3
4document.addEventListener('DOMContentLoaded', initGraph);

With that, your frontend is fully set up: the HTML provides the interface, Cytoscape visualizes the system graph, and app.js handles data fetching, graph rendering, and interactivity, ready to communicate with your backend /map endpoint.

Step 4: Dockerization

Backend Dockerfile:

1# Use official Python runtime as base image
2FROM python:3.11-slim
3
4
5# Set working directory inside container
6WORKDIR /app
7
8
9# Copy requirements first (Docker layer caching optimization)
10COPY requirements.txt .
11
12
13# Install Python dependencies
14RUN pip install --no-cache-dir -r requirements.txt
15
16
17# Copy application code
18COPY app.py .
19
20
21# Expose port 8000 for FastAPI
22EXPOSE 8000
23
24
25# Run the application
26# Uses uvicorn ASGI server for production-grade performance
27CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

Backend requirements.txt:

1fastapi==0.115.0
2uvicorn[standard]==0.32.0
3httpx==0.24.1
4openai==1.3.0
5pydantic==2.9.2
6python-multipart==0.0.12

Frontend Dockerfile:

1# Use nginx to serve static files
2FROM nginx:alpine
3
4
5# Copy frontend files to nginx's default directory
6COPY index.html /usr/share/nginx/html/
7COPY app.js /usr/share/nginx/html/
8
9
10# Expose port 80
11EXPOSE 80
12
13
14# nginx starts automatically with the base image

Build and push images:

1# Build backend image
2docker build -t YOUR_REGISTRY/system-mapper-backend:latest .
3# Push backend image
4docker push YOUR_REGISTRY/system-mapper-backend:latest
5# Build frontend image
6docker build -t YOUR_REGISTRY/system-mapper-frontend:latest .
7# Push frontend image
8docker push YOUR_REGISTRY/system-mapper-frontend:latest

Step 5: Deploy on Civo Kubernetes

Backend deployment YAML:

1# ---------------------------------------------------------
2# Namespace
3# ---------------------------------------------------------
4apiVersion: v1
5kind: Namespace
6metadata:
7 name: system-mapper
8
9
10---
11# ---------------------------------------------------------
12# RelaxAI Secret (replace YOUR_API_KEY_HERE with actual key)
13# ---------------------------------------------------------
14apiVersion: v1
15kind: Secret
16metadata:
17 name: relaxai-secret
18 namespace: system-mapper
19type: Opaque
20stringData:
21 api-key: "YOUR_API_KEY_HERE"
22
23
24---
25# ---------------------------------------------------------
26# Backend Deployment
27# ---------------------------------------------------------
28apiVersion: apps/v1
29kind: Deployment
30metadata:
31 name: backend
32 namespace: system-mapper
33 labels:
34   app: backend
35spec:
36 replicas: 2
37 selector:
38   matchLabels:
39     app: backend
40 template:
41   metadata:
42     labels:
43       app: backend
44   spec:
45     containers:
46     - name: backend
47       image: YOUR_REGISTRY/system-mapper-backend:latest  # Replace with your image
48       ports:
49       - containerPort: 8000
50         name: http
51      
52       env:
53       - name: RELAXAI_API_KEY
54         valueFrom:
55           secretKeyRef:
56             name: relaxai-secret
57             key: api-key
58      
59       resources:
60         requests:
61           memory: "512Mi"
62           cpu: "500m"
63         limits:
64           memory: "1Gi"
65           cpu: "1000m"
66      
67       livenessProbe:
68         httpGet:
69           path: /health
70           port: 8000
71         initialDelaySeconds: 10
72         periodSeconds: 30
73      
74       readinessProbe:
75         httpGet:
76           path: /health
77           port: 8000
78         initialDelaySeconds: 5
79         periodSeconds: 10
80
81
82---
83# ---------------------------------------------------------
84# Backend Service (LoadBalancer)
85# ---------------------------------------------------------
86apiVersion: v1
87kind: Service
88metadata:
89 name: backend-service
90 namespace: system-mapper
91spec:
92 type: LoadBalancer
93 selector:
94   app: backend
95 ports:
96 - protocol: TCP
97   port: 8000
98   targetPort: 8000

Apply it:

1kubectl apply -f kubernetes/backend-deployment.yaml

Frontend deployment YAML:

1# ---------------------------------------------------------
2# Frontend Deployment
3# ---------------------------------------------------------
4# Serves the static HTML/JS interface via nginx
5apiVersion: apps/v1
6kind: Deployment
7metadata:
8 name: frontend
9 namespace: system-mapper
10 labels:
11   app: frontend
12spec:
13 replicas: 2
14 selector:
15   matchLabels:
16     app: frontend
17 template:
18   metadata:
19     labels:
20       app: frontend
21   spec:
22     containers:
23     - name: frontend
24       image: YOUR_REGISTRY/system-mapper-frontend:latest  # Replace with your image
25       ports:
26       - containerPort: 80
27         name: http
28      
29       resources:
30         requests:
31           memory: "128Mi"
32           cpu: "100m"
33         limits:
34           memory: "256Mi"
35           cpu: "200m"
36      
37       # Health check (nginx has a /health endpoint from the config)
38       livenessProbe:
39         httpGet:
40           path: /
41           port: 80
42         initialDelaySeconds: 10
43         periodSeconds: 30
44      
45       readinessProbe:
46         httpGet:
47           path: /
48           port: 80
49         initialDelaySeconds: 5
50         periodSeconds: 10
51
52
53---
54# ---------------------------------------------------------
55# Frontend Service (LoadBalancer)
56# ---------------------------------------------------------
57# Exposes the frontend to the internet
58apiVersion: v1
59kind: Service
60metadata:
61 name: frontend-service
62 namespace: system-mapper
63spec:
64 type: LoadBalancer
65 selector:
66   app: frontend
67 ports:
68 - protocol: TCP
69   port: 80          # External port (access via http://<EXTERNAL-IP>)
70   targetPort: 80    # Container port

Apply it:

1kubectl apply -f kubernetes/frontend-deployment.yaml

Verify deployments and get external IPs:

1kubectl get pods -n system-mapper
2kubectl get svc -n system-mapper

Step 6: Test and Visualize

With both the backend and frontend deployed, it’s time to verify that your system mapper works as expected. You can do this by entering real architecture notes in the frontend input box and checking whether the generated system map appears correctly in the browser.

Use this text in the frontend input box:

Our e-commerce platform: React frontend (UI) calls API Gateway (Platform). Gateway routes to User Service (Identity) for authentication using PostgreSQL, Product Service (Catalog) managing inventory with MongoDB and Elasticsearch, and Order Service (Commerce) processing payments via Stripe with PostgreSQL. All services publish events to Kafka (Platform). Background workers include Order Processor (Commerce) reading RabbitMQ for async payment tasks, and Analytics Worker (Data) consuming Kafka events to load Snowflake warehouse. Order Service calls Product Service to verify stock before checkout. Admin Dashboard (Operations) connects directly to Order Service and Product Service for management tasks.

If the system is configured correctly, the backend will extract components and their relationships, normalize the data into the required JSON format, and the frontend will render an interactive system map.

LLM-Driven System Boundary & Responsibility Mapper on Civo 3

This tutorial is small and focused, meant to serve as a solid starting point rather than a toy example. While the example inputs are simple, the same pipeline can handle longer documents, multiple texts at once, or integration into real-world applications. When scaling up like this, GPU acceleration helps keep processing fast and responsive. Since the cluster is already GPU-enabled, you can move from simple experiments to larger production workloads without changing the architecture.

Summary

You've just built a tool that solves a problem every growing team faces: keeping architecture knowledge accessible and up-to-date. By combining LLMs with Civo's GPU-ready infrastructure, you transformed unstructured text into interactive diagrams in seconds, eliminating manual diagramming, stale docs, and knowledge silos.

This pattern extends beyond system maps. Use the same approach for API dependency tracking, data flow visualization, or team responsibility matrices. Add authentication, save/load features, or integrate with your existing docs platform. The foundation is there; scale it as your needs grow.

Additional Resources

To learn more about the technologies used in this tutorial and explore next steps, check out these resources:

LLM-driven system boundary & responsibility mapper on Civo

Prerequisites

Project Structure

Step 1: Create and connect to your Civo Kubernetes cluster

Step 2: Build the backend

Step 3: Build the frontend

Create the frontend files

Index.html

app.js

Step 4: Dockerization

Step 5: Deploy on Civo Kubernetes

Step 6: Test and Visualize

Summary

Additional Resources

Company

Company

Public Cloud

Public Cloud

Private Cloud

Private Cloud

Civo AI

Civo AI

Solutions

Solutions

Resources

Resources

Contact

Contact

Legal

Social