# locationtech/jts architecture

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

- Interactive diagram: https://gitdiagram.com/locationtech/jts
- Repository: https://github.com/locationtech/jts

## Overview

1. Repository shape  
This is a multi-module Maven Java project centered on the JTS Topology Suite. The root aggregates reusable geometry libraries, user-facing tools, integration adapters, examples, and a large test corpus. The main architectural boundary is between the immutable-ish geometry core and everything that consumes or visualizes it.

2. Core geometry engine  
`modules/core` is the primary subsystem and contains the fundamental geometry model: `Coordinate`, `Geometry`, `Point`, `LineString`, `Polygon`, `GeometryFactory`, `PrecisionModel`, and related sequence/collection types. Most other modules depend on this layer. It is the canonical source of geometry state passed through the rest of the system.

3. Algorithm and operation layers  
The core module is organized around geometry-processing subsystems: `algorithm` for low-level numeric/topological routines, `operation` for higher-level tasks like buffer, overlay, union, distance, relate, validation, polygonize, and line merge, plus `simplify`, `triangulate`, `linearref`, `coverage`, and `precision`. The data flow is typically `Geometry` in → noding/indexing/graph construction → topological computation → new `Geometry` out.

4. Spatial indexing and robustness infrastructure  
A major architectural concern in JTS is robustness under floating-point error. That shows up in dedicated packages for precision reduction, common-bits handling, snap rounding, and robust overlay/relate variants. The indexing packages (`quadtree`, `strtree`, `kdtree`, `hprtree`, interval trees, sweep line) support performance-critical operations and are embedded beneath many algorithms rather than exposed as standalone application logic.

5. Geometry graph / noding / planar graph boundary  
Several internal subsystems model geometry as graphs of edges, nodes, and intersections (`geomgraph`, `planargraph`, `edgegraph`, `noding`). These are the connective tissue for overlay, relate, buffer, polygonization, and validation. Architecturally, they transform raw coordinate sequences into topological structures that downstream operations can reason about safely.

6. I/O and interchange adapters  
`modules/core` contains classic WKT/WKB/GML/KML readers and writers. `modules/io/common` adds GeoJSON and TWKB support, `modules/io/ora` supports Oracle geometries, and `modules/io/sde` supports SDE input. These modules form the ingest/egress boundary: external text/binary spatial formats are normalized into core `Geometry` objects, then serialized back out after processing.

7. TestBuilder application stack  
`modules/app` is the desktop application layer, centered on the TestBuilder GUI. Its internal structure is explicit: model classes hold editable layers/test cases, controllers coordinate commands and results, UI panels and dialogs present geometry, renderers paint layers, and tool classes handle interaction. The app is a visualization and editing shell around the same core geometry engine.

8. TestBuilder data flow  
In the GUI, geometry enters from WKT/WKB/shapefile/import dialogs, is stored in the model, edited via tools, and rendered through the Swing-based view layer. User actions invoke geometry functions, which are registered/reflected through function registries and invocation wrappers, then results are routed to result panels, inspectors, and export writers such as HTML, SVG, PNG, XML, or Java test cases.

9. Test runner subsystem  
`modules/tests` is a separate test-execution framework used by the XML-based geometry test suites. It parses test definitions, loads geometry operations/functions, executes them against inputs, and compares results with specialized matchers. This module is the bridge between static test data and the library’s operation APIs, and it also supports CLI execution and reporting.

10. Example and lab code  
`modules/example` is a documentation-oriented sample application layer showing how to use core APIs, IO readers/writers, prepared geometry, linear referencing, and operation classes. `modules/lab` contains experimental or exploratory algorithms such as overlay-area variants, edge-ray methods, medial axis, and custom union strategies. These are clearly separated from the stable core APIs and should be treated as incubating extensions.

11. Shared command-line and utility code  
There are small command-line entry points and utilities in the app and test modules, including JTSOp/TestRunner-related commands and general-purpose file, command, and stream helpers. These are thin orchestration layers: they parse inputs, call the geometry engine, and format results, but do not own geometry logic themselves.

12. Build, quality, and release infrastructure  
The repo uses Maven across modules and GitHub Actions for CI. Build tooling includes checkstyle/PMD configuration, release documentation, and multiple shell/batch launchers for the GUI and command-line tools. The architecture is therefore not just library-centric; it also includes a repeatable validation pipeline with broad test coverage and packaged desktop/CLI tooling.

