# ryuu3160/cpon architecture

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

- Interactive diagram: https://gitdiagram.com/ryuu3160/cpon
- Repository: https://github.com/ryuu3160/cpon

## Overview

1. **What this repository is**
   CPON is a **C++20 / MSVC-oriented library** for a custom object notation format, with both **text** (`.cpon`) and **binary** (`.cponb`) representations. The repo is organized as a library source tree plus a NuGet packaging layer.

2. **Core runtime library**
   The main implementation lives under `CPON/src/`. This is the architectural center of the project and contains the reusable C++ code that consumer applications compile or package against.

3. **Primary subsystems in the core**
   The source files split into three obvious responsibilities:
   - `cpon.hpp / cpon.cpp`: top-level API and format handling entry points
   - `cpon_object.hpp / cpon_object.cpp`: object/data model for CPON entities
   - `cpon_binary_helper.hpp / cpon_binary_helper.cpp`: binary format support and translation logic

4. **Data model boundary**
   `cpon_object.*` is the boundary between parsing/serialization logic and the in-memory representation. It likely models CPON objects, fields, arrays, nested objects, and metadata such as counts/types shown in the README examples.

5. **Text format flow**
   The text CPON flow is: source `.cpon` content → parser/reader in `cpon.*` → structured object model in `cpon_object.*` → optional modification → serialization back to text. The sample files `output.cpon` and `output_modified.cpon` suggest round-trip read/edit/write behavior.

6. **Binary format flow**
   Binary support is separated into `cpon_binary_helper.*`, which indicates a distinct encode/decode path for `.cponb`. The presence of `output.cponb` and the README “binary file support” note make binary a first-class serialization target rather than an afterthought.

7. **Consumer-facing API surface**
   `cpon.hpp` is the likely public header, while the other headers expose supporting types. A consumer would primarily interact through this API rather than directly with the internal file layout.

8. **Example / verification harness**
   `CPON/Test/main.cpp` is a small executable-style test harness used to exercise the library. It is not a separate subsystem; it validates parsing, conversion, and output generation against the sample artifacts.

9. **Build and IDE boundary**
   `CPON/CPON.vcxproj`, its filters file, the solution file `CPON.slnx`, and `CPON/cpp.hint` show this repo is designed for **Visual Studio / MSBuild** workflows. The project boundary is conventional C++ source-based compilation, not a framework-managed runtime.

10. **NuGet distribution path**
   The `CPON.NuGet/` subtree is a packaging mirror of the core library. It contains:
   - a `.nuspec`
   - native build targets under `build/native/CPON.targets`
   - `contentFiles/cpp/...` copies of the headers and sources  
   This means the library is distributed to downstream C++ projects through NuGet, with build integration handled by package targets.

11. **Important architectural duplication**
   The same core code appears in both `CPON/src/` and `CPON.NuGet/contentFiles/cpp/any/any/`. That duplication indicates two delivery modes:
   - direct repository build for development
   - packaged source delivery for consumption by other projects

12. **External constraints that shape the architecture**
   The README explicitly targets **Windows 10+, MSVC, and C++20**. Those constraints matter because the project is optimized for Visual Studio-native C++ builds and package integration, rather than cross-platform runtime portability.

13. **How to draw the architecture**
   A clean diagram would show:
   - **Consumer application / test program**
   - **CPON public API (`cpon.hpp`)**
   - **Object model (`cpon_object.*`)**
   - **Binary helper (`cpon_binary_helper.*`)**
   - **Text and binary CPON files** as input/output boundaries
   - **NuGet packaging layer** as a distribution path parallel to the source tree

