# Architecture Decisions

Last updated: 2026-05-24

This file records accepted technical decisions that should guide future migration work.

## ADR-001 Single Private SDK Repository

MuPRO SDK should converge toward one private engineering repository. The former `openmupro` split added build and release friction without a realistic code-contribution benefit.

Impact:

- Common runtime and utility modules live in `library/`.
- Future app code may also be folded into the primary SDK repository during app refactors.
- Public/customer interaction should happen through issues, support, logs, test cases, and requirements rather than direct source contribution.

## ADR-002 App Submodules Are Transitional

The current app submodules remain in place until each app is refactored. Do not spend effort polishing their independent repository workflow unless it is needed for a near-term release.

Impact:

- `apps/muFerro` and `apps/muPREDICT` local cleanup edits are deferred.
- Future app refactors should decide whether to absorb app code into the SDK repository or keep only release packaging links.
- App migration should be planned separately from L0/L1 runtime migration.

## ADR-003 Desktop Is Out Of Scope

The old desktop code is not part of the SDK migration. Desktop or GUI products will be redesigned in other software.

Impact:

- Do not migrate `openmupro/desktop`.
- Do not block core SDK migration on GUI build health.
- Keep SDK examples command-line and library-oriented for now.

## ADR-004 Fortran First, C ABI Boundary

Fortran remains the primary numerical/scientific implementation language. A stable C ABI should be introduced as the long-term cross-language boundary.

Impact:

- Preserve existing Fortran module APIs during migration.
- Add C ABI wrappers gradually after runtime ownership and error/status foundations exist.
- C/C++ code may be used behind the ABI or in backend implementations when justified.

## ADR-005 Platform Tiers

Linux is the Tier 1 high-performance and official release platform. Windows is supported for oneAPI-based workflows when required. macOS is development-only and CPU-only.

Impact:

- Linux/Windows defaults are oneAPI + oneMKL + MKL FFT.
- macOS defaults are Homebrew `gfortran` + OpenBLAS + user-installed FFTW + OpenMPI.
- macOS should run small examples and smoke checks, not production HPC workloads.

## ADR-006 FFTW Is Never Bundled

FFTW is used only for macOS development builds and must not be bundled into SDK packages.

Impact:

- macOS developers install FFTW themselves.
- SDK package scripts should not copy FFTW artifacts.
- Linux/Windows official builds use MKL FFT.

## ADR-007 Reference Code Defines Scientific Baselines

The old MUPRO snapshot under `reference/` is the primary behavior reference for core scientific logic.

Impact:

- Solver refactors should map current code to `reference/Library` and `reference/Main_Programs/Ferroelectric` before changing algorithms.
- Unconfirmed scientific logic must be marked as `需人确认`.
- Benchmark expected values should trace to reference code or trusted legacy outputs.