sirena 0.1.0

data/docs/_diagram_types/architecture-diagram.adoc

@@ -0,0 +1,314 @@
+= Architecture Diagram
+:toc:
+:toclevels: 3
+
+== Purpose
+
+Architecture diagrams visualize software system architecture at different levels, showing system boundaries, services, components, and their relationships. This is useful for documenting system architecture, communicating design decisions, and understanding system topology.
+
+== Features
+
+=== General
+
+Architecture diagrams support:
+
+* Services with icons and labels
+* Grouping services into boundaries
+* Nested group hierarchies
+* Directional connections between services
+* Edge labels for protocols/technologies
+* Metadata (title, accessibility)
+
+The implementation follows Mermaid's `architecture-beta` syntax.
+
+=== Basic services
+
+Define services with icons and labels.
+
+Syntax:
+
+[source]
+----
+architecture-beta
+    service {id}({icon})[{label}]
+----
+
+Where,
+
+`id`:: Unique identifier for the service
+`icon`:: Icon type (database, server, disk, cloud, internet, browser, etc.)
+`label`:: Display label for the service
+
+.Defining basic services
+[example]
+====
+[source,mermaid]
+----
+architecture-beta
+    service db(database)[Database]
+    service api(server)[API Server]
+    service ui(browser)[Web UI]
+----
+
+This creates three services:
+
+* A database service with ID `db`
+* An API server with ID `api`
+* A web UI with ID `ui`
+====
+
+=== Service connections
+
+Connect services with directional arrows.
+
+Syntax:
+
+[source]
+----
+{from_id}:{from_pos} --> {to_pos}:{to_id}
+{from_id} --> {to_id}
+----
+
+Where,
+
+`from_id`:: Source service identifier
+`to_id`:: Target service identifier
+`from_pos`:: Optional position hint (L/R/T/B for left/right/top/bottom)
+`to_pos`:: Optional position hint for target side
+
+.Connecting services with position hints
+[example]
+====
+[source,mermaid]
+----
+architecture-beta
+    service db(database)[Database]
+    service server(server)[Server]
+
+    db:R --> L:server
+----
+
+This creates a connection from the right side of the database to the left side of the server.
+====
+
+=== Edge labels
+
+Add labels to connections to indicate protocols or technologies.
+
+Syntax:
+
+[source]
+----
+{from_id} --> {to_id}: {label}
+----
+
+Where,
+
+`label`:: Text describing the connection (e.g., HTTP, SQL, REST)
+
+.Adding edge labels
+[example]
+====
+[source,mermaid]
+----
+architecture-beta
+    service ui(browser)[Web UI]
+    service api(server)[API]
+    service db(database)[Database]
+
+    ui:R --> L:api: HTTP
+    api:R --> L:db: SQL
+----
+
+This shows the protocols used between services.
+====
+
+=== Groups and boundaries
+
+Group related services using boundaries.
+
+Syntax:
+
+[source]
+----
+group {id}({icon})[{label}]
+service {service_id}({icon})[{label}] in {group_id}
+----
+
+Where,
+
+`group_id`:: Identifier for the group
+`service_id`:: Service to place in the group
+`icon`:: Optional icon for the group (e.g., cloud)
+`label`:: Display label for the group boundary
+
+.Grouping services
+[example]
+====
+[source,mermaid]
+----
+architecture-beta
+    group api(cloud)[API Layer]
+
+    service db(database)[Database] in api
+    service server(server)[Server] in api
+
+    service gateway(internet)[Gateway]
+
+    gateway:R --> L:server
+----
+
+This creates an API Layer group containing the database and server, with an external gateway service.
+====
+
+=== Nested groups
+
+Create hierarchical group structures.
+
+Syntax:
+
+[source]
+----
+group {parent_id}[{label}]
+group {child_id}[{label}] in {parent_id}
+----
+
+.Creating nested groups
+[example]
+====
+[source,mermaid]
+----
+architecture-beta
+    group api[API]
+    group public[Public API] in api
+    group private[Private API] in api
+
+    service web(server)[Web Server] in public
+    service admin(server)[Admin Server] in private
+    service db(database)[Database] in private
+----
+
+This creates a hierarchical structure with public and private API groups within a main API group.
+====
+
+=== Title and accessibility
+
+Add metadata for documentation and accessibility.
+
+Syntax:
+
+[source]
+----
+architecture-beta
+    title {diagram title}
+    accTitle: {accessibility title}
+    accDescr: {accessibility description}
+----
+
+.Adding metadata
+[example]
+====
+[source,mermaid]
+----
+architecture-beta
+    title E-Commerce System Architecture
+    accTitle: System Architecture Diagram
+    accDescr: Shows the main components of the e-commerce platform
+
+    service ui(browser)[Web UI]
+    service api(server)[API Gateway]
+    service db(database)[Database]
+----
+====
+
+=== Icon types
+
+Common icon types supported:
+
+* `database` - Database systems
+* `server` - Application servers
+* `disk` - Storage systems
+* `cloud` - Cloud services
+* `internet` - Internet gateway
+* `browser` - Web browsers/clients
+
+Additional icon prefixes (for future extension):
+
+* `logos:{name}` - Logo icons (e.g., `logos:aws-s3`)
+* `fa:{name}` - Font Awesome icons (e.g., `fa:image`)
+
+== Implementation
+
+Architecture diagrams use a 7-file Parslet architecture:
+
+. **Model** ([`lib/sirena/diagram/architecture.rb`](lib/sirena/diagram/architecture.rb)) - Lutaml::Model classes for diagram structure
+. **Grammar** ([`lib/sirena/parser/grammars/architecture.rb`](lib/sirena/parser/grammars/architecture.rb)) - Parslet grammar for syntax parsing
+. **Transform** ([`lib/sirena/parser/transforms/architecture.rb`](lib/sirena/parser/transforms/architecture.rb)) - Converts parse tree to model
+. **Parser** ([`lib/sirena/parser/architecture.rb`](lib/sirena/parser/architecture.rb)) - Orchestrates parsing pipeline
+. **Layout** ([`lib/sirena/transform/architecture.rb`](lib/sirena/transform/architecture.rb)) - Positions elements spatially
+. **Renderer** ([`lib/sirena/renderer/architecture.rb`](lib/sirena/renderer/architecture.rb)) - Generates SVG output
+. **Tests** - Parser and renderer test suites
+
+The implementation follows MECE principles with clear separation of concerns between parsing, transformation, layout, and rendering stages.
+
+== Examples
+
+=== Simple three-tier architecture
+
+[source,mermaid]
+----
+architecture-beta
+    service ui(browser)[Web UI]
+    service api(server)[API Server]
+    service db(database)[Database]
+
+    ui:R --> L:api: HTTPS
+    api:R --> L:db: SQL
+----
+
+=== Microservices with groups
+
+[source,mermaid]
+----
+architecture-beta
+    group frontend[Frontend]
+    group backend[Backend Services]
+    group data[Data Layer]
+
+    service web(browser)[Web App] in frontend
+    service mobile(browser)[Mobile App] in frontend
+
+    service auth(server)[Auth Service] in backend
+    service orders(server)[Order Service] in backend
+    service inventory(server)[Inventory Service] in backend
+
+    service db(database)[Primary DB] in data
+    service cache(disk)[Cache] in data
+
+    web:B --> T:auth
+    mobile:B --> T:auth
+    auth:B --> T:db
+    orders:B --> T:db
+    inventory:R --> L:cache
+----
+
+=== Cloud architecture
+
+[source,mermaid]
+----
+architecture-beta
+    title Cloud Infrastructure
+
+    group aws(cloud)[AWS Cloud]
+
+    service lb(internet)[Load Balancer] in aws
+    service web(server)[Web Servers] in aws
+    service app(server)[App Servers] in aws
+    service db(database)[RDS Database] in aws
+    service s3(disk)[S3 Storage] in aws
+
+    lb:B --> T:web: HTTPS
+    web:B --> T:app: HTTP
+    app:R --> L:db: SQL
+    app:B --> T:s3: S3 API
+----

