# cyriux/livingdocumentation-workshop architecture

> Architecture diagram of the GitHub repository cyriux/livingdocumentation-workshop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cyriux/livingdocumentation-workshop
- Repository: https://github.com/cyriux/livingdocumentation-workshop

## Overview

This repository is a Java/Maven workshop project centered on “living documentation,” not a single production app. The codebase combines example domain models, documentation-generation assets, and a few architecture patterns used as teaching material.

1. **Top-level purpose**
   The repo is split between:
   - workshop content and generated documentation artifacts (`*.html`, `*.md`, diagrams, cards, games)
   - example Java code under `src/main/java`
   - tests that exercise the living-documentation tooling and domain examples

2. **Core documentation/tooling layer**
   The `flottio.annotations` package defines custom markers such as `@BoundedContext`, `@DomainLayer`, `@InfrastructureLayer`, `@Entity`, `@ValueObject`, `@Repository`, `@ExternalActor`, and related tags. These annotations are the backbone of the documentation model: they classify code elements so diagrams, glossaries, and guided tours can be generated from the source.

3. **Living documentation generator**
   The `flottio.livingdocumentation` tests and supporting templates are the main automation layer for producing documentation outputs:
   - diagram generation
   - glossary generation
   - guided tours
   - word clouds
   - system diagrams
   The repo includes HTML/JS/CSS tooling (`strapdown`, `viz.js`, `d3.js`, Graphviz-related assets) to render these artifacts. This is essentially a documentation pipeline driven by source code and test fixtures.

4. **Fuel card monitoring bounded context**
   `flottio.fuelcardmonitoring` is the most complete domain example. It is organized into:
   - `domain`: business concepts and rules
   - `infra`: adapters to external systems and persistence/reporting
   - `infra.web`: web-facing resources
   - `legacy`: integration with an older vehicle datastore
   - `monitoring`: JMX-facing monitoring surface
   This is the main sample bounded context for demonstrating layered architecture and living documentation.

5. **Fuel card domain model**
   The `domain` package models the business language: `FuelCardTransaction`, `FuelCardTransactionReport`, `Vehicle`, `Merchant`, `Money`, `Coordinates`, `GeoDistance`, `FuelEconomy`, `Geocoding`, `LocationTracking`, and related units/types. The model suggests a flow where fuel-card events are analyzed against vehicle/location context to detect anomalies and produce reports.

6. **Fuel card infrastructure and integration**
   The infra layer contains adapters that connect the domain to outside concerns:
   - `FuelCardTxListener` for incoming transaction events
   - `ReportDAO` for report storage/access
   - `SmartGISGeoCodingAdapter` for geocoding
   - `WebServiceGPSTrackingAdapter` for GPS/location data
   - `FuelCardResource` and `ReportResource` as web entry points
   The architectural boundary is clear: domain logic stays separate from transport, persistence, and external service calls.

7. **Legacy and operational dependencies**
   `legacy.VehicleDatastore` represents an older system the domain depends on for vehicle data. `monitoring.FuelCardJMXBean` exposes operational visibility through JMX. These are important because they show the system is not isolated; it integrates with both legacy data sources and runtime management interfaces.

8. **Dispatching example**
   `flottio.dispatching` is a second bounded context, likely used to illustrate assignment/optimization concerns. It includes:
   - `DispatchingOptimizationService`
   - `FCAssignController`
   - `VehicleAssignmentEJB`
   - `VehicleAssignmentEntity`
   - `JMXBean`
   This area demonstrates a more service-oriented / enterprise-Java style boundary, with controller, service, persistence/entity, and management hooks.

9. **Preventative maintenance example**
   `flottio.preventativemaintenance` is a smaller domain model around `OdometerReading`, `VehicleMaintenanceJournal`, and `VehicleMaintenanceManual`. It appears to be a supporting bounded context used in workshop stories and likely feeds into the documentation examples rather than a full application stack.

