How-to Guides

Importing landscapes

This guide shows how to import and maintain landscapes as code using the LandscapeImportData JSON schema.

This is useful for:

  • Generating diagrams with LLMs
  • Syncing landscapes via CI/CD pipelines
  • Maintaining diagrams in a git repository

Prerequisites:

  • IcePanel account
  • API key (created from https://app.icepanel.io/organizations/:organizationId/manage/api-keys)

Steps

1

Select a landscape

To import diagrams into a landscape, you will need the landscape ID, which can be found in the URL:

https://app.icepanel.io/landscapes/:landscapeId/versions/latest/overview

Or, you can get the landscape ID with a GET request to the /landscapes endpoint.

GET
/v1/organizations/:organizationId/landscapes
1import { IcePanelClient } from "@icepanel/sdk";
2
3async function main() {
4    const client = new IcePanelClient({
5        apiKey: "YOUR_API_KEY_HERE",
6    });
7    await client.organizations.landscapes.list("organizationId");
8}
9main();
Try it

This returns a list of all landscapes in your organization. Note the id of the landscape you want to import into.

2

Create your import file

Your landscape can be modelled in a JSON or YAML file by using the LandscapeImportData JSON schema. Each data model has a persistent id field, which is useful for upserting existing models.

1{
2"modelObjects": [
3{
4  "id": "domain-ecommerce",
5  "name": "E-Commerce Platform",
6  "parentId": null,
7  "type": "domain"
8},
9
10{
11  "id": "person-customer",
12  "name": "Customer",
13  "parentId": "domain-ecommerce",
14  "type": "actor",
15  "tagIds": ["tag-external"]
16},
17{
18  "id": "person-admin",
19  "name": "Admin User",
20  "parentId": "domain-ecommerce",
21  "type": "actor",
22  "tagIds": ["tag-internal"]
23},
24
25{
26  "id": "system-storefront",
27  "name": "Storefront",
28  "parentId": "domain-ecommerce",
29  "type": "system",
30  "tagIds": ["tag-internal"]
31},
32{
33  "id": "system-payment",
34  "name": "Payment Gateway",
35  "parentId": "domain-ecommerce",
36  "type": "system",
37  "tagIds": ["tag-external"]
38},
39{
40  "id": "system-email",
41  "name": "Email Service",
42  "parentId": "domain-ecommerce",
43  "type": "system",
44  "tagIds": ["tag-external"]
45},
46
47{
48  "id": "container-web",
49  "name": "Web App",
50  "parentId": "system-storefront",
51  "type": "app",
52  "tagIds": ["tag-internal"]
53},
54{
55  "id": "container-api",
56  "name": "API Server",
57  "parentId": "system-storefront",
58  "type": "app",
59  "tagIds": ["tag-internal"]
60},
61{
62  "id": "container-db",
63  "name": "Product Database",
64  "parentId": "system-storefront",
65  "type": "database",
66  "tagIds": ["tag-internal"]
67},
68{
69  "id": "container-cache",
70  "name": "Cache",
71  "parentId": "system-storefront",
72  "type": "database",
73  "tagIds": ["tag-internal"]
74},
75
76{
77  "id": "component-product-service",
78  "name": "Product Service",
79  "parentId": "container-api",
80  "type": "component",
81  "tagIds": ["tag-internal"]
82},
83{
84  "id": "component-order-service",
85  "name": "Order Service",
86  "parentId": "container-api",
87  "type": "component",
88  "tagIds": ["tag-internal"]
89},
90{
91  "id": "component-auth-service",
92  "name": "Auth Service",
93  "parentId": "container-api",
94  "type": "component",
95  "tagIds": ["tag-internal"]
96},
97{
98  "id": "component-notification-service",
99  "name": "Notification Service",
100  "parentId": "container-api",
101  "type": "component",
102  "tagIds": ["tag-internal"]
103}
104],
105
106"modelConnections": [
107{
108  "id": "conn-customer-web",
109  "name": "Browses store via HTTPS",
110  "direction": "outgoing",
111  "originId": "person-customer",
112  "targetId": "container-web"
113},
114{
115  "id": "conn-admin-web",
116  "name": "Manages catalog via HTTPS",
117  "direction": "outgoing",
118  "originId": "person-admin",
119  "targetId": "container-web"
120},
121{
122  "id": "conn-web-api",
123  "name": "REST API calls",
124  "direction": "outgoing",
125  "originId": "container-web",
126  "targetId": "container-api"
127},
128{
129  "id": "conn-api-db",
130  "name": "Reads/writes",
131  "direction": "outgoing",
132  "originId": "container-api",
133  "targetId": "container-db"
134},
135{
136  "id": "conn-api-cache",
137  "name": "Caches product data",
138  "direction": "outgoing",
139  "originId": "container-api",
140  "targetId": "container-cache"
141},
142{
143  "id": "conn-order-payment",
144  "name": "Processes payment",
145  "direction": "outgoing",
146  "originId": "component-order-service",
147  "targetId": "system-payment"
148},
149{
150  "id": "conn-notification-email",
151  "name": "Sends order confirmations",
152  "direction": "outgoing",
153  "originId": "component-notification-service",
154  "targetId": "system-email"
155},
156{
157  "id": "conn-product-db",
158  "name": "Queries product catalog",
159  "direction": "outgoing",
160  "originId": "component-product-service",
161  "targetId": "container-db"
162},
163{
164  "id": "conn-auth-db",
165  "name": "Reads user records",
166  "direction": "outgoing",
167  "originId": "component-auth-service",
168  "targetId": "container-db"
169},
170{
171  "id": "conn-order-notification",
172  "name": "Triggers notifications",
173  "direction": "outgoing",
174  "originId": "component-order-service",
175  "targetId": "component-notification-service"
176}
177],
178
179"tagGroups": [
180{
181  "id": "tag-group-ownership",
182  "name": "Ownership",
183  "icon": "tag"
184}
185],
186
187"tags": [
188{
189  "id": "tag-internal",
190  "name": "Internal",
191  "color": "blue",
192  "groupId": "tag-group-ownership"
193},
194{
195  "id": "tag-external",
196  "name": "External",
197  "color": "orange",
198  "groupId": "tag-group-ownership"
199}
200]
201}
1# yaml-language-server: $schema=https://api.icepanel.io/v1/schemas/LandscapeImportData
2
3tagGroups:
4- id: tag-group-ownership
5name: Ownership
6icon: tag
7
8tags:
9- id: tag-internal
10name: Internal
11color: blue
12groupId: tag-group-ownership
13- id: tag-external
14name: External
15color: orange
16groupId: tag-group-ownership
17
18modelObjects:
19- id: domain-ecommerce
20name: E-Commerce Platform
21type: domain
22
23- id: person-customer
24name: Customer
25type: actor
26parentId: domain-ecommerce
27tagIds:
28  - tag-external
29
30- id: person-admin
31name: Admin User
32type: actor
33parentId: domain-ecommerce
34tagIds:
35  - tag-internal
36
37- id: system-storefront
38name: Storefront
39type: system
40parentId: domain-ecommerce
41tagIds:
42  - tag-internal
43
44- id: system-payment
45name: Payment Gateway
46type: system
47parentId: domain-ecommerce
48tagIds:
49  - tag-external
50
51- id: system-email
52name: Email Service
53type: system
54parentId: domain-ecommerce
55tagIds:
56  - tag-external
57
58- id: container-web
59name: Web App
60type: app
61parentId: system-storefront
62tagIds:
63  - tag-internal
64
65- id: container-api
66name: API Server
67type: app
68parentId: system-storefront
69tagIds:
70  - tag-internal
71
72- id: container-db
73name: Product Database
74type: database
75parentId: system-storefront
76tagIds:
77  - tag-internal
78
79- id: container-cache
80name: Cache
81type: database
82parentId: system-storefront
83tagIds:
84  - tag-internal
85
86- id: component-product-service
87name: Product Service
88type: component
89parentId: container-api
90tagIds:
91  - tag-internal
92
93- id: component-order-service
94name: Order Service
95type: component
96parentId: container-api
97tagIds:
98  - tag-internal
99
100- id: component-auth-service
101name: Auth Service
102type: component
103parentId: container-api
104tagIds:
105  - tag-internal
106
107- id: component-notification-service
108name: Notification Service
109type: component
110parentId: container-api
111tagIds:
112  - tag-internal
113
114modelConnections:
115- id: conn-customer-web
116name: Browses store via HTTPS
117direction: outgoing
118originId: person-customer
119targetId: container-web
120
121- id: conn-admin-web
122name: Manages catalog via HTTPS
123direction: outgoing
124originId: person-admin
125targetId: container-web
126
127- id: conn-web-api
128name: REST API calls
129direction: outgoing
130originId: container-web
131targetId: container-api
132
133- id: conn-api-db
134name: Reads/writes
135direction: outgoing
136originId: container-api
137targetId: container-db
138
139- id: conn-api-cache
140name: Caches product data
141direction: outgoing
142originId: container-api
143targetId: container-cache
144
145- id: conn-order-payment
146name: Processes payment
147direction: outgoing
148originId: component-order-service
149targetId: system-payment
150
151- id: conn-notification-email
152name: Sends order confirmations
153direction: outgoing
154originId: component-notification-service
155targetId: system-email
156
157- id: conn-product-db
158name: Queries product catalog
159direction: outgoing
160originId: component-product-service
161targetId: container-db
162
163- id: conn-auth-db
164name: Reads user records
165direction: outgoing
166originId: component-auth-service
167targetId: container-db
168
169- id: conn-order-notification
170name: Triggers notifications
171direction: outgoing
172originId: component-order-service
173targetId: component-notification-service
3

Import your landscape

You can import the file through the UI or the API.

Each id in your import file maps to a resource in IcePanel. It’s either created if the resource does not exist or updated otherwise.

From the landscape page, click Import model > File Upload and upload your file.

Import landscape file

4

Set up CI/CD

To keep your landscape in sync automatically, call the import endpoint in a CI/CD job on every push to your main branch.

Add two repository secrets in GitHub (Settings > Secrets and variables > Actions):

  • ICEPANEL_LANDSCAPE_ID
  • ICEPANEL_API_KEY

Create a workflow file at .github/workflows/icepanel-sync.yml:

your-project
.github
workflows
icepanel-sync.yml
icepanel-landscape-import.yaml
README.md
.github/workflows/icepanel-sync.yml
1name: Synchronise IcePanel landscape
2
3on:
4  push:
5    branches:
6      - main
7      - master
8
9jobs:
10  synchronise-landscape:
11    runs-on: ubuntu-latest
12    steps:
13      - uses: actions/checkout@v4
14
15      - name: Import landscape
16        run: |
17          curl -sf -X POST "https://api.icepanel.io/v1/landscapes/${{ vars.ICEPANEL_LANDSCAPE_ID }}/versions/latest/import" \
18            -H "X-API-Key: ${{ secrets.ICEPANEL_API_KEY }}" \
19            -H "Content-Type: application/yaml" \
20            --data-binary @icepanel-landscape-import.yaml

This triggers the synchronise-landscape job on every push to main/master.

Generating diagrams with LLMs

LLMs can generate a valid import file from a description of your architecture. The LandscapeImportData schema is publicly accessible, so you can point the LLM directly at it to validate the output.

See an example prompt that generates an import file for IcePanel.

Prompt
Generate an IcePanel landscape import data model based on the C4 model from the infrastructure and software architecture of the platform.
Parse infrastructure files to understand the platform and use it to map the infrastructure into C4 model abstraction.
Do not create objects or connections that don't exist or are strongly implied by the infrastructure.
Fetch LandscapeImportData JSONSchema from api.icepanel.io/v1/schemas/LandscapeImportData along with nested schemas and strictly follow the schema to create a YAML file for import into IcePanel.
Fetch docs.icepanel.io/core-features/modelling.md for context on how to create IcePanel C4 model structures.
Infrastructure can be categorized into technologies by fetching the JSONSchema from api.icepanel.io/v1/schemas/CatalogTechnologyType.
Perform an exhaustive search for technologies using http requests to api.icepanel.io/v1/catalog/technologies?filter[name]=NodeJS and add the id to the technologyIds array.
If a technology cannot be found try reducing the search term to be more specific to find a match.
If a primary technology exists then assign the visual icon to icon.technologyId.
Write the resulting import data to a YAML file to the file named icepanel-landscape-import.yaml in the current directory.
Prefix the YAML file with # yaml-language-server: $schema=https://api.icepanel.io/v1/schemas/LandscapeImportData.

Example output:

1# yaml-language-server: $schema=https://api.icepanel.dev/v1/schemas/LandscapeImportData
2
3modelObjects:
4
5  # ── Domain ────────────────────────────────────────────────────────────────
6
7  - id: domain-icepanel
8    name: IcePanel Platform
9    type: domain
10    description: >-
11      IcePanel is a multi-tenant SaaS platform for collaborative software
12      architecture documentation and diagramming using C4 model notation.
13      Deployed on Google Cloud Platform.
14
15  # ── Actors ────────────────────────────────────────────────────────────────
16
17  - id: actor-user
18    name: Software Architect / Developer
19    parentId: domain-icepanel
20    type: actor
21    description: >-
22      Software engineers and architects who use IcePanel to create, maintain,
23      and share C4 architecture diagrams collaboratively with their teams.
24
25  # ── Visual Groups ─────────────────────────────────────────────────────────
26
27  - id: group-external-services
28    name: External Services
29    parentId: domain-icepanel
30    type: group
31    description: Third-party SaaS services that IcePanel integrates with.
32
33  - id: group-source-integrations
34    name: Source Code Platforms
35    parentId: domain-icepanel
36    type: group
37    description: Source code hosting and DevOps platforms that users can link to architecture objects.
38
39  # ── Systems ───────────────────────────────────────────────────────────────
40
41  - id: system-icepanel
42    name: IcePanel
43    parentId: domain-icepanel
44    type: system
45    external: false
46    description: >-
47      Multi-tenant SaaS platform for creating and maintaining collaborative C4
48      architecture diagrams. Runs as a collection of microservices on Google
49      Cloud Platform using Cloud Run, backed by Firestore, Redis, and Cloud
50      Storage.
51
52  - id: system-stripe
53    name: Stripe
54    parentId: domain-icepanel
55    type: system
56    external: true
57    groupIds:
58      - group-external-services
59    description: >-
60      Payment processing platform used for subscription billing, plan management,
61      and payment collection across multiple currencies (CAD, EUR, GBP, USD).
62
63  - id: system-openai
64    name: OpenAI
65    parentId: domain-icepanel
66    type: system
67    external: true
68    groupIds:
69      - group-external-services
70    description: >-
71      AI platform providing large language models used to power AI-assisted
72      architecture modelling and description generation features.
73
74  - id: system-mixpanel
75    name: Mixpanel
76    parentId: domain-icepanel
77    type: system
78    external: true
79    groupIds:
80      - group-external-services
81    description: >-
82      Product analytics platform for tracking user behaviour, feature adoption,
83      and engagement metrics to guide product decisions.
84
85  - id: system-sentry
86    name: Sentry2
87    parentId: domain-icepanel
88    type: system
89    external: true
90    groupIds:
91      - group-external-services
92    description: >-
93      Application error monitoring and performance tracking service that captures
94      runtime exceptions and alerts the engineering team.
95
96  - id: system-resend
97    name: Resend
98    parentId: domain-icepanel
99    type: system
100    external: true
101    groupIds:
102      - group-external-services
103    description: >-
104      Transactional email delivery service used to send user invitations,
105      onboarding sequences, and notification emails.
106
107  - id: system-slack
108    name: Slack
109    parentId: domain-icepanel
110    type: system
111    external: true
112    groupIds:
113      - group-external-services
114    description: >-
115      Team messaging platform that receives automated architecture change
116      notifications triggered by IcePanel automation rules configured by users.
117
118  - id: system-linear
119    name: Linear
120    parentId: domain-icepanel
121    type: system
122    external: true
123    groupIds:
124      - group-external-services
125    description: >-
126      Issue tracking platform used internally for bug tracking and for surfacing
127      customer-reported issues to the engineering team.
128
129  - id: system-datadog
130    name: Datadog
131    parentId: domain-icepanel
132    type: system
133    external: true
134    groupIds:
135      - group-external-services
136    description: >-
137      Infrastructure monitoring, APM, and log management platform used to
138      observe service health, performance, and operational metrics.
139
140  - id: system-github
141    name: GitHub
142    parentId: domain-icepanel
143    type: system
144    external: true
145    groupIds:
146      - group-source-integrations
147    description: >-
148      Source code hosting platform that users can link to architecture objects
149      and that powers the CI/CD pipeline for IcePanel deployments.
150
151  - id: system-gitlab
152    name: GitLab
153    parentId: domain-icepanel
154    type: system
155    external: true
156    groupIds:
157      - group-source-integrations
158    description: >-
159      Source code and DevOps platform that IcePanel integrates with for
160      repository and pipeline linking within architecture diagrams.
161
162  - id: system-azure-devops
163    name: Azure DevOps
164    parentId: domain-icepanel
165    type: system
166    external: true
167    groupIds:
168      - group-source-integrations
169    description: >-
170      Microsoft Azure DevOps platform that IcePanel integrates with for source
171      repository linking and pipeline integrations.
172
173  - id: system-bitbucket
174    name: Bitbucket
175    parentId: domain-icepanel
176    type: system
177    external: true
178    groupIds:
179      - group-source-integrations
180    description: >-
181      Atlassian source code hosting platform that IcePanel integrates with for
182      repository linking within architecture objects.
183
184  # ── IcePanel Containers ───────────────────────────────────────────────────
185
186  - id: app-web
187    name: Web Application
188    parentId: system-icepanel
189    type: app
190    caption: Vue.js SPA
191    description: >-
192      Single-page application built with Vue.js 3, TypeScript, Pinia, Vuetify,
193      Pixi.js, and TipTap that provides the main user interface for collaborative
194      C4 architecture modelling and diagram editing. Built with Vite and served
195      via Google Cloud CDN.
196
197  - id: app-api
198    name: API Service
199    parentId: system-icepanel
200    type: app
201    caption: Node.js REST API
202    description: >-
203      Core REST API service built with Node.js, TypeScript, and Express that
204      handles all business logic including authentication, landscape management,
205      model CRUD operations, billing, and external service integrations.
206      Deployed on Cloud Run. API contract defined with an OpenAPI specification
207      and TypeScript client auto-generated via SDK generation.
208
209  - id: app-realtime
210    name: Real-time Service
211    parentId: system-icepanel
212    type: app
213    caption: Node.js / Socket.IO
214    description: >-
215      WebSocket service built with Node.js and Socket.IO that broadcasts
216      real-time model change events to connected clients, enabling live
217      multi-user collaboration on shared architecture diagrams. Deployed on
218      Cloud Run and scaled horizontally with Redis pub/sub coordination.
219
220  - id: app-action-log
221    name: Action Log Service 2
222    parentId: system-icepanel
223    type: app
224    caption: Node.js Worker
225    description: >-
226      Background service that subscribes to Firestore change events via Cloud
227      Pub/Sub, records a full audit trail of architecture changes, updates
228      contributor statistics, and exports analytics data to BigQuery.
229      Deployed on Cloud Run and triggered via Eventarc.
230
231  - id: app-automation
232    name: Automation Service
233    parentId: system-icepanel
234    type: app
235    caption: Node.js Event Processor
236    description: >-
237      Event-driven service that evaluates user-configured automation rules when
238      architecture changes occur and triggers configured actions such as Slack
239      notifications or synchronising external tool integrations. Deployed on
240      Cloud Run and triggered via Eventarc.
241
242  - id: app-render
243    name: Render Service
244    parentId: system-icepanel
245    type: app
246    caption: Node.js / Puppeteer
247    description: >-
248      Headless browser service built with Puppeteer that renders C4 architecture
249      diagrams to high-quality PDF and PNG files for export. Deployed on Cloud
250      Run and triggered asynchronously via Cloud Pub/Sub.
251
252  - id: app-pubsub
253    name: Cloud Pub/Sub
254    parentId: system-icepanel
255    type: app
256    caption: Message Broker
257    description: >-
258      Google Cloud Pub/Sub message broker with Eventarc triggers that route
259      Firestore document change events to background processing services,
260      decoupling the API service from asynchronous processing workflows.
261
262  - id: store-firestore
263    name: Cloud Firestore
264    parentId: system-icepanel
265    type: store
266    caption: Primary Database
267    description: >-
268      Google Cloud Firestore NoSQL document database serving as the primary data
269      store for all landscape data including model objects, connections, diagrams,
270      flows, comments, tags, and user data. Supports real-time listeners used by
271      the real-time service for live collaboration.
272
273  - id: store-redis
274    name: Cloud Memorystore (Redis)
275    parentId: system-icepanel
276    type: store
277    caption: Cache & Pub/Sub
278    description: >-
279      Managed Redis instance used for API response caching to reduce Firestore
280      read latency, and for pub/sub coordination across multiple Cloud Run
281      instances of the real-time service to ensure all clients receive updates.
282    technologyIds:
283      - 4IpQAof5QthfBnNHOq6H
284    icon:
285      technologyId: 4IpQAof5QthfBnNHOq6H
286
287  - id: store-gcs
288    name: Cloud Storage
289    parentId: system-icepanel
290    type: store
291    caption: File Storage
292    description: >-
293      Google Cloud Storage buckets used for storing user-uploaded assets,
294      technology catalog icons, exported diagram files (PDF/PNG), and
295      application data backups.
296    technologyIds:
297      - 3cc0cIZIk4Mos3HufC7q
298    icon:
299      technologyId: 3cc0cIZIk4Mos3HufC7q
300
301  - id: store-bigquery
302    name: BigQuery
303    parentId: system-icepanel
304    type: store
305    caption: Analytics Warehouse
306    description: >-
307      Google Cloud BigQuery serverless data warehouse used to store and query
308      platform-level analytics including user activity, feature usage, and
309      business metrics exported by the Action Log service.
310    technologyIds:
311      - 1LjoEJGZgj1Ec7nCVgvB
312    icon:
313      technologyId: 1LjoEJGZgj1Ec7nCVgvB
314
315modelConnections:
316
317  # ── User ──────────────────────────────────────────────────────────────────
318
319  - id: conn-user-web
320    name: Models architecture
321    originId: actor-user
322    targetId: app-web
323    direction: outgoing
324    description: >-
325      Architects and developers access IcePanel through a web browser to create,
326      edit, and collaborate on C4 architecture diagrams.
327
328  # ── Web Application ───────────────────────────────────────────────────────
329
330  - id: conn-web-api
331    name: API calls
332    originId: app-web
333    targetId: app-api
334    direction: outgoing
335    description: >-
336      The SPA communicates with the API service over HTTPS using a generated
337      TypeScript client (from the OpenAPI spec) to perform all CRUD operations
338      on landscapes, model objects, connections, and diagrams.
339
340  - id: conn-web-realtime
341    name: Live collaboration
342    originId: app-web
343    targetId: app-realtime
344    direction: outgoing
345    description: >-
346      The web application maintains a persistent WebSocket (Socket.IO) connection
347      to receive real-time model change events pushed by other collaborators
348      editing the same landscape.
349
350  # ── API Service ───────────────────────────────────────────────────────────
351
352  - id: conn-api-firestore
353    name: Reads and writes data
354    originId: app-api
355    targetId: store-firestore
356    direction: outgoing
357    description: >-
358      The API service uses Firestore as its primary data store, performing reads
359      and writes on all model data using transactions and optimistic concurrency
360      control via commit counters.
361
362  - id: conn-api-redis
363    name: Caches responses
364    originId: app-api
365    targetId: store-redis
366    direction: outgoing
367    description: >-
368      The API service caches frequently accessed Firestore data in Redis to
369      reduce read latency and Firestore costs.
370
371  - id: conn-api-gcs
372    name: Stores files
373    originId: app-api
374    targetId: store-gcs
375    direction: outgoing
376    description: >-
377      The API service stores user-uploaded files and technology catalog icons
378      in Cloud Storage buckets.
379
380  - id: conn-api-pubsub
381    name: Publishes events
382    originId: app-api
383    targetId: app-pubsub
384    direction: outgoing
385    description: >-
386      Firestore document change events are routed via Eventarc triggers to Cloud
387      Pub/Sub topics, which fan out to downstream background processing services.
388
389  - id: conn-api-stripe
390    name: Manages subscriptions
391    originId: app-api
392    targetId: system-stripe
393    direction: outgoing
394    description: >-
395      The API service integrates with Stripe to manage customer subscriptions,
396      process payments, handle plan upgrades and downgrades, and respond to
397      billing webhook events across multiple currencies.
398
399  - id: conn-api-openai
400    name: AI-powered features
401    originId: app-api
402    targetId: system-openai
403    direction: outgoing
404    description: >-
405      The API service calls OpenAI language models to power AI-assisted
406      architecture modelling features such as generating diagram content
407      from natural language descriptions.
408
409  - id: conn-api-resend
410    name: Sends emails
411    originId: app-api
412    targetId: system-resend
413    direction: outgoing
414    description: >-
415      The API service sends transactional emails via Resend for user invitations,
416      team notifications, and onboarding email sequences.
417
418  - id: conn-api-mixpanel
419    name: Tracks product usage
420    originId: app-api
421    targetId: system-mixpanel
422    direction: outgoing
423    description: >-
424      The API service sends product usage and feature adoption events to Mixpanel
425      to power analytics dashboards and guide product decisions.
426
427  - id: conn-api-sentry
428    name: Reports errors
429    originId: app-api
430    targetId: system-sentry
431    direction: outgoing
432    description: >-
433      The API service uses the Sentry SDK to capture and report runtime
434      exceptions and performance issues for monitoring and debugging.
435
436  - id: conn-api-linear
437    name: Creates issues
438    originId: app-api
439    targetId: system-linear
440    direction: outgoing
441    description: >-
442      The API service creates Linear issues for internal tracking of bugs and
443      customer-reported problems escalated through the support workflow.
444
445  - id: conn-api-datadog
446    name: Sends metrics and logs
447    originId: app-api
448    targetId: system-datadog
449    direction: outgoing
450    description: >-
451      The API service emits operational metrics, traces, and structured logs to
452      Datadog for infrastructure monitoring and performance observability.
453
454  # ── Real-time Service ─────────────────────────────────────────────────────
455
456  - id: conn-realtime-firestore
457    name: Listens for changes
458    originId: app-realtime
459    targetId: store-firestore
460    direction: outgoing
461    description: >-
462      The real-time service subscribes to Firestore real-time listeners on
463      landscape collections and forwards change events to all connected
464      WebSocket clients for live diagram updates.
465
466  - id: conn-realtime-redis
467    name: Coordinates instances
468    originId: app-realtime
469    targetId: store-redis
470    direction: outgoing
471    description: >-
472      The real-time service uses Redis pub/sub to propagate change events across
473      multiple stateless Cloud Run instances, ensuring every connected client
474      receives updates regardless of which instance they are connected to.
475
476  # ── Cloud Pub/Sub ─────────────────────────────────────────────────────────
477
478  - id: conn-pubsub-actionlog
479    name: Action events
480    originId: app-pubsub
481    targetId: app-action-log
482    direction: outgoing
483    description: >-
484      Cloud Pub/Sub delivers Firestore document change events to the Action Log
485      service for recording change history and updating contributor statistics.
486
487  - id: conn-pubsub-automation
488    name: Architecture events
489    originId: app-pubsub
490    targetId: app-automation
491    direction: outgoing
492    description: >-
493      Cloud Pub/Sub delivers architecture change events to the Automation service
494      to evaluate and trigger configured automation rules.
495
496  - id: conn-pubsub-render
497    name: Export requests
498    originId: app-pubsub
499    targetId: app-render
500    direction: outgoing
501    description: >-
502      Cloud Pub/Sub delivers diagram export requests to the Render service for
503      asynchronous PDF and PNG generation.
504
505  # ── Action Log Service ────────────────────────────────────────────────────
506
507  - id: conn-actionlog-firestore
508    name: Records history
509    originId: app-action-log
510    targetId: store-firestore
511    direction: outgoing
512    description: >-
513      The Action Log service writes processed action events, contributor
514      statistics, and versioned change history back to Cloud Firestore.
515
516  - id: conn-actionlog-bigquery
517    name: Exports analytics
518    originId: app-action-log
519    targetId: store-bigquery
520    direction: outgoing
521    description: >-
522      The Action Log service exports aggregated usage and analytics data to
523      BigQuery for platform-level reporting and business intelligence queries.
524
525  # ── Automation Service ────────────────────────────────────────────────────
526
527  - id: conn-automation-firestore
528    name: Reads automation rules
529    originId: app-automation
530    targetId: store-firestore
531    direction: outgoing
532    description: >-
533      The Automation service reads user-configured automation rules and landscape
534      data from Firestore and writes automation execution results back.
535
536  - id: conn-automation-slack
537    name: Sends notifications
538    originId: app-automation
539    targetId: system-slack
540    direction: outgoing
541    description: >-
542      The Automation service sends architecture change notifications to
543      user-configured Slack channels via the Slack Web API.
544
545  - id: conn-automation-github
546    name: Syncs with repositories
547    originId: app-automation
548    targetId: system-github
549    direction: outgoing
550    description: >-
551      The Automation service integrates with GitHub to link architecture objects
552      to source code repositories and respond to repository events.
553
554  - id: conn-automation-gitlab
555    name: Syncs with repositories
556    originId: app-automation
557    targetId: system-gitlab
558    direction: outgoing
559    description: >-
560      The Automation service integrates with GitLab for source code repository
561      linking and event-driven architecture updates.
562
563  - id: conn-automation-azuredevops
564    name: Syncs with repositories
565    originId: app-automation
566    targetId: system-azure-devops
567    direction: outgoing
568    description: >-
569      The Automation service integrates with Azure DevOps for source code
570      repository and pipeline linking within architecture diagrams.
571
572  - id: conn-automation-bitbucket
573    name: Syncs with repositories
574    originId: app-automation
575    targetId: system-bitbucket
576    direction: outgoing
577    description: >-
578      The Automation service integrates with Bitbucket for source code repository
579      linking and event-driven integrations.
580
581  # ── Render Service ────────────────────────────────────────────────────────
582
583  - id: conn-render-gcs
584    name: Saves exports
585    originId: app-render
586    targetId: store-gcs
587    direction: outgoing
588    description: >-
589      The Render service saves generated PDF and PNG diagram exports to Cloud
590      Storage, from where users can download them via the API.
591
592tagGroups:
593  - id: tg-deployment
594    name: Deployment
595    icon: cloud
596
597tags:
598  - id: tag-cloud-run
599    name: Cloud Run
600    groupId: tg-deployment
601    color: blue
602
603  - id: tag-gcp
604    name: Google Cloud Platform
605    groupId: tg-deployment
606    color: dark-blue

Prune option

By default, data models that exist in IcePanel but are missing from your import file are left untouched. To have IcePanel delete models not present in the import file, add the prune=true query parameter.

Note that prune=true is a destructive operation. Any model objects, connections, tags, or tag groups in IcePanel that are not in your import file will be permanently deleted. Make sure your import file is the complete source of truth before using this option.

$curl -sf -X POST "https://api.icepanel.io/v1/landscapes/$ICEPANEL_LANDSCAPE_ID/versions/latest/import?prune=true" \
>  -H "X-API-Key: $ICEPANEL_API_KEY" \
>  -H "Content-Type: application/yaml" \
>  --data-binary @icepanel-landscape-import.yaml