Skip to content

Commit 3483593

Browse files
shehab-asshehab-as
authored
Merge pull request #1 from IcePanel/shehab/add-intro-and-structure
Add Core Concepts and fix Introduction
2 parents 96ccd00 + 8b347df commit 3483593

20 files changed

Lines changed: 1192 additions & 147 deletions

‎fern/concepts/diagrams.mdx‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Diagrams
2+
3+
Diagrams are C4 visualisations of your model. They are views onto the underlying model [objects](/core-concepts/model-objects) and [connections](/core-concepts/model-connections). The model data exists independently of any diagram, and the same object can appear in multiple diagrams.
4+
5+
---
6+
7+
## Diagram types
8+
9+
Each diagram type maps to a C4 level of abstraction:
10+
11+
| Type | C4 Level | Description |
12+
| --- | --- | --- |
13+
| `context-diagram` | Level 1 | Shows a `system` in the context of its actors and external systems |
14+
| `app-diagram` | Level 2 | Shows the `app` and `store` containers inside a `system` |
15+
| `component-diagram` | Level 3 | Shows the `component` objects inside an `app` or `store` |
16+
17+
---
18+
19+
## Related concepts
20+
21+
- [Model Objects](/core-concepts/model-objects)
22+
- [Flows](/core-concepts/flows)
23+
- [Versions](/core-concepts/versions)

‎fern/concepts/domains.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Domains
2+
3+
Domains are named groupings that organise [model objects](/core-concepts/model-objects) into bounded contexts. They map closely to the <Tooltip tip="A software design approach that focuses on modeling software to match a domain. It divides a large system into bounded contexts, each of which have their own model.">Domain-Driven Design (DDD)</Tooltip>.
4+
5+
---
6+
7+
## What a domain is
8+
9+
Every model object in a version belongs to exactly one domain. Domains provide a way to segment a large architecture either by business unit (e.g., `Payments`) or by team ownership (e.g., `platform`).
10+
11+
---
12+
13+
## Creating domains
14+
15+
Create a domain in a version:
16+
17+
<EndpointRequestSnippet endpoint="POST /landscapes/{landscapeId}/versions/{versionId}/domains" />
18+
19+
---
20+
21+
## Filtering model objects by domain
22+
23+
Use the `GET` endpoint with query parameter `?filter[domainId]={domainId}` to filter objects.
24+
25+
<EndpointRequestSnippet endpoint="GET /landscapes/{landscapeId}/versions/{versionId}/model/objects" />
26+
27+
This is useful for extracting a bounded-context slice of the architecture for reports or external tools.
28+
29+
---
30+
31+
## Related concepts
32+
33+
- [Model Objects](/core-concepts/model-objects)
34+
- [Model Connections](/core-concepts/model-connections)

‎fern/concepts/flows.mdx‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Flows
2+
3+
Flows are step-by-step sequences that trace a path through your architecture model. Useful for documenting user journeys, request paths, data flows, or any scenario where ordering and directionality matter.
4+
5+
---
6+
7+
## What a flow is
8+
9+
A flow lives inside a [diagram](/core-concepts/diagrams) and consists of an ordered list of **steps**. Each step identifies a model [object](/core-concepts/model-objects) or [connection](/core-concepts/model-connections) that participates at that point in the sequence. When viewing a flow in the IcePanel UI, the relevant objects and connections are highlighted in order.
10+
11+
Flows are distinct from model connections: a connection represents a static relationship between two objects, while a flow represents a dynamic sequence that may traverse many objects and connections.
12+
13+
---
14+
15+
## Related concepts
16+
17+
- [Model Objects](/core-concepts/model-objects)
18+
- [Model Connections](/core-concepts/model-connections)
19+
- [Diagrams](/core-concepts/diagrams)

