How cyriux/livingdocumentation-workshop works
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: domain Fuel Domain · living-documentation-workshop Workshop Output · infra Fuel Infra · livingdocumentation Doc Tests
Components 17
Documentation
Annotations, templates, tests, and rendered workshop artifacts that drive living documentation.
- Annotations · Custom markers that classify code for documentation and architecture views.
living-documentation-workshop/src/main/java/flottio/annotations - Hexagonal · Reference model for architecture teaching material.
living-documentation-workshop/src/main/java/flottio/annotations/hexagonalarchitecture/HexagonalArchitecture.java - Doc Tests · Test suite that drives diagram, glossary, guided tour, and word cloud generation.
living-documentation-workshop/src/test/java/flottio/livingdocumentation - Templates · Template fixtures used to render generated workshop outputs.
living-documentation-workshop/src/test/resources/flottio/livingdocumentation - Workshop Output · 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 · Main business model for fuel card anomaly detection and reporting.
living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/domain - Monitoring App · Entry point coordinating fuel-card monitoring logic.
living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/domain/FuelCardMonitoring.java - Transactions · Fuel-card transactions, reports, cards, merchants, money, and vehicle context.
living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/domain/FuelCardTransaction.java - Geo Model · Coordinates, distance, geocoding, location tracking, and related units.
living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/domain/Coordinates.java - Maintenance · Small preventative maintenance example around odometer and service history.
living-documentation-workshop/src/main/java/flottio/preventativemaintenance - Dispatching · Assignment and optimization example with controller, service, entity, and JMX surface.
living-documentation-workshop/src/main/java/flottio/dispatching - Domain Stories · 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 · Infrastructure boundary for events, persistence, geocoding, GPS, and web resources.
living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/infra - Web API · HTTP-facing resources for fuel-card operations and reports.
living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/infra/web - Legacy Store · Older vehicle datastore consumed by the fuel-card domain.
living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/legacy/VehicleDatastore.java - Fuel JMX · Operational monitoring interface for the fuel-card bounded context.
living-documentation-workshop/src/main/java/flottio/fuelcardmonitoring/monitoring/FuelCardJMXBean.java - Dispatch Ops · Dispatching controller, EJB, entity, and management hook.
living-documentation-workshop/src/main/java/flottio/dispatching/VehicleAssignmentEJB.java
Connections 17
- 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.