# bertt/cityjson architecture

> Architecture diagram of the GitHub repository bertt/cityjson, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bertt/cityjson
- Repository: https://github.com/bertt/cityjson

## Overview

##### Project Type and Purpose
- This is a .NET 6.0 class‐library project (CityJSON) with two companion CLI tools (cj2pg and cj2glb).
- Purpose: parse and manipulate CityJSON files, convert to NetTopologySuite features, and offer command‐line conversion to PostGIS (cj2pg) and GLB (cj2glb).

##### File‐Structure Analysis
- Top‐level:
- src – the core CityJSON library (domain types, converters, geometry models, extension methods, IO routines).
- tests – unit tests exercising parsing, geometry conversions, sequence reading.
- tools – two CLI apps (cityjson2pg, cj2glb) plus their tests and fixtures.
- Patterns & Layers:
- Domain layer (CityObject, Geometry, CityJsonDocument)
- Conversion layer (Convertors/*.cs)
- Extension methods (Extensions/*.cs)
- IO layer (CityJsonSeqReader, PolygonCreator)
- External dependency: NetTopologySuite for geometry features; Json.NET for deserialization.
- CI/CD: GitHub workflows under .github/workflows (build, test, release).

##### Key README Insights
- Shows core API: deserialize to CityJsonDocument, convert to NTS features, read sequence files.
- Describes two CLI tools: “cj2pg” (CityJSON → PostGIS) and “cj2glb” (CityJSON → GLB).
- Lists supported geometry types, appearance (textures), and limitations.

- Core Library (“CityJSON.Core”)
– Domain Model (CityJsonDocument, CityObject, Geometry classes)
– Converters (GeometryConverter, VertexConvertor)
– Extensions (ToFeature, ToFeatures methods)
– IO Services (CityJsonSeqReader, PolygonCreator)
- External Libraries
– Json.NET (Newtonsoft.Json)
– NetTopologySuite
- CLI Tools
– cj2pg (uses “CityJSON.Core” + PostGIS Connector)
– cj2glb (uses “CityJSON.Core” + glTF Builder)
- Data Stores / Outputs
– PostGIS Database
– GLB Files
- Tests
– Unit Tests for Core Library
– Integration Tests for Tools (fixtures folder)

- JSON File → (Json.NET) → Core Library → CityJsonDocument
- CityJsonDocument → (Converters + Extensions) → NetTopologySuite Features
- cj2pg:
– Reads CityJSON → Core Library → Generates SQL → Writes to PostGIS
- cj2glb:
– Reads CityJSON → Core Library → GltfCreator → Outputs .glb file
- CI/CD Workflow → (Build & Test) → Deploy NuGet / Release Binaries

c. Architectural Patterns & Principles
- Layered architecture:
– Presentation (CLI tools)
– Application (Core Library services)
– Domain (Geometry & CityJSON models)
– Infrastructure (IO, external DB/file outputs)
- Single Responsibility: converters, extensions, IO each in their own folder.
- Dependency Injection point: CLI applications wire up the core library.
- Extensibility: extension methods and converter classes allow adding support for new geometry types or outputs.

d. Key Technologies & Frameworks
- .NET 6.0 / C#
- Newtonsoft.Json for JSON parsing
- NetTopologySuite for geometry representations
- Npgsql (implied in cj2pg) for PostGIS integration
- Custom glTF builders in cj2glb

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Input
    JSON["CityJSON File"]:::external
    JSON -->|reads| JsonNet["Newtonsoft.Json"]:::external
    JsonNet -->|deserializes| Core["CityJSON.Core Library"]:::library

    %% Core Library Subsystems
    subgraph "Domain Model"
        direction TB
        Document["CityJsonDocument"]:::domain
        Object["CityObject"]:::domain
        GeoCore["Geometry"]:::domain
    end
    click Document "https://github.com/bertt/cityjson/blob/master/src/CityJsonDocument.cs"
    click Object "https://github.com/bertt/cityjson/blob/master/src/CityObject.cs"
    click GeoCore "https://github.com/bertt/cityjson/blob/master/src/Geometry/Geometry.cs"

    subgraph "Converters"
        direction TB
        GC["GeometryConverter"]:::converter
        VC["VertexConvertor"]:::converter
    end
    click GC "https://github.com/bertt/cityjson/blob/master/src/Convertors/GeometryConverter.cs"
    click VC "https://github.com/bertt/cityjson/blob/master/src/Convertors/VertexConvertor.cs"

    subgraph "Extensions"
        direction TB
        ExtDoc["CityJsonDocumentExtensions"]:::extension
        ExtObj["CityObjectExtensions"]:::extension
        ExtComposite["CompositeSolidGeometryExtensions"]:::extension
    end
    click ExtDoc "https://github.com/bertt/cityjson/blob/master/src/Extensions/CityJsonDocumentExtensions.cs"
    click ExtObj "https://github.com/bertt/cityjson/blob/master/src/Extensions/CityObjectExtensions.cs"
    click ExtComposite "https://github.com/bertt/cityjson/blob/master/src/Extensions/CompositeSolidGeometryExtensions.cs"

    subgraph "IO Services"
        direction TB
        SeqReader["CityJsonSeqReader"]:::io
        Polygon["PolygonCreator"]:::io
    end
    click SeqReader "https://github.com/bertt/cityjson/blob/master/src/CityJsonSeqReader.cs"
    click Polygon "https://github.com/bertt/cityjson/blob/master/src/IO/PolygonCreator.cs"

    subgraph "Appearance & Textures"
        direction TB
        Appearance["Appearance"]:::domain
        Texture["Texture"]:::domain
    end
    click Appearance "https://github.com/bertt/cityjson/blob/master/src/Appearance.cs"
    click Texture "https://github.com/bertt/cityjson/blob/master/src/Texture.cs"

    subgraph "Geometry Primitives"
        direction TB
        Transform["Transform"]:::domain
        Vertex["Vertex"]:::domain
    end
    click Transform "https://github.com/bertt/cityjson/blob/master/src/Transform.cs"
    click Vertex "https://github.com/bertt/cityjson/blob/master/src/Vertex.cs"

    %% Core Flow to Features
    Core --> DomainModel["Domain Model"]:::library
    Core --> Converters["Converters"]:::library
    Core --> Extensions["Extensions"]:::library
    Core --> IO["IO Services"]:::library
    Core --> AppearanceTextures["Appearance & Textures"]:::library
    Core --> Primitives["Geometry Primitives"]:::library

    Core -->|convert| NTS["NetTopologySuite"]:::external

    %% CLI Tools
    CJ2PG["cj2pg CLI"]:::cli
    CJ2GLB["cj2glb CLI"]:::cli

    click CJ2PG "https://github.com/bertt/cityjson/blob/master/tools/cityjson2pg/Program.cs"
    click CJ2PG "https://github.com/bertt/cityjson/blob/master/tools/cityjson2pg/Options.cs"
    click CJ2PG "https://github.com/bertt/cityjson/blob/master/tools/cityjson2pg/TileReader.cs"
    click CJ2GLB "https://github.com/bertt/cityjson/blob/master/tools/cj2glb/Program.cs"
    click CJ2GLB "https://github.com/bertt/cityjson/blob/master/tools/cj2glb/GltfCreator.cs"
    click CJ2GLB "https://github.com/bertt/cityjson/blob/master/tools/cj2glb/TexturedGltfCreator.cs"
    click CJ2GLB "https://github.com/bertt/cityjson/blob/master/tools/cj2glb/Flattener.cs"
    click CJ2GLB "https://github.com/bertt/cityjson/blob/master/tools/cj2glb/Tesselator.cs"
    click CJ2GLB "https://github.com/bertt/cityjson/blob/master/tools/cj2glb/Normal.cs"
    click CJ2GLB "https://github.com/bertt/cityjson/blob/master/tools/cj2glb/Triangle.cs"

    %% Tool Flows
    JSON -->|input| CJ2PG
    CJ2PG -->|uses| Core
    CJ2PG -->|writes SQL| PostGIS["PostGIS Database"]:::datastore

    JSON -->|input| CJ2GLB
    CJ2GLB -->|uses| Core
    CJ2GLB -->|outputs| GLB[".glb File"]:::datastore

    %% Tests and CI/CD
    subgraph "Tests"
        direction TB
        CoreTests["Core Unit Tests"]:::test
        IntTests["cj2glb Integration Tests"]:::test
    end
    click CoreTests "https://github.com/bertt/cityjson/blob/master/tests/CityJsonTests.cs"
    click CoreTests "https://github.com/bertt/cityjson/blob/master/tests/CityJsonSeqTests.cs"
    click CoreTests "https://github.com/bertt/cityjson/blob/master/tests/SimpleGeometriesTests.cs"
    click IntTests "https://github.com/bertt/cityjson/blob/master/tools/cj2glb.tests/UnitTest1.cs"
    click IntTests "https://github.com/bertt/cityjson/tree/master/tools/cj2glb.tests/testfixtures/"

    CI["CI/CD Workflow"]:::ci
    CI -->|runs| CoreTests
    CI -->|runs| IntTests
    CI -->|build & release| NuGet["NuGet/Release Binaries"]:::datastore
    click CI "https://github.com/bertt/cityjson/blob/master/.github/workflows/dotnet.yml"
    click CI "https://github.com/bertt/cityjson/blob/master/.github/workflows/release.yaml"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef library fill:#bbf,stroke:#333,stroke-width:1px
    classDef domain fill:#bfb,stroke:#333,stroke-width:1px
    classDef converter fill:#fbf,stroke:#333,stroke-width:1px
    classDef extension fill:#ffb,stroke:#333,stroke-width:1px
    classDef io fill:#bff,stroke:#333,stroke-width:1px
    classDef cli fill:#fbb,stroke:#333,stroke-width:1px
    classDef datastore fill:#ffd,stroke:#333,stroke-width:1px
    classDef test fill:#ddd,stroke:#333,stroke-width:1px
    classDef ci fill:#cdf,stroke:#333,stroke-width:1px
```