data/docs/_diagram_types/block-diagram.adoc

@@ -0,0 +1,345 @@
+= Block Diagrams
+:toc:
+:toclevels: 3
+
+== General
+
+Block diagrams in Sirena provide a column-based layout system for visualizing hierarchical structures, data flows, and system architectures using blocks and connections. Unlike flowcharts which use graph-based layouts, block diagrams arrange elements in a structured grid with explicit column positioning.
+
+Block diagrams are declared with the `block-beta` keyword and support:
+
+* Column-based layouts with configurable column counts
+* Blocks with optional labels and width specifications
+* Compound/nested blocks for hierarchical structures
+* Space placeholders for layout control
+* Connections between blocks (arrows and lines)
+* Multiple block shapes (rectangles, circles)
+* Styling directives for customization
+
+== Basic block diagram
+
+The simplest block diagram contains blocks arranged in columns:
+
+[source,mermaid]
+----
+block-beta
+  columns 2
+  A["Block A"]
+  B["Block B"]
+----
+
+This creates a two-column layout with two blocks side by side.
+
+== Block declarations
+
+=== Simple blocks
+
+Blocks can be declared with just an identifier:
+
+[source,mermaid]
+----
+block-beta
+  A
+  B
+  C
+----
+
+Without a label, the block displays its identifier as the label.
+
+=== Blocks with labels
+
+Blocks can have custom labels using bracket notation:
+
+[source,mermaid]
+----
+block-beta
+  id1["Custom Label"]
+  id2["Another Block"]
+----
+
+The label text appears inside the block, while the identifier is used for connections.
+
+=== Block widths
+
+Blocks can span multiple columns using width specifications:
+
+[source,mermaid]
+----
+block-beta
+  columns 3
+  A:2
+  B:1
+  C:3
+----
+
+Where:
+
+`A:2`:: Block A spans 2 columns
+`B:1`:: Block B spans 1 column (default)
+`C:3`:: Block C spans 3 columns (entire row)
+
+== Column layout
+
+=== Columns statement
+
+The `columns` directive specifies how many columns the layout uses:
+
+[source,mermaid]
+----
+block-beta
+  columns 3
+  A
+  B
+  C
+  D
+  E
+  F
+----
+
+This creates a grid with 3 columns. Blocks flow left to right, top to bottom.
+
+=== Default columns
+
+If no `columns` statement is provided, the default is 1 column (vertical layout):
+
+[source,mermaid]
+----
+block-beta
+  A
+  B
+  C
+----
+
+All blocks stack vertically in a single column.
+
+== Block shapes
+
+=== Rectangle shape (default)
+
+Blocks are rectangles by default, but can be explicitly labeled:
+
+[source,mermaid]
+----
+block-beta
+  A["Rectangle Block"]
+----
+
+=== Circle shape
+
+Use double parentheses for circular blocks:
+
+[source,mermaid]
+----
+block-beta
+  db(("Database"))
+----
+
+This creates a circular block, often used for databases or special nodes.
+
+== Compound blocks
+
+=== Basic compound blocks
+
+Compound blocks contain nested child blocks:
+
+[source,mermaid]
+----
+block-beta
+  block:group1
+    A
+    B
+    C
+  end
+----
+
+Where:
+
+`block:group1`:: Declares a compound block with ID "group1"
+`A`, `B`, `C`:: Child blocks nested inside
+`end`:: Closes the compound block
+
+=== Nested compound blocks
+
+Compound blocks can be nested:
+
+[source,mermaid]
+----
+block-beta
+  block:outer
+    A
+    block:inner
+      B
+      C
+    end
+    D
+  end
+----
+
+This creates a hierarchical structure with multiple levels.
+
+== Space placeholders
+
+=== Space blocks
+
+Use `space` to create empty cells in the grid:
+
+[source,mermaid]
+----
+block-beta
+  columns 3
+  A
+  space
+  B
+  C
+  space
+  space
+----
+
+Space blocks maintain grid alignment but don't render visually.
+
+== Connections
+
+=== Arrow connections
+
+Connect blocks with arrows using `-->`:
+
+[source,mermaid]
+----
+block-beta
+  A
+  B
+  A --> B
+----
+
+This draws an arrow from block A to block B.
+
+=== Line connections
+
+Use `---` for non-directed line connections:
+
+[source,mermaid]
+----
+block-beta
+  A
+  B
+  A --- B
+----
+
+This draws a simple line without an arrowhead.
+
+=== Multiple connections
+
+A block can have multiple connections:
+
+[source,mermaid]
+----
+block-beta
+  A
+  B
+  C
+  A --> B
+  A --> C
+  B --> C
+----
+
+== Styling
+
+=== Block styling
+
+Style individual blocks using the `style` directive:
+
+[source,mermaid]
+----
+block-beta
+  A["Styled Block"]
+  style A fill:#969,stroke:#333,stroke-width:4px
+----
+
+Where:
+
+`fill:#969`:: Background color
+`stroke:#333`:: Border color
+`stroke-width:4px`:: Border width
+
+=== Style properties
+
+Supported style properties include:
+
+* `fill` - Background color
+* `stroke` - Border color
+* `stroke-width` - Border thickness
+
+== Complete example
+
+Here's a comprehensive example showing various features:
+
+[source,mermaid]
+----
+block-beta
+  columns 3
+
+  db(("Database"))
+  space
+  api["API Server"]
+
+  block:services
+    auth["Auth Service"]
+    users["User Service"]
+    data["Data Service"]
+  end
+
+  web["Web Client"]:3
+
+  db --> services
+  services --> api
+  api --> web
+
+  style db fill:#69f,stroke:#333,stroke-width:2px
+  style api fill:#f96,stroke:#333,stroke-width:2px
+----
+
+This creates a multi-tier architecture diagram with:
+
+* 3-column layout
+* Circular database block
+* Compound services block
+* Full-width web client block
+* Connections showing data flow
+* Custom styling for key components
+
+== Implementation notes
+
+=== Column-based layout
+
+Unlike flowcharts that use graph algorithms, block diagrams use explicit column-based positioning. Blocks are placed in columns from left to right, wrapping to the next row when a row is full.
+
+=== Width calculation
+
+Block widths are calculated based on:
+
+* Explicit width specifications (`:N` syntax)
+* Label text dimensions
+* Minimum block size constraints
+
+=== Connection routing
+
+Connections are routed from the bottom center of the source block to the top center of the target block using straight lines. Future enhancements may include bezier curves for more aesthetic routing.
+
+=== Compound block rendering
+
+Compound blocks are rendered with:
+
+* Dashed border to indicate grouping
+* Padding around child blocks
+* Automatic height calculation based on children
+
+== Theme integration
+
+Block diagrams support full theme integration:
+
+* Block colors from theme palette
+* Border colors and styles
+* Text styling and fonts
+* Connection colors and styles
+
+All visual properties can be customized through themes or inline styling.