docs: refine project overview

README.md

@@ -12,9 +12,7 @@
 
 **UnifiedVol** is a **C++20 quantitative finance library** for volatility surface modelling.
 
-The project focuses on front-office style numerical engineering: explicit model
-validation, reproducible public-data fixtures, regression coverage, performance
-guardrails, and documented references for the implemented methods.
+This project is designed around clean architecture, modular C++20 components, optimized numerical routines, and reproducible CI. It combines calibration pipelines, explicit model validation, regression and performance guardrails, public-data fixtures, and documented model implementations.
 
 ---
 
@@ -28,6 +26,85 @@ guardrails, and documented references for the implemented methods.
 
 ---
 
+## Architecture
+
+In the diagram below, arrows mean "depends on, includes, or calls".
+
+```mermaid
+flowchart LR
+    subgraph Clients["Clients"]
+        direction TB
+        Examples[examples]
+        Tests[tests]
+    end
+
+    subgraph Public["Public API"]
+        direction TB
+        API[uv/UnifiedVol.hpp]
+    end
+
+    subgraph Domain["Domain Layer"]
+        direction TB
+        Models[uv/Models<br/>SVI, Heston]
+        IO[uv/IO]
+        Core[uv/Core]
+    end
+
+    subgraph Numerics["Numerical Layer"]
+        direction TB
+        Math[uv/Math]
+        Opt[uv/Optimization]
+    end
+
+    subgraph Foundation["Foundation"]
+        direction TB
+        Base[uv/Base]
+    end
+
+    subgraph External["External"]
+        direction TB
+        ExtTest[GoogleTest]
+        ExtOpt[NLopt / Ceres]
+        ExtMath[Boost.Math<br/>lets_be_rational]
+    end
+
+    Examples --> API
+    Tests --> API
+    Tests --> ExtTest
+
+    API --> Base
+    API --> Core
+    API --> IO
+    API --> Models
+    API --> Math
+    API --> Opt
+
+    Core --> Base
+
+    IO --> Base
+    IO --> Core
+    IO --> Math
+
+    Models --> Base
+    Models --> Core
+    Models --> Math
+    Models --> Opt
+
+    Math --> Base
+    Math --> Core
+    Math --> ExtMath
+
+    Opt --> Base
+    Opt --> ExtOpt
+
+    Examples ~~~ Tests
+    Models ~~~ IO
+    Math ~~~ Opt
+    Base ~~~ ExtTest
+```
+
+---
+
 ## Example Usage
 
 Below is a **minimal excerpt** illustrating the structure of a typical calibration pipeline.  
@@ -67,7 +144,6 @@ io::report::volatility(hestonVolSurface);
 
 ## Documentation
 
-- Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
 - Contributing: [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)
 - Build instructions: [docs/BUILD.md](docs/BUILD.md)
 - File tree: [docs/TREE.md](docs/TREE.md)

docs/TREE.md

@@ -28,7 +28,6 @@ UnifiedVol/
 ├── data/
 │   ├── VolSurface_SPY_04072011.csv
 ├── docs/
-│   ├── ARCHITECTURE.md
 │   ├── BUILD.md
 │   ├── CONTRIBUTING.md
 │   ├── DATA.md
@@ -336,6 +335,10 @@ UnifiedVol/
 │   │   │   │   │   ├── Integrand.inl
 │   │   │   │   │   ├── Pricer.inl
 │   │   │   │   ├── Pricer.hpp
+│   │   ├── LocalVol/
+│   │   │   ├── Detail/
+│   │   │   │   ├── LocalVolSurface.inl
+│   │   │   ├── LocalVolSurface.hpp
 │   │   ├── SVI/
 │   │   │   ├── BuildSurface.hpp
 │   │   │   ├── Calibrate/

uv/Models/LocalVol/Detail/LocalVolSurface.inl

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include "Math/LinearAlgebra/VectorOps.hpp"
+
+namespace uv::models::local_vol
+{
+
+template <std::floating_point T>
+LocalVolSlice<T>::LocalVolSlice(std::span<const T> cPoints, std::span<const T> knots)
+    : interpolator_(exponentiateControlPoints(cPoints), knots)
+{
+}
+
+template <std::floating_point T>
+Vector<T> LocalVolSlice<T>::exponentiateControlPoints(std::span<const T> cPoints) const
+{
+    return math::linear_algebra::exponential(cPoints);
+}
+
+template <std::floating_point T>
+void LocalVolSlice<T>::localVarInplace(std::span<T> out, std::span<const T> x) const
+{
+    interpolator_.evalInplace(out, x);
+}
+
+template <std::floating_point T>
+Vector<T> LocalVolSlice<T>::localVar(std::span<const T> x) const
+{
+    return interpolator_.eval(x);
+}
+
+template <std::floating_point T>
+void LocalVolSlice<T>::localVolInplace(std::span<T> out, std::span<const T> x) const
+{
+    localVarInplace(out, x);
+    math::linear_algebra::squareRootInplace<T>(out, out);
+}
+
+template <std::floating_point T>
+Vector<T> LocalVolSlice<T>::localVol(std::span<const T> x) const
+{
+    Vector<T> out{localVar(x)};
+    math::linear_algebra::squareRootInplace<T>(out, out);
+
+    return out;
+}
+
+} // namespace uv::models::local_vol

uv/Models/LocalVol/LocalVolSurface.hpp

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include "Base/Types.hpp"
+#include "Math/Interpolation/BSpline/Interpolator.hpp"
+
+#include <concepts>
+#include <span>
+
+namespace uv::models::local_vol
+{
+
+template <std::floating_point T> class LocalVolSlice
+{
+  public:
+    LocalVolSlice() = delete;
+
+    LocalVolSlice(std::span<const T> cPoints, std::span<const T> knots);
+
+    void localVarInplace(std::span<T>, std::span<const T>) const;
+    Vector<T> localVar(std::span<const T>) const;
+
+    void localVolInplace(std::span<T>, std::span<const T>) const;
+    Vector<T> localVol(std::span<const T>) const;
+
+  private:
+    uv::math::interp::bspline::BSpline<T> interpolator_;
+
+    Vector<T> exponentiateControlPoints(std::span<const T>) const;
+};
+
+} // namespace uv::models::local_vol
+
+#include "Models/LocalVol/Detail/LocalVolSurface.inl"