Main entry points: [`modules/core/src/main/java/org/locationtech/jts/geom`](https://github.com/locationtech/jts/tree/master/modules/core/src/main/java/org/locationtech/jts/geom) (Geometry model), [`modules/core/src/main/java/org/locationtech/jts/operation`](https://github.com/locationtech/jts/tree/master/modules/core/src/main/java/org/locationtech/jts/operation) (Operations), [`modules/pom.xml`](https://github.com/locationtech/jts/blob/master/modules/pom.xml) (Modules POM), [`modules/app/src/main/java/org/locationtech/jtstest/testbuilder`](https://github.com/locationtech/jts/tree/master/modules/app/src/main/java/org/locationtech/jtstest/testbuilder) (TestBuilder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Repo"]
  node_pom_root["Root POM<br/>maven root<br/>[pom.xml]"]
  node_pom_modules["Modules POM<br/>maven aggregator<br/>[pom.xml]"]
end

subgraph group_core["Core engine"]
  node_core_geom[("Geometry model<br/>core model")]
  node_core_ops["Operations<br/>geometry ops"]
  node_core_alg["Algorithms"]
  node_core_noding["Noding & graphs<br/>topology graph"]
  node_core_index["Spatial indexes<br/>indexing"]
  node_core_precision["Precision tools<br/>robustness"]
  node_core_io["Core IO<br/>wkt/wkb/gml/kml"]
  node_core_prep["Prepared geom<br/>predicate accel"]
end

subgraph group_io["IO adapters"]
  node_io_common["Common IO<br/>geojson/twkb"]
  node_io_ora["Oracle IO<br/>oracle spatial"]
  node_io_sde["SDE IO<br/>sde reader"]
end

subgraph group_app["Desktop app"]
  node_app_builder["TestBuilder<br/>desktop GUI"]
  node_app_cmd["CLI tools<br/>command layer"]
  node_app_funcs["Function registry<br/>function bridge"]
  node_app_render["Rendering UI<br/>swing render"]
  node_app_model["App model<br/>edit model"]
end

subgraph group_tests["Test runner"]
  node_tests_runner["TestRunner<br/>xml harness"]
  node_tests_geomop["Geom ops<br/>operation adapters"]
  node_tests_xml["XML suites<br/>test corpus"]
end

subgraph group_extras["Examples & lab"]
  node_example_mod["Examples<br/>sample code"]
  node_lab_mod["Lab code<br/>experimental"]
end

subgraph group_build["Build & CI"]
  node_build_tools["Build tools<br/>quality config"]
  node_github_ci["GitHub Actions<br/>ci pipeline<br/>[build-and-test.yml]"]
end

node_pom_root -->|"aggregates"| node_pom_modules
node_pom_modules -->|"builds"| node_core_geom
node_pom_modules -->|"builds"| node_core_ops
node_pom_modules -->|"builds"| node_core_io
node_pom_modules -->|"builds"| node_io_common
node_pom_modules -->|"builds"| node_app_builder
node_pom_modules -->|"builds"| node_tests_runner
node_pom_modules -->|"builds"| node_example_mod
node_pom_modules -->|"builds"| node_lab_mod
node_core_geom -->|"uses"| node_core_alg
node_core_geom -->|"feeds"| node_core_noding
node_core_geom -->|"queries"| node_core_index
node_core_geom -->|"stabilizes"| node_core_precision
node_core_geom -->|"accelerates"| node_core_prep
node_core_ops -->|"depends on"| node_core_noding
node_core_ops -->|"depends on"| node_core_index
node_core_ops -->|"depends on"| node_core_precision
node_core_ops -->|"returns"| node_core_geom
node_core_alg -->|"accelerates"| node_core_index
node_core_io -->|"serializes"| node_core_geom
node_io_common -->|"extends"| node_core_geom
node_io_ora -->|"bridges"| node_core_geom
node_io_sde -->|"bridges"| node_core_geom
node_app_builder -->|"uses"| node_app_model
node_app_builder -->|"renders via"| node_app_render
node_app_builder -->|"invokes"| node_app_funcs
node_app_cmd -->|"parses"| node_core_io
node_app_cmd -->|"executes"| node_core_ops
node_app_funcs -->|"wraps"| node_core_ops
node_app_render -->|"draws"| node_core_geom
node_tests_runner -->|"loads"| node_tests_geomop
node_tests_geomop -->|"executes"| node_core_ops
node_tests_runner -->|"drives"| node_tests_xml
node_example_mod -->|"demonstrates"| node_core_geom
node_example_mod -->|"demonstrates"| node_core_ops
node_lab_mod -->|"experiments with"| node_core_ops
node_build_tools -->|"supports"| node_pom_root
node_github_ci -->|"enforces"| node_build_tools
node_github_ci -->|"runs"| node_tests_runner

click node_pom_root "https://github.com/locationtech/jts/blob/master/pom.xml"
click node_pom_modules "https://github.com/locationtech/jts/blob/master/modules/pom.xml"
click node_core_geom "https://github.com/locationtech/jts/tree/master/modules/core/src/main/java/org/locationtech/jts/geom"
click node_core_ops "https://github.com/locationtech/jts/tree/master/modules/core/src/main/java/org/locationtech/jts/operation"
click node_core_alg "https://github.com/locationtech/jts/tree/master/modules/core/src/main/java/org/locationtech/jts/algorithm"
click node_core_noding "https://github.com/locationtech/jts/tree/master/modules/core/src/main/java/org/locationtech/jts/noding"
click node_core_index "https://github.com/locationtech/jts/tree/master/modules/core/src/main/java/org/locationtech/jts/index"
click node_core_precision "https://github.com/locationtech/jts/tree/master/modules/core/src/main/java/org/locationtech/jts/precision"
click node_core_io "https://github.com/locationtech/jts/tree/master/modules/core/src/main/java/org/locationtech/jts/io"
click node_core_prep "https://github.com/locationtech/jts/tree/master/modules/core/src/main/java/org/locationtech/jts/geom/prep"
click node_io_common "https://github.com/locationtech/jts/tree/master/modules/io/common/src/main/java/org/locationtech/jts/io"
click node_io_ora "https://github.com/locationtech/jts/tree/master/modules/io/ora/src/main/java/org/locationtech/jts/io/oracle"
click node_io_sde "https://github.com/locationtech/jts/tree/master/modules/io/sde/src/main/java/org/locationtech/jts/io/sde"
click node_app_builder "https://github.com/locationtech/jts/tree/master/modules/app/src/main/java/org/locationtech/jtstest/testbuilder"
click node_app_cmd "https://github.com/locationtech/jts/tree/master/modules/app/src/main/java/org/locationtech/jtstest/cmd"
click node_app_funcs "https://github.com/locationtech/jts/tree/master/modules/app/src/main/java/org/locationtech/jtstest/geomfunction"
click node_app_render "https://github.com/locationtech/jts/tree/master/modules/app/src/main/java/org/locationtech/jtstest/testbuilder/ui"
click node_app_model "https://github.com/locationtech/jts/tree/master/modules/app/src/main/java/org/locationtech/jtstest/testbuilder/model"
click node_tests_runner "https://github.com/locationtech/jts/tree/master/modules/tests/src/main/java/org/locationtech/jtstest/testrunner"
click node_tests_geomop "https://github.com/locationtech/jts/tree/master/modules/tests/src/main/java/org/locationtech/jtstest/geomop"
click node_tests_xml "https://github.com/locationtech/jts/tree/master/modules/tests/src/test/resources/testxml"
click node_example_mod "https://github.com/locationtech/jts/tree/master/modules/example/src/main/java/org/locationtech/jtsexample"
click node_lab_mod "https://github.com/locationtech/jts/tree/master/modules/lab/src/main/java/org/locationtech/jtslab"
click node_build_tools "https://github.com/locationtech/jts/tree/master/build-tools/src/main/resources/jts"
click node_github_ci "https://github.com/locationtech/jts/blob/master/.github/workflows/build-and-test.yml"

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_pom_root,node_pom_modules,node_build_tools,node_github_ci toneBlue
class node_core_geom,node_core_ops,node_core_alg,node_core_noding,node_core_index,node_core_precision,node_core_io,node_core_prep toneAmber
class node_io_common,node_io_ora,node_io_sde toneMint
class node_app_builder,node_app_cmd,node_app_funcs,node_app_render,node_app_model toneRose
class node_tests_runner,node_tests_geomop,node_tests_xml toneIndigo
class node_example_mod,node_lab_mod toneTeal
```

## Components

### Repo

Multi-module Maven geometry toolkit centered on JTS core

- [Root POM](https://github.com/locationtech/jts/blob/master/pom.xml): maven root · Aggregates the multi-module build · `pom.xml`
- [Modules POM](https://github.com/locationtech/jts/blob/master/modules/pom.xml): maven aggregator · Common module aggregation for the subprojects · `modules/pom.xml`

### Core engine

Geometry model, algorithms, indexes, and operations

- [Geometry model](https://github.com/locationtech/jts/tree/master/modules/core/src/main/java/org/locationtech/jts/geom): core model · Coordinate, Geometry, factory, precision, and sequence types · `modules/core/src/main/java/org/locationtech/jts/geom`
- [Operations](https://github.com/locationtech/jts/tree/master/modules/core/src/main/java/org/locationtech/jts/operation): geometry ops · Buffer, overlay, union, relate, validation, simplify, linearref, coverage · `modules/core/src/main/java/org/locationtech/jts/operation`
- [Algorithms](https://github.com/locationtech/jts/tree/master/modules/core/src/main/java/org/locationtech/jts/algorithm): spatial algorithms · Numeric and topological routines used by higher-level operations · `modules/core/src/main/java/org/locationtech/jts/algorithm`
- [Noding & graphs](https://github.com/locationtech/jts/tree/master/modules/core/src/main/java/org/locationtech/jts/noding): topology graph · Segment noding and graph structures for overlay and relate · `modules/core/src/main/java/org/locationtech/jts/noding`
- [Spatial indexes](https://github.com/locationtech/jts/tree/master/modules/core/src/main/java/org/locationtech/jts/index): indexing · Quadtree, STRtree, kdtree, interval trees, and sweep-line indexes · `modules/core/src/main/java/org/locationtech/jts/index`
- [Precision tools](https://github.com/locationtech/jts/tree/master/modules/core/src/main/java/org/locationtech/jts/precision): robustness · Common bits, precision reduction, and enhanced precision support · `modules/core/src/main/java/org/locationtech/jts/precision`
- [Core IO](https://github.com/locationtech/jts/tree/master/modules/core/src/main/java/org/locationtech/jts/io): wkt/wkb/gml/kml · Canonical text and binary geometry readers and writers · `modules/core/src/main/java/org/locationtech/jts/io`
- [Prepared geom](https://github.com/locationtech/jts/tree/master/modules/core/src/main/java/org/locationtech/jts/geom/prep): predicate accel · Prepared geometry support for faster repeated spatial predicates · `modules/core/src/main/java/org/locationtech/jts/geom/prep`

### IO adapters

Format readers and writers around core Geometry

- [Common IO](https://github.com/locationtech/jts/tree/master/modules/io/common/src/main/java/org/locationtech/jts/io): geojson/twkb · GeoJSON and TWKB adapters built on core geometry · `modules/io/common/src/main/java/org/locationtech/jts/io`
- [Oracle IO](https://github.com/locationtech/jts/tree/master/modules/io/ora/src/main/java/org/locationtech/jts/io/oracle): oracle spatial · Oracle geometry reader and writer integration · `modules/io/ora/src/main/java/org/locationtech/jts/io/oracle`
- [SDE IO](https://github.com/locationtech/jts/tree/master/modules/io/sde/src/main/java/org/locationtech/jts/io/sde): sde reader · SDE input adapter into core Geometry · `modules/io/sde/src/main/java/org/locationtech/jts/io/sde`

### Desktop app

TestBuilder GUI, command tools, and rendering

- [TestBuilder](https://github.com/locationtech/jts/tree/master/modules/app/src/main/java/org/locationtech/jtstest/testbuilder): desktop GUI · Swing-based geometry inspection, editing, and visualization shell · `modules/app/src/main/java/org/locationtech/jtstest/testbuilder`
- [CLI tools](https://github.com/locationtech/jts/tree/master/modules/app/src/main/java/org/locationtech/jtstest/cmd): command layer · JTSOp and related command-line entry points · `modules/app/src/main/java/org/locationtech/jtstest/cmd`
- [Function registry](https://github.com/locationtech/jts/tree/master/modules/app/src/main/java/org/locationtech/jtstest/geomfunction): function bridge · Reflective geometry function wrappers used by tools and GUI · `modules/app/src/main/java/org/locationtech/jtstest/geomfunction`
- [Rendering UI](https://github.com/locationtech/jts/tree/master/modules/app/src/main/java/org/locationtech/jtstest/testbuilder/ui): swing render · Layer rendering, styles, tools, and view management · `modules/app/src/main/java/org/locationtech/jtstest/testbuilder/ui`
- [App model](https://github.com/locationtech/jts/tree/master/modules/app/src/main/java/org/locationtech/jtstest/testbuilder/model): edit model · Layers, test cases, result containers, and undo state · `modules/app/src/main/java/org/locationtech/jtstest/testbuilder/model`

### Test runner

XML-driven geometry test execution and matching

- [TestRunner](https://github.com/locationtech/jts/tree/master/modules/tests/src/main/java/org/locationtech/jtstest/testrunner): xml harness · XML-driven geometry test execution and reporting · `modules/tests/src/main/java/org/locationtech/jtstest/testrunner`
- [Geom ops](https://github.com/locationtech/jts/tree/master/modules/tests/src/main/java/org/locationtech/jtstest/geomop): operation adapters · Operation wrappers, matchers, and function loading for tests · `modules/tests/src/main/java/org/locationtech/jtstest/geomop`
- [XML suites](https://github.com/locationtech/jts/tree/master/modules/tests/src/test/resources/testxml): test corpus · Large geometry test data sets for correctness and robustness · `modules/tests/src/test/resources/testxml`

### Examples & lab

Samples and experimental geometry work

- [Examples](https://github.com/locationtech/jts/tree/master/modules/example/src/main/java/org/locationtech/jtsexample): sample code · Documentation-oriented usage examples across core APIs · `modules/example/src/main/java/org/locationtech/jtsexample`
- [Lab code](https://github.com/locationtech/jts/tree/master/modules/lab/src/main/java/org/locationtech/jtslab): experimental · Incubating algorithms and exploratory operations · `modules/lab/src/main/java/org/locationtech/jtslab`

### Build & CI

Maven, quality gates, and release automation

- [Build tools](https://github.com/locationtech/jts/tree/master/build-tools/src/main/resources/jts): quality config · Checkstyle, PMD, suppression, and shared build resources · `build-tools/src/main/resources/jts`
- [GitHub Actions](https://github.com/locationtech/jts/blob/master/.github/workflows/build-and-test.yml): ci pipeline · Automated build and test workflow · `.github/workflows/build-and-test.yml`

## Connections

- Root POM → Modules POM: aggregates · Root build includes the module aggregator
- Modules POM → Geometry model: builds · Core module is the main dependency base
- Modules POM → Operations: builds · Operation layer is packaged from core
- Modules POM → Core IO: builds · Core IO is part of the main library
- Modules POM → Common IO: builds · Additional interchange adapters
- Modules POM → TestBuilder: builds · Desktop TestBuilder application
- Modules POM → TestRunner: builds · Standalone test execution framework
- Modules POM → Examples: builds · Example module compiles against core APIs
- Modules POM → Lab code: builds · Experimental module remains separate
- Geometry model → Algorithms: uses · Geometry model underpins algorithms
- Geometry model → Noding & graphs: feeds · Coordinates and segments are noded for topology
- Geometry model → Spatial indexes: queries · Geometry operations rely on spatial indexing
- Geometry model → Precision tools: stabilizes · Precision tools protect geometry computations
- Geometry model → Prepared geom: accelerates · Prepared geometries optimize repeated predicates
- Operations → Noding & graphs: depends on · Overlay, relate, and polygonization build topological graphs
- Operations → Spatial indexes: depends on · Performance-critical operations use spatial indexes
- Operations → Precision tools: depends on · Robust variants reduce floating-point error
- Operations → Geometry model: returns · Operations produce new Geometry objects
- Algorithms → Spatial indexes: accelerates · Some algorithms use indexed search
- Core IO → Geometry model: serializes · Reads and writes normalized geometry objects
- Common IO → Geometry model: extends · GeoJSON and TWKB adapters target core geometry
- Oracle IO → Geometry model: bridges · Oracle geometry conversion boundary
- SDE IO → Geometry model: bridges · SDE input is normalized into core geometry
- TestBuilder → App model: uses · GUI state is held in the application model
- TestBuilder → Rendering UI: renders via · Swing views and tools paint geometry state
- TestBuilder → Function registry: invokes · Registered geometry functions drive interactive actions
- CLI tools → Core IO: parses · CLI tools ingest and emit geometry text/binary
- CLI tools → Operations: executes · Command-line operations call into geometry algorithms
- Function registry → Operations: wraps · Function registry exposes operation APIs
- Rendering UI → Geometry model: draws · Rendering works from core geometry objects
- TestRunner → Geom ops: loads · Runner uses operation adapters and matchers
- Geom ops → Operations: executes · Test operations call the geometry engine
- TestRunner → XML suites: drives · XML suites provide inputs and expected outputs
- Examples → Geometry model: demonstrates · Examples show core model usage
- Examples → Operations: demonstrates · Examples exercise common operations
- Lab code → Operations: experiments with · Lab code explores alternative algorithms
- Build tools → Root POM: supports · Shared build rules apply across modules
- GitHub Actions → Build tools: enforces · CI runs quality checks and tests
- GitHub Actions → TestRunner: runs · Automation executes the test harness