10. **Tests as documentation inputs**
   Tests are not just verification; they are part of the workshop’s content pipeline. The `src/test/java/flottio/livingdocumentation` suite validates diagram, glossary, guided-tour, templating, and word-cloud generation. Domain tests under `fuelcardmonitoring` and `preventativemaintenance` act as executable examples of the business model.

11. **Workshop assets and reference material**
   The `cards`, `games`, `quick_developer_tour.md`, `livingglossary.md`, `livinggdiagram.html`, `systemdiagram.html`, and `wordcloud.html` files are workshop outputs or teaching aids. They are part of the learning experience and show the expected rendered results of the documentation system.

12. **Architecture boundaries to draw**
   A good diagram should show three main layers:
   - **Documentation/tooling layer**: annotations, templates, generators, rendered artifacts
   - **Domain/application examples**: fuel card monitoring, dispatching, preventative maintenance
   - **Infrastructure/external integration**: web resources, JMX, legacy datastore, GPS/geocoding adapters, DAO/reporting
   The strongest data flows run from domain events and model types into infrastructure adapters and then into generated documentation artifacts.

Main entry points: [`living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/domain`](https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/domain) (Fuel Domain), [`living-documentation-workshop`](https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop) (Workshop Output), [`living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/infra`](https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/infra) (Fuel Infra), [`living-documentation-workshop/src/test/java/flottio/livingdocumentation`](https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/test/java/flottio/livingdocumentation) (Doc Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Documentation"]
  node_annotations["Annotations<br/>doc model"]
  node_hexagonal_arch["Hexagonal<br/>pattern note"]
  node_living_tests["Doc Tests<br/>generator tests"]
  node_templates["Templates"]
  node_artifacts["Workshop Output<br/>rendered docs"]
end

subgraph group_domain["Domain Examples"]
  node_fuel_domain["Fuel Domain<br/>bounded context"]
  node_fuel_monitoring["Monitoring App<br/>domain service"]
  node_tx_model["Transactions<br/>entity model"]
  node_geo_model["Geo Model<br/>value objects<br/>[Coordinates.java]"]
  node_maintenance["Maintenance<br/>bounded context"]
  node_dispatching["Dispatching<br/>bounded context"]
  node_maintenance_tests["Domain Stories<br/>example tests"]
end

subgraph group_infra["Integration"]
  node_fuel_infra["Fuel Infra<br/>adapters"]
  node_fuel_web["Web API<br/>web resources"]
  node_fuel_legacy[("Legacy Store<br/>external system")]
  node_fuel_jmx(("Fuel JMX<br/>ops surface"))
  node_dispatch_ops["Dispatch Ops<br/>enterprise adapters"]
end

node_annotations -->|"drives"| node_living_tests
node_living_tests -->|"renders"| node_templates
node_living_tests -->|"produces"| node_artifacts
node_annotations -->|"tags"| node_fuel_domain
node_fuel_monitoring -->|"orchestrates"| node_tx_model
node_fuel_monitoring -->|"uses"| node_geo_model
node_fuel_domain -->|"depends on"| node_fuel_infra
node_fuel_infra -->|"exposes"| node_fuel_web
node_fuel_infra -->|"reads"| node_fuel_legacy
node_fuel_infra -->|"observes"| node_fuel_jmx
node_dispatching -->|"implemented by"| node_dispatch_ops
node_maintenance -->|"validated by"| node_maintenance_tests
node_fuel_domain -.->|"related example"| node_maintenance
node_fuel_domain -.->|"related example"| node_dispatching
node_artifacts -->|"documents"| node_fuel_domain
node_artifacts -->|"documents"| node_dispatching
node_artifacts -->|"documents"| node_maintenance

click node_annotations "https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/main/java/flottio/annotations"
click node_hexagonal_arch "https://github.com/cyriux/livingdocumentation-workshop/blob/master/living-documentation-workshop/src/main/java/flottio/annotations/hexagonalarchitecture/HexagonalArchitecture.java"
click node_living_tests "https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/test/java/flottio/livingdocumentation"
click node_templates "https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/test/resources/flottio/livingdocumentation"
click node_artifacts "https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop"
click node_fuel_domain "https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/domain"
click node_fuel_monitoring "https://github.com/cyriux/livingdocumentation-workshop/blob/master/living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/domain/FuelCardMonitoring.java"
click node_tx_model "https://github.com/cyriux/livingdocumentation-workshop/blob/master/living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/domain/FuelCardTransaction.java"
click node_geo_model "https://github.com/cyriux/livingdocumentation-workshop/blob/master/living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/domain/Coordinates.java"
click node_maintenance "https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/main/java/flottio/preventativemaintenance"
click node_dispatching "https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/main/java/flottio/dispatching"
click node_fuel_infra "https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/infra"
click node_fuel_web "https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/infra/web"
click node_fuel_legacy "https://github.com/cyriux/livingdocumentation-workshop/blob/master/living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/legacy/VehicleDatastore.java"
click node_fuel_jmx "https://github.com/cyriux/livingdocumentation-workshop/blob/master/living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/monitoring/FuelCardJMXBean.java"
click node_dispatch_ops "https://github.com/cyriux/livingdocumentation-workshop/blob/master/living-documentation-workshop/src/main/java/flottio/dispatching/VehicleAssignmentEJB.java"
click node_maintenance_tests "https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/test/java/flottio/preventativemaintenance"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_annotations,node_hexagonal_arch,node_living_tests,node_templates,node_artifacts toneBlue
class node_fuel_domain,node_fuel_monitoring,node_tx_model,node_geo_model,node_maintenance,node_dispatching,node_maintenance_tests toneAmber
class node_fuel_infra,node_fuel_web,node_fuel_legacy,node_fuel_jmx,node_dispatch_ops toneMint
```

## Components

### Documentation

Annotations, templates, tests, and rendered workshop artifacts that drive living documentation.

- [Annotations](https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/main/java/flottio/annotations): doc model · Custom markers that classify code for documentation and architecture views. · `living-documentation-workshop/src/main/java/flottio/annotations`
- [Hexagonal](https://github.com/cyriux/livingdocumentation-workshop/blob/master/living-documentation-workshop/src/main/java/flottio/annotations/hexagonalarchitecture/HexagonalArchitecture.java): pattern note · Reference model for architecture teaching material. · `living-documentation-workshop/src/main/java/flottio/annotations/hexagonalarchitecture/HexagonalArchitecture.java`
- [Doc Tests](https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/test/java/flottio/livingdocumentation): generator tests · Test suite that drives diagram, glossary, guided tour, and word cloud generation. · `living-documentation-workshop/src/test/java/flottio/livingdocumentation`
- [Templates](https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/test/resources/flottio/livingdocumentation): html templates · Template fixtures used to render generated workshop outputs. · `living-documentation-workshop/src/test/resources/flottio/livingdocumentation`
- [Workshop Output](https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop): rendered docs · HTML, markdown, cards, and games used as teaching artifacts. · `living-documentation-workshop`

### Domain Examples

Sample bounded contexts used to demonstrate architecture and documentation generation.

- [Fuel Domain](https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/domain): bounded context · Main business model for fuel card anomaly detection and reporting. · `living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/domain`
- [Monitoring App](https://github.com/cyriux/livingdocumentation-workshop/blob/master/living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/domain/FuelCardMonitoring.java): domain service · Entry point coordinating fuel-card monitoring logic. · `living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/domain/FuelCardMonitoring.java`
- [Transactions](https://github.com/cyriux/livingdocumentation-workshop/blob/master/living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/domain/FuelCardTransaction.java): entity model · Fuel-card transactions, reports, cards, merchants, money, and vehicle context. · `living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/domain/FuelCardTransaction.java`
- [Geo Model](https://github.com/cyriux/livingdocumentation-workshop/blob/master/living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/domain/Coordinates.java): value objects · Coordinates, distance, geocoding, location tracking, and related units. · `living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/domain/Coordinates.java`
- [Maintenance](https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/main/java/flottio/preventativemaintenance): bounded context · Small preventative maintenance example around odometer and service history. · `living-documentation-workshop/src/main/java/flottio/preventativemaintenance`
- [Dispatching](https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/main/java/flottio/dispatching): bounded context · Assignment and optimization example with controller, service, entity, and JMX surface. · `living-documentation-workshop/src/main/java/flottio/dispatching`
- [Domain Stories](https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/test/java/flottio/preventativemaintenance): example tests · Executable stories and tests for preventative maintenance examples. · `living-documentation-workshop/src/test/java/flottio/preventativemaintenance`

### Integration

Adapters, external interfaces, and operational surfaces around the sample domains.

- [Fuel Infra](https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/infra): adapters · Infrastructure boundary for events, persistence, geocoding, GPS, and web resources. · `living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/infra`
- [Web API](https://github.com/cyriux/livingdocumentation-workshop/tree/master/living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/infra/web): web resources · HTTP-facing resources for fuel-card operations and reports. · `living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/infra/web`
- [Legacy Store](https://github.com/cyriux/livingdocumentation-workshop/blob/master/living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/legacy/VehicleDatastore.java): external system · Older vehicle datastore consumed by the fuel-card domain. · `living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/legacy/VehicleDatastore.java`
- [Fuel JMX](https://github.com/cyriux/livingdocumentation-workshop/blob/master/living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/monitoring/FuelCardJMXBean.java): ops surface · Operational monitoring interface for the fuel-card bounded context. · `living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/monitoring/FuelCardJMXBean.java`
- [Dispatch Ops](https://github.com/cyriux/livingdocumentation-workshop/blob/master/living-documentation-workshop/src/main/java/flottio/dispatching/VehicleAssignmentEJB.java): enterprise adapters · Dispatching controller, EJB, entity, and management hook. · `living-documentation-workshop/src/main/java/flottio/dispatching/VehicleAssignmentEJB.java`

## Connections

- Annotations → Doc Tests: drives · Annotations enable source classification used by documentation generators.
- Doc Tests → Templates: renders · Tests render documentation artifacts from templates and fixtures.
- Doc Tests → Workshop Output: produces · Generator tests validate the workshop outputs.
- Annotations → Fuel Domain: tags · Domain code is marked for bounded-context and layer extraction.
- Monitoring App → Transactions: orchestrates · The monitoring entry point coordinates transaction analysis.
- Monitoring App → Geo Model: uses · Monitoring logic depends on geographic and distance concepts.
- Fuel Domain → Fuel Infra: depends on · Domain behavior is connected to adapters at the boundary.
- Fuel Infra → Web API: exposes · Web resources provide external access to the fuel-card context.
- Fuel Infra → Legacy Store: reads · Infrastructure integrates with the older vehicle datastore.
- Fuel Infra → Fuel JMX: observes · Operational monitoring is surfaced through JMX.
- Dispatching → Dispatch Ops: implemented by · The dispatching example is realized through service, entity, and controller components.
- Maintenance → Domain Stories: validated by · Preventative maintenance is primarily exercised through example tests.
- Fuel Domain → Maintenance: related example · Both contexts illustrate business-rule modeling for workshop stories.
- Fuel Domain → Dispatching: related example · Both bounded contexts demonstrate layered enterprise architecture.
- Workshop Output → Fuel Domain: documents · Generated material explains the sample domains and architecture.
- Workshop Output → Dispatching: documents · Workshop outputs include dispatching and pattern examples.
- Workshop Output → Maintenance: documents · Workshop outputs include preventative maintenance stories.
