ConformalLabpp/doc/architecture/project-structure.md

# Project Structure

```
ConformalLabpp/
├── CLAUDE.md                         # Claude Code context file
├── README.md                         # Entry point — what/why, quick start, doc index
├── LICENSE                           # MIT
│
├── code/                             # All C++ source
│   ├── CMakeLists.txt                # Root: three build modes (default / CGAL_TESTS / CGAL)
│   │
│   ├── include/                      # Header-only library — all algorithms here
│   │   ├── conformal_mesh.hpp        # ConformalMesh = CGAL::Surface_mesh<Point3>
│   │   ├── constants.hpp             # conformallab::PI, TWO_PI
│   │   ├── clausen.hpp               # Cl₂, Lobachevsky Л, ImLi₂
│   │   ├── hyper_ideal_geometry.hpp  # ζ₁₃/₁₄/₁₅, lᵢⱼ, αᵢⱼ, σᵢ, σᵢⱼ
│   │   ├── hyper_ideal_utility.hpp   # Tetrahedron volumes (Meyerhoff / Kolpakov–Mednykh)
│   │   ├── hyper_ideal_visualization_utility.hpp  # Poincaré disk projection, circumcircle helpers
│   │   ├── hyper_ideal_functional.hpp # HyperIdeal energy + gradient on ConformalMesh
│   │   ├── hyper_ideal_hessian.hpp   # HyperIdeal Hessian (symmetric FD, Phase 9b: analytic)
│   │   ├── spherical_geometry.hpp    # Spherical arc-length, half-angle formula
│   │   ├── spherical_functional.hpp  # Spherical energy + gradient + gauge-fix
│   │   ├── spherical_hessian.hpp     # Spherical Hessian (∂α/∂u via law of cosines)
│   │   ├── euclidean_geometry.hpp    # Euclidean corner angle (t-value / atan2)
│   │   ├── euclidean_functional.hpp  # Euclidean energy + gradient
│   │   ├── euclidean_hessian.hpp     # Cotangent Laplacian Hessian (Pinkall–Polthier)
│   │   ├── newton_solver.hpp         # newton_{euclidean,spherical,hyper_ideal} + solve_linear_system
│   │   ├── gauss_bonnet.hpp          # euler_characteristic, genus, check/enforce_gauss_bonnet
│   │   ├── cut_graph.hpp             # CutGraph + compute_cut_graph (tree-cotree)
│   │   ├── layout.hpp                # Priority-BFS layout, MobiusMap, halfedge_uv, HolonomyData
│   │   ├── mesh_builder.hpp          # make_triangle / make_tetrahedron / make_quad_strip / make_fan
│   │   ├── mesh_io.hpp               # load_mesh / save_mesh (OFF/OBJ/PLY via CGAL::IO)
│   │   ├── mesh_utils.hpp            # CGAL → Eigen conversion (cgal_to_eigen)
│   │   ├── serialization.hpp         # save/load_result_json + save/load_result_xml
│   │   ├── period_matrix.hpp         # PeriodData, compute_period_matrix, SL(2,ℤ) reduction
│   │   └── fundamental_domain.hpp    # FundamentalDomain, tiling_copy, tiling_neighbourhood
│   │
│   ├── src/
│   │   ├── apps/v0/conformallab_cli.cpp   # CLI app (Phase 5): load → solve → layout → export
│   │   └── viewer/simple_viewer.cpp       # libigl/GLFW viewer wrapper
│   │
│   ├── examples/                     # Standalone example programs (require WITH_CGAL=ON)
│   │   ├── example_euclidean.cpp     # Euclidean pipeline end-to-end
│   │   ├── example_hyper_ideal.cpp   # HyperIdeal pipeline end-to-end
│   │   ├── example_layout.cpp        # Full pipeline: solve → layout → OFF/JSON/XML + round-trip
│   │   └── example_viewer.cpp        # Interactive libigl viewer
│   │
│   ├── tests/
│   │   ├── CMakeLists.txt
│   │   ├── test_clausen.cpp
│   │   ├── test_hyper_ideal_utility.cpp
│   │   ├── test_matrix_utility.cpp
│   │   ├── test_surface_curve_utility.cpp
│   │   ├── test_discrete_elliptic_utility.cpp
│   │   ├── test_p2_utility.cpp
│   │   ├── test_hyper_ideal_visualization_utility.cpp
│   │   └── cgal/                     # CGAL test suite (WITH_CGAL_TESTS or WITH_CGAL)
│   │       ├── test_conformal_mesh.cpp
│   │       ├── test_hyper_ideal_functional.cpp
│   │       ├── test_spherical_functional.cpp
│   │       ├── test_euclidean_functional.cpp
│   │       ├── test_euclidean_hessian.cpp
│   │       ├── test_spherical_hessian.cpp
│   │       ├── test_newton_solver.cpp
│   │       ├── test_mesh_io.cpp
│   │       ├── test_pipeline.cpp
│   │       ├── test_layout.cpp
│   │       ├── test_phase6.cpp
│   │       ├── test_phase7.cpp
│   │       └── test_geometry_utils.cpp
│   │
│   └── deps/                         # All dependencies as bundled tarballs
│       ├── tarballs/
│       │   ├── eigen-3.4.0.tar.gz
│       │   ├── CGAL-6.1.1.tar.xz
│       │   ├── libigl-2.6.0.tar.gz
│       │   ├── libigl-glad.tar.gz
│       │   └── glfw-3.4.tar.gz
│       └── single_includes/          # CLI11.hpp, json.hpp (header-only)
│
├── doc/
│   ├── getting-started.md
│   ├── contributing.md
│   ├── api/
│   │   ├── pipeline.md               # Full pipeline API with code examples
│   │   ├── extending.md              # New functionals, geometry modes, Java porting
│   │   ├── contracts.md              # Processing unit preconditions/provides table
│   │   └── cgal-package.md           # Phase 8 CGAL package design (TODO)
│   ├── architecture/
│   │   ├── overall_pipeline.md       # Mermaid diagram + stage descriptions
│   │   ├── design-decisions.md       # Key architectural choices + rationale
│   │   └── project-structure.md      # This file
│   ├── math/
│   │   ├── geometry-modes.md         # Euclidean / Spherical / HyperIdeal comparison
│   │   └── references.md             # All papers by module
│   └── roadmap/
│       ├── phases.md                 # Phases 1–10 with porting/research boundary
│       └── java-parity.md            # Java vs C++ feature parity table
│
└── .gitea/
    ├── docker/Dockerfile.ci-cpp      # Ubuntu 22.04 ARM64 CI image
    └── workflows/cpp-tests.yml       # Two-job CI pipeline
```

## Build targets

| Target | Mode | Description |
|---|---|---|
| `conformallab_tests` | default | 36 non-CGAL pure-math tests |
| `conformallab_cgal_tests` | `WITH_CGAL_TESTS` or `WITH_CGAL` | 158 CGAL tests |
| `conformallab_core` | `WITH_CGAL` | CLI application |
| `example_euclidean` | `WITH_CGAL` | Euclidean example program |
| `example_hyper_ideal` | `WITH_CGAL` | HyperIdeal example program |
| `example_layout` | `WITH_CGAL` | Full pipeline example |
| `example_viewer` | `WITH_CGAL` | Interactive viewer |