stack_compiler/
ir.rs

1//! Normalized renderer-independent diagram representation.
2
3/// A supported language version.
4#[derive(Debug, Clone, Copy, PartialEq, Eq)]
5pub struct LanguageVersion {
6    /// Language major version.
7    pub major: u32,
8    /// Language minor version.
9    pub minor: u32,
10}
11
12/// A semantically valid normalized Stack diagram.
13#[derive(Debug, Clone, PartialEq, Eq)]
14pub struct Diagram {
15    /// Declared language version.
16    pub language_version: LanguageVersion,
17    /// Visible diagram title.
18    pub title: String,
19    /// Effective theme identifier after language defaults.
20    pub theme_id: String,
21    /// Direct root children in declaration order.
22    pub children: Vec<ElementId>,
23    /// Nodes in declaration order.
24    pub nodes: Vec<Node>,
25    /// Groups in declaration order.
26    pub groups: Vec<Group>,
27    /// Edges in declaration order.
28    pub edges: Vec<Edge>,
29    /// Optional diagram-scoped layout input.
30    pub layout: Option<Layout>,
31}
32
33/// A typed reference to one direct layout or containment child.
34#[derive(Debug, Clone, PartialEq, Eq, Hash)]
35pub enum ElementId {
36    /// Node identifier.
37    Node(String),
38    /// Group identifier.
39    Group(String),
40}
41
42impl ElementId {
43    /// Returns the underlying Stack identifier.
44    pub fn as_str(&self) -> &str {
45        match self {
46            Self::Node(identifier) | Self::Group(identifier) => identifier,
47        }
48    }
49}
50
51/// A normalized architectural node.
52#[derive(Debug, Clone, PartialEq, Eq)]
53pub struct Node {
54    /// Globally unique source identifier.
55    pub id: String,
56    /// Visible node label.
57    pub label: String,
58    /// Effective semantic node kind.
59    pub kind: NodeKind,
60    /// Optional theme or namespaced provider icon identifier.
61    pub icon_id: Option<String>,
62    /// Optional visible detail.
63    pub detail: Option<String>,
64    /// Nearest containing group, if any.
65    pub parent_group_id: Option<String>,
66}
67
68/// Coarse architectural meaning of a node.
69#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
70pub enum NodeKind {
71    /// Person, role, team, or autonomous participant.
72    Actor,
73    /// Browser, application, device, or other client.
74    Client,
75    /// Long-running application, API, gateway, or general component.
76    Service,
77    /// On-demand or serverless compute unit.
78    Function,
79    /// Background processor or scheduled job.
80    Worker,
81    /// Durable queryable datastore.
82    Database,
83    /// Disposable or derived datastore.
84    Cache,
85    /// Queue, stream, bus, or broker.
86    Queue,
87    /// Blob, object, file, or archival storage.
88    Storage,
89    /// System outside the architecture's control boundary.
90    External,
91}
92
93/// A normalized containment group.
94#[derive(Debug, Clone, PartialEq, Eq)]
95pub struct Group {
96    /// Globally unique source identifier.
97    pub id: String,
98    /// Visible group label.
99    pub label: String,
100    /// Nearest containing group, if any.
101    pub parent_group_id: Option<String>,
102    /// Direct children in declaration order.
103    pub children: Vec<ElementId>,
104    /// Optional group-scoped layout input.
105    pub layout: Option<Layout>,
106}
107
108/// A normalized relationship between two nodes.
109#[derive(Debug, Clone, PartialEq, Eq)]
110pub struct Edge {
111    /// Left or source endpoint identifier.
112    pub from: String,
113    /// Right or target endpoint identifier.
114    pub to: String,
115    /// Effective directionality.
116    pub direction: EdgeDirection,
117    /// Effective semantic relationship kind.
118    pub kind: EdgeKind,
119    /// Optional visible edge label.
120    pub label: Option<String>,
121}
122
123/// Normalized edge directionality.
124#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
125pub enum EdgeDirection {
126    /// Directed from `from` to `to`.
127    Forward,
128    /// Symmetric in both directions.
129    Bidirectional,
130    /// Directionless or intentionally unspecified.
131    Association,
132}
133
134/// Semantic relationship kind.
135#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
136pub enum EdgeKind {
137    /// Generic runtime or conceptual flow.
138    Flow,
139    /// Synchronous request or call.
140    Request,
141    /// Asynchronous message or event delivery.
142    Event,
143    /// Data movement, replication, read, or write.
144    Data,
145    /// Build-time, deployment-time, or operational dependency.
146    Dependency,
147}
148
149/// Normalized layout constraints and hints for one scope.
150#[derive(Debug, Clone, PartialEq, Eq)]
151pub struct Layout {
152    /// Optional preferred flow direction.
153    pub direction: Option<Direction>,
154    /// Disjoint same-rank constraints.
155    pub same_ranks: Vec<Vec<String>>,
156    /// Optional relative-order hint.
157    pub order: Option<Vec<String>>,
158}
159
160/// Preferred layout direction.
161#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
162pub enum Direction {
163    /// Prefer left-to-right progression.
164    Right,
165    /// Prefer top-to-bottom progression.
166    Down,
167}
stack_compiler/ir.rs

stack_compiler/
ir.rs