‎fern/concepts/landscapes.mdx‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Landscapes
2+
3+
A landscape is the primary workspace in IcePanel. It holds a complete C4 architecture model including all objects, connections, diagrams, flows, and versions.
4+
5+
---
6+
7+
## What a landscape contains
8+
9+
Each landscape is versioned. All models like objects, connections, diagrams, flows, and domains live inside a [version](/core-concepts/versions) of a landscape.
10+
11+
When you create a landscape, IcePanel automatically creates an initial `latest` version that you can modify immediately.
12+
13+
Create a landscape:
14+
15+
<EndpointRequestSnippet endpoint="POST /organizations/{organizationId}/landscapes" />
16+
17+
The response returns both the `landscape` and the initial `version` objects.
18+
19+
List all landscapes in your organization:
20+
21+
<EndpointRequestSnippet endpoint="GET /organizations/{organizationId}/landscapes" />
22+
23+
---
24+
25+
## URL patterns
26+
27+
Landscape endpoints are available in two forms.
28+
29+
**Organization-scoped** (includes org context, useful when you have the org ID in scope):
30+
```
31+
GET /organizations/{organizationId}/landscapes/{landscapeId}
32+
```
33+
34+
**Landscape-scoped** (shorter, useful when you already know the landscape ID):
35+
```
36+
GET /landscapes/{landscapeId}
37+
```
38+
39+
All version-scoped resources (model objects, diagrams, flows, etc.) use only the landscape-scoped pattern:
40+
```
41+
GET /landscapes/{landscapeId}/versions/{versionId}/model/objects
42+
```
43+
44+
You can also specify `latest` as a shorthand for getting the latest version:
45+
46+
```
47+
GET /landscapes/{landscapeId}/versions/latest/model/objects
48+
```
49+
50+
---
51+
52+
## Duplicate vs copy
53+
54+
IcePanel provides two operations for replicating a landscape:
55+
56+
| Operation | Description |
57+
| --- | --- |
58+
| **Duplicate** | Creates a full copy of the landscape within the same organization, including all versions and model content |
59+
| **Copy** | Copies the model content of a specific version into a different target landscape. This is useful for merging two models or seeding a new landscape from an existing one |
60+
61+
Duplicate a landscape:
62+
63+
<EndpointRequestSnippet endpoint="POST /landscapes/{landscapeId}/duplicate" />
64+
65+
Copy to another landscape:
66+
67+
<EndpointRequestSnippet endpoint="POST /landscapes/{landscapeId}/copy" />
68+
69+
---
70+
71+
## Related concepts
72+
73+
- [Versions](/core-concepts/versions)
74+
- [Model Objects](/core-concepts/model-objects)
75+
- [Diagrams](/core-concepts/diagrams)

‎fern/concepts/model-connections.mdx‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Model Connections
2+
3+
Model connections are the edges of the <Tooltip tip="Actors, systems, services, and components that make up your software architecture.">model objects</Tooltip> in your architecture. They represent relationships, dependencies, API calls, data flows, or any meaningful interaction between two model objects.
4+
5+
---
6+
7+
## Creating connections
8+
9+
<EndpointRequestSnippet endpoint="POST /landscapes/{landscapeId}/versions/{versionId}/model/connections" />
10+
11+
---
12+
13+
## Filtering connections
14+
15+
The `GET /model/connections` endpoint supports filtering:
16+
17+
| Query parameter | Description |
18+
| --- | --- |
19+
| `filter[originId]` | Connections starting from a specific object |
20+
| `filter[targetId]` | Connections ending at a specific object |
21+
| `filter[viaId]` | Connections passing through a specific object |
22+
| `filter[direction]` | `outgoing` or `bidirectional` |
23+
| `filter[status]` | Status lifecycle value |
24+
| `filter[tagIds][]` | One or more tag IDs |
25+
| `filter[technologyIds][]` | One or more technology IDs |
26+
| `filter[labels][key]` | Label key-value pair |
27+
| `filter[name]` | Partial name match |
28+
| `filter[linked]` | `true` to return only connections with at least one link |
29+
30+
---
31+
32+
## Status lifecycle
33+
34+
Connections share the same four-state lifecycle as [model objects](/core-concepts/model-objects):
35+
36+
| Status | Description |
37+
| --- | --- |
38+
| `live` | Active dependency or relationship |
39+
| `future` | Planned but not yet implemented |
40+
| `deprecated` | In use but being phased out |
41+
| `removed` | Retired, kept for historical reference |
42+
43+
---
44+
45+
## Related concepts
46+
47+
- [Model Objects](/core-concepts/model-objects)

