From da436a45b2e180ab09796f88b42d13bcd0810437 Mon Sep 17 00:00:00 2001
From: Ronald Tse <ronald.tse@ribose.com>
Date: Thu, 9 Jul 2026 07:20:20 +0800
Subject: [PATCH] docs: add README.adoc with architecture, CLI, and API docs

---
 README.adoc | 131 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 131 insertions(+)
 create mode 100644 README.adoc

diff --git a/README.adoc b/README.adoc
new file mode 100644
index 0000000..45f37e6
--- /dev/null
+++ b/README.adoc
@@ -0,0 +1,131 @@
+= ea
+Ronald Tse <open.source@ribose.com>
+:doctype: article
+:toc: left
+:toclevels: 3
+:source-highlighter: highlightjs
+
+Standalone Ruby gem for parsing Sparx Enterprise Architect data files
+(QEA SQLite database and Sparx XMI). Pure parse, optional bridge to
+`lutaml-uml` for cross-vendor UML output and SPA generation.
+
+== Installation
+
+ gem install ea
+
+For SPA generation (optional):
+
+ gem install ea lutaml-uml
+
+Or in your Gemfile:
+
+ source "https://rubygems.org"
+ gem "ea", "~> 0.2"
+ gem "lutaml-uml", "~> 0.5"   # optional: SPA + SVG diagram rendering
+
+== Quick start
+
+=== Parse a QEA file (pure — no lutaml-uml needed)
+
+[source,ruby]
+----
+require "ea"
+
+db = Ea.parse("model.qea")   #=> Ea::Qea::Database
+puts "#{db.packages.size} packages, #{db.objects.size} objects"
+----
+
+=== Generate a SPA from QEA (requires lutaml-uml)
+
+[source,bash]
+----
+ea spa model.qea --output browser.html
+----
+
+Produces a single-file Vue IIFE HTML (~300KB for a typical model)
+with package hierarchy, class details, and diagram navigation.
+
+=== Generate Sparx XMI from QEA (pure — no lutaml-uml)
+
+[source,bash]
+----
+ea convert model.qea --to xmi --output model.xmi
+----
+
+=== Extract a diagram as SVG (requires lutaml-uml)
+
+[source,bash]
+----
+ea diagrams extract model.qea "Diagram Name" --output diagram.svg
+----
+
+== Architecture
+
+The ea gem has two layers:
+
+=== Pure layer (no lutaml-uml dependency)
+
+[cols="1,2"]
+|===
+| `Ea.parse(path)` | Returns `Ea::Qea::Database` (.qea) or `Xmi::Sparx::Root` (.xmi)
+| `Ea::Transformers::QeaToXmi` | Converts `Ea::Qea::Database` → Sparx XMI string
+| `Ea::Qea.load(path)` | Low-level QEA loader → `Ea::Qea::Database`
+| `Ea::Xmi.load(path)` | Low-level XMI loader → `Xmi::Sparx::Root`
+|===
+
+=== Bridge layer (optional — lazy-requires lutaml-uml)
+
+[cols="1,2"]
+|===
+| `Ea.to_uml(path_or_model)` | Returns `Lutaml::Uml::Document` (tool-agnostic)
+| `Ea::Bridge::QeaToUml` | `Ea::Qea::Database` → `Lutaml::Uml::Document`
+| `Ea::Bridge::XmiToUml` | `Xmi::Sparx::Root` → `Lutaml::Uml::Document`
+|===
+
+=== Data flow
+
+----
+QEA file ──→ Ea::Qea::Database  ──┐
+                                   ├──→ Ea::Bridge ──→ Lutaml::Uml::Document
+XMI file ──→ Xmi::Sparx::Root    ──┘                        │
+                                                           ├──→ SPA (HTML)
+                                                           ├──→ SVG diagram
+                                                           └──→ cross-vendor output
+
+QEA file ──→ Ea::Qea::Database  ──→ Ea::Transformers::QeaToXmi ──→ Sparx XMI
+                                    (pure, no lutaml-uml)
+----
+
+== CLI commands
+
+[cols="1,3"]
+|===
+| `ea spa FILE` | Generate single-page app from QEA/XMI/LUR
+| `ea list FILE` | List model elements (auto-detects QEA or XMI)
+| `ea diagrams list FILE` | List diagrams in a QEA/XMI file
+| `ea diagrams extract FILE NAME` | Render a diagram to SVG
+| `ea validate FILE` | Validate EA model
+| `ea stats FILE` | Show collection counts
+| `ea parse FILE` | Parse to internal model representation
+| `ea convert FILE --to xmi` | Convert QEA → Sparx XMI
+| `ea version` | Show gem version
+|===
+
+== Limitations
+
+- **Sparx only**: QEA format and Sparx-flavored XMI only. Does not parse
+  MagicDraw or Papyrus XMI.
+- **XMI parser**: Parses `<xmi:Extension>` blocks for Sparx-specific
+  diagram metadata. Generic OMG XMI is handled by the `xmi` gem.
+
+== Development
+
+ git clone https://github.com/lutaml/ea
+ cd ea
+ bundle install
+ bundle exec rspec        # run specs (2036 examples)
+ bundle exec ea help      # see CLI commands
+
+== License
+
+MIT — see `LICENSE` file.