Main entry points: [`CPON/src/cpon.hpp`](https://github.com/ryuu3160/cpon/blob/master/CPON/src/cpon.hpp) (CPON API), [`CPON/Test/main.cpp`](https://github.com/ryuu3160/cpon/blob/master/CPON/Test/main.cpp) (Test harness), [`CPON.NuGet/contentFiles/cpp/any/any/include/cpon.hpp`](https://github.com/ryuu3160/cpon/blob/master/CPON.NuGet/contentFiles/cpp/any/any/include/cpon.hpp) (Packaged headers), [`CPON.NuGet/contentFiles/cpp/any/any/src/cpon.cpp`](https://github.com/ryuu3160/cpon/blob/master/CPON.NuGet/contentFiles/cpp/any/any/src/cpon.cpp) (Packaged sources)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_api["CPON API<br/>public header<br/>[cpon.hpp]"]
  node_api_impl["API impl<br/>core source<br/>[cpon.cpp]"]
  node_model["Object model<br/>data model<br/>[cpon_object.hpp]"]
  node_model_impl["Model impl<br/>core source<br/>[cpon_object.cpp]"]
  node_binary["Binary helper<br/>binary codec"]
  node_binary_impl["Binary impl<br/>core source"]
end

subgraph group_package["NuGet packaging"]
  node_package_nuspec["NuGet spec<br/>package metadata<br/>[CPON.nuspec]"]
  node_package_targets["NuGet targets<br/>build targets<br/>[CPON.targets]"]
  node_package_headers["Packaged headers<br/>source mirror<br/>[cpon.hpp]"]
  node_package_sources["Packaged sources<br/>source mirror<br/>[cpon.cpp]"]
end

subgraph group_build["Build and samples"]
  node_test_harness["Test harness<br/>sample executable<br/>[main.cpp]"]
  node_project["VS project<br/>MSBuild project<br/>[CPON.vcxproj]"]
  node_solution["Solution<br/>VS workspace<br/>[CPON.slnx]"]
  node_hint["C++ hint<br/>IDE config<br/>[cpp.hint]"]
end

subgraph group_artifacts["Sample artifacts"]
  node_text_out["Text output<br/>sample .cpon<br/>[output.cpon]"]
  node_binary_out["Binary output<br/>sample .cponb<br/>[output.cponb]"]
  node_text_modified["Edited text<br/>sample .cpon"]
end

node_consumer["Consumer app<br/>downstream C++ app"]

node_consumer -->|"uses"| node_api
node_test_harness -->|"exercises"| node_api
node_api -->|"implements"| node_api_impl
node_api_impl -->|"builds on"| node_model
node_api_impl -->|"delegates"| node_binary
node_model -->|"implements"| node_model_impl
node_binary -->|"implements"| node_binary_impl
node_test_harness -->|"writes"| node_text_out
node_test_harness -->|"writes"| node_binary_out
node_test_harness -->|"writes"| node_text_modified
node_package_nuspec -->|"packages"| node_package_targets
node_package_targets -->|"exposes"| node_package_headers
node_package_targets -->|"exposes"| node_package_sources
node_package_headers -.->|"mirrors"| node_api
node_package_headers -.->|"mirrors"| node_model
node_package_headers -.->|"mirrors"| node_binary
node_package_sources -.->|"mirrors"| node_api_impl
node_package_sources -.->|"mirrors"| node_model_impl
node_package_sources -.->|"mirrors"| node_binary_impl
node_project -->|"builds"| node_api
node_project -->|"includes"| node_test_harness
node_solution -->|"opens"| node_project
node_hint -.->|"supports"| node_api

click node_test_harness "https://github.com/ryuu3160/cpon/blob/master/CPON/Test/main.cpp"
click node_project "https://github.com/ryuu3160/cpon/blob/master/CPON/CPON.vcxproj"
click node_solution "https://github.com/ryuu3160/cpon/blob/master/CPON.slnx"
click node_hint "https://github.com/ryuu3160/cpon/blob/master/CPON/cpp.hint"
click node_api "https://github.com/ryuu3160/cpon/blob/master/CPON/src/cpon.hpp"
click node_api_impl "https://github.com/ryuu3160/cpon/blob/master/CPON/src/cpon.cpp"
click node_model "https://github.com/ryuu3160/cpon/blob/master/CPON/src/cpon_object.hpp"
click node_model_impl "https://github.com/ryuu3160/cpon/blob/master/CPON/src/cpon_object.cpp"
click node_binary "https://github.com/ryuu3160/cpon/blob/master/CPON/src/cpon_binary_helper.hpp"
click node_binary_impl "https://github.com/ryuu3160/cpon/blob/master/CPON/src/cpon_binary_helper.cpp"
click node_package_nuspec "https://github.com/ryuu3160/cpon/blob/master/CPON.NuGet/CPON.nuspec"
click node_package_targets "https://github.com/ryuu3160/cpon/blob/master/CPON.NuGet/build/native/CPON.targets"
click node_package_headers "https://github.com/ryuu3160/cpon/blob/master/CPON.NuGet/contentFiles/cpp/any/any/include/cpon.hpp"
click node_package_sources "https://github.com/ryuu3160/cpon/blob/master/CPON.NuGet/contentFiles/cpp/any/any/src/cpon.cpp"
click node_text_out "https://github.com/ryuu3160/cpon/blob/master/CPON/output.cpon"
click node_binary_out "https://github.com/ryuu3160/cpon/blob/master/CPON/output.cponb"
click node_text_modified "https://github.com/ryuu3160/cpon/blob/master/CPON/output_modified.cpon"

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_api,node_api_impl,node_model,node_model_impl,node_binary,node_binary_impl toneBlue
class node_package_nuspec,node_package_targets,node_package_headers,node_package_sources toneAmber
class node_test_harness,node_project,node_solution,node_hint toneMint
class node_text_out,node_binary_out,node_text_modified toneRose
class node_consumer toneNeutral
```

## Components

### Core library

Primary C++20 CPON implementation and public API

- [CPON API](https://github.com/ryuu3160/cpon/blob/master/CPON/src/cpon.hpp): public header · Top-level library entry points and format handling · `CPON/src/cpon.hpp`
- [API impl](https://github.com/ryuu3160/cpon/blob/master/CPON/src/cpon.cpp): core source · Implementation behind the public CPON API · `CPON/src/cpon.cpp`
- [Object model](https://github.com/ryuu3160/cpon/blob/master/CPON/src/cpon_object.hpp): data model · In-memory CPON entities and structure boundary · `CPON/src/cpon_object.hpp`
- [Model impl](https://github.com/ryuu3160/cpon/blob/master/CPON/src/cpon_object.cpp): core source · Implementation of the CPON object model · `CPON/src/cpon_object.cpp`
- [Binary helper](https://github.com/ryuu3160/cpon/blob/master/CPON/src/cpon_binary_helper.hpp): binary codec · Encode/decode support for .cponb files · `CPON/src/cpon_binary_helper.hpp`
- [Binary impl](https://github.com/ryuu3160/cpon/blob/master/CPON/src/cpon_binary_helper.cpp): core source · Binary translation logic for CPON · `CPON/src/cpon_binary_helper.cpp`

### NuGet packaging

Distribution mirror and build targets for package consumers

- [NuGet spec](https://github.com/ryuu3160/cpon/blob/master/CPON.NuGet/CPON.nuspec): package metadata · Package manifest for CPON distribution · `CPON.NuGet/CPON.nuspec`
- [NuGet targets](https://github.com/ryuu3160/cpon/blob/master/CPON.NuGet/build/native/CPON.targets): build targets · Native build integration for packaged consumers · `CPON.NuGet/build/native/CPON.targets`
- [Packaged headers](https://github.com/ryuu3160/cpon/blob/master/CPON.NuGet/contentFiles/cpp/any/any/include/cpon.hpp): source mirror · Mirrored public headers delivered through NuGet · `CPON.NuGet/contentFiles/cpp/any/any/include/cpon.hpp`
- [Packaged sources](https://github.com/ryuu3160/cpon/blob/master/CPON.NuGet/contentFiles/cpp/any/any/src/cpon.cpp): source mirror · Mirrored implementation sources delivered through NuGet · `CPON.NuGet/contentFiles/cpp/any/any/src/cpon.cpp`

### Build and samples

Visual Studio project and test harness

- [Test harness](https://github.com/ryuu3160/cpon/blob/master/CPON/Test/main.cpp): sample executable · Small program that exercises parsing and serialization · `CPON/Test/main.cpp`
- [VS project](https://github.com/ryuu3160/cpon/blob/master/CPON/CPON.vcxproj): MSBuild project · Visual Studio build definition for the library · `CPON/CPON.vcxproj`
- [Solution](https://github.com/ryuu3160/cpon/blob/master/CPON.slnx): VS workspace · Solution entry point for the repository · `CPON.slnx`
- [C++ hint](https://github.com/ryuu3160/cpon/blob/master/CPON/cpp.hint): IDE config · Visual Studio IntelliSense hint file · `CPON/cpp.hint`

### Sample artifacts

Text and binary round-trip outputs

- [Text output](https://github.com/ryuu3160/cpon/blob/master/CPON/output.cpon): sample .cpon · Round-trip text CPON sample output · `CPON/output.cpon`
- [Binary output](https://github.com/ryuu3160/cpon/blob/master/CPON/output.cponb): sample .cponb · Round-trip binary CPON sample output · `CPON/output.cponb`
- [Edited text](https://github.com/ryuu3160/cpon/blob/master/CPON/output_modified.cpon): sample .cpon · Modified round-trip text sample · `CPON/output_modified.cpon`

### Other components

- **Consumer app**: downstream C++ app · External project using the CPON library

## Connections

- Consumer app → CPON API: uses · Downstream code consumes the public CPON API
- Test harness → CPON API: exercises · Test harness drives the public API
- CPON API → API impl: implements · Public declarations are backed by API implementation
- API impl → Object model: builds on · Parsing and serialization work through the object model
- API impl → Binary helper: delegates · Binary format handling is routed to the helper
- Object model → Model impl: implements · Object model declarations are backed by model implementation
- Binary helper → Binary impl: implements · Binary codec declarations are backed by helper implementation
- Test harness → Text output: writes · Sample program produces text output
- Test harness → Binary output: writes · Sample program produces binary output
- Test harness → Edited text: writes · Sample program emits edited text output
- NuGet spec → NuGet targets: packages · Package manifest ties in native build targets
- NuGet targets → Packaged headers: exposes · Targets make the headers available to consumers
- NuGet targets → Packaged sources: exposes · Targets also deliver source files to consumers
- Packaged headers → CPON API: mirrors · Packaged header mirrors the core public API
- Packaged headers → Object model: mirrors · Packaged headers include the object model boundary
- Packaged headers → Binary helper: mirrors · Packaged headers include binary helper declarations
- Packaged sources → API impl: mirrors · Packaged sources mirror the API implementation
- Packaged sources → Model impl: mirrors · Packaged sources mirror the model implementation
- Packaged sources → Binary impl: mirrors · Packaged sources mirror the binary helper implementation
- VS project → CPON API: builds · Visual Studio project compiles the core library sources
- VS project → Test harness: includes · Project workspace includes the test executable
- Solution → VS project: opens · Solution is the top-level IDE entry point
- C++ hint → CPON API: supports · IDE hint file supports the library headers