‎fern/concepts/model-objects.mdx‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Model Objects
2+
3+
Model objects are the nodes in your architecture graph. They represent the actors, systems, services, and components that make up your software architecture.
4+
5+
---
6+
7+
## Object types
8+
9+
IcePanel uses the <Tooltip tip="Framework for visualising software architecture through four levels of abstraction: Context, Containers, Components, and Code">C4 model</Tooltip>'s levels of abstraction. Each object type maps to a C4 level:
10+
11+
| Type | C4 Level | Description |
12+
| --- | --- | --- |
13+
| `root` | — | The root node of every [domain](/core-concepts/domains). There is exactly one per domain. All top-level systems and actors are children of the root. |
14+
| `actor` | Level 1 | A person or external role that interacts with your architecture (e.g. "Customer", "Admin") |
15+
| `system` | Level 1 | A top-level software system (e.g. "IcePanel") |
16+
| `group` | Level 1 | A visual grouping (e.g. "Worker Pool", "Subnet") |
17+
| `app` | Level 2 | A deployable unit (container) inside a system: a service, web app, mobile app, or queue |
18+
| `store` | Level 2 | A persistent data store inside a system: a database, blob store, or cache |
19+
| `component` | Level 3 | An internal building block inside an `app` or `store` |
20+
21+
---
22+
23+
## The parent–child hierarchy
24+
25+
Model objects form a tree. Every object except `root` has a `parentId` pointing to its parent:
26+
27+
```
28+
root
29+
├── actor: Customer
30+
├── system: Payment Service
31+
│ ├── app: API Gateway
32+
│ │ ├── component: Auth Middleware
33+
│ │ └── component: Rate Limiter
34+
│ ├── app: Payment Processor
35+
│ └── store: Transactions DB
36+
└── system: Auth Platform (external)
37+
```
38+
39+
---
40+
41+
## Creating objects
42+
43+
To create a new object, specify the `landscapeId` and either the `versionId` or `latest`:
44+
<EndpointRequestSnippet endpoint="POST /landscapes/{landscapeId}/versions/{versionId}/model/objects" />
45+
46+
---
47+
48+
## Filtering objects
49+
50+
To find the root object (required as `parentId` when creating top-level objects), use the query parameter `?filter[type]=root`
51+
52+
<EndpointRequestSnippet endpoint="GET /landscapes/{landscapeId}/versions/{versionId}/model/objects" />
53+
54+
The `GET /model/objects` endpoint supports the following filters:
55+
56+
| Query parameter | Description |
57+
| --- | --- |
58+
| `filter[type]` | Object type |
59+
| `filter[status]` | Status lifecycle value |
60+
| `filter[parentId]` | Direct parent ID |
61+
| `filter[domainId]` | Domain ID |
62+
| `filter[external]` | `true` / `false` |
63+
| `filter[tagIds][]` | One or more tag IDs |
64+
| `filter[teamIds][]` | One or more team IDs |
65+
| `filter[technologyIds][]` | One or more technology IDs |
66+
| `filter[labels][key]` | Label key-value pair |
67+
| `filter[name]` | Partial name match |
68+
| `filter[linked]` | `true` to return only objects with at least one link |
69+
70+
---
71+
72+
## Status lifecycle
73+
74+
Objects and connections share a four-state lifecycle representing their architectural status:
75+
76+
```
77+
live → deprecated → removed → future
78+
```
79+
80+
| Status | Description |
81+
| --- | --- |
82+
| `live` | Current, active element |
83+
| `future` | Planned but not yet built |
84+
| `deprecated` | Still in use but being phased out |
85+
| `removed` | Retired, kept for historical reference |
86+
87+
Use the `filter[status]` query parameter to retrieve only objects with a given status.
88+
89+
---
90+
91+
## Related concepts
92+
93+
- [Model Connections](/core-concepts/model-connections)

‎fern/concepts/organizations.mdx‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Organizations
2+
3+
An organization is the top-level model in IcePanel. It owns all landscapes, manages billing, and controls who has access.
4+
5+
---
6+
7+
Every API key and every landscape belongs to exactly one organization. The `organizationId` is the first path parameter you'll need for most operations.
8+
9+
<EndpointRequestSnippet endpoint="GET /organizations/{organizationId}" />
10+
11+
---
12+
13+
## Related concepts
14+
15+
- [Landscapes](/core-concepts/landscapes)
16+
- [Versions](/core-concepts/versions)

0 commit comments

Comments
 (0)