---
title: "Software Engineering"
summary: "How the capability is built: design decisions and their costs, the differentiable-programming patterns the solver relies on, code structure, the service architecture, testing, pipelines and provenance, performance, and process."
section: engineering
order: 0
level: 1
keywords: [engineering]
---
<!-- gyre docs: expanded Markdown of engineering/index.md (generated tables, verification numbers and chart data are written out). Base level of this page: L1 Essentials; passages at another level are bracketed by 'begin level N' / 'end level N' comments and start with [LN Name]. Built from revision ceb1f4b0be. -->

For people who change or operate the code. The pages record decisions together with the alternatives that were rejected, and the lessons that shaped the current design.

- [Design decisions](design-decisions.md) (L2 Practice): The handful of decisions that shape everything else — JAX as the kernel language, split-form DGSEM, geometry as differentiable data, split-argument residuals, one execution path, isolated worker processes — with the alternatives that were rejected.
- [Differentiable programming patterns](differentiable-programming.md) (L2 Practice): How the solver is structured so that automatic differentiation yields exact, efficient linearisations — the handful of JAX patterns the code relies on, and the pitfalls each one avoids.
- [Service architecture](service-architecture.md) (L2 Practice): The service is an asyncio API process that owns no numerical state, plus solver subprocesses of two kinds — one-shot job workers and long-lived sessions — over a file-based store that also holds the meshes clients upload. This page describes lifecycles, failure handling, caching and security.
- [Code structure](code-structure.md) (L2 Practice): A map of the package — which module owns which concept, how data is laid out in memory, and the conventions that the numerical kernels, the solver and the service share.
- [Testing strategy](testing-strategy.md) (L2 Practice): Tests are layered by what they can prove — algebraic invariants, exact derivative identities, end-to-end behaviour with real processes — and by cost. Verification studies sit above them as slower, reported evidence.
- [Pipelines and provenance](pipelines-and-provenance.md) (L2 Practice): Analyses, verification, documentation builds and deployment are stages of declarative pipelines. Stages are cached by content, run in isolation, and leave a provenance record — which is how every number in the documentation can be traced to a revision.
- [Performance](performance.md) (L2 Practice): Measured kernel throughput on CPU and GPU, the cost of derivatives relative to a residual evaluation, and where time goes in practice — compilation for small problems, Krylov iterations for large ones.
- [Development process](development-process.md) (L2 Practice): How the project is organised for contributors — human or agent: the roadmap as hand-off state, the effort ledger, commit and verification discipline, and the conventions that keep four interfaces consistent.
- [Effort ledger](effort-ledger.md) (L1 Essentials): How the development time was split between core capability, verification and logistics: the measured numbers, how they are measured, and how far they can be trusted. The split does not meet the 70 / 25 / 10 target cleanly, and a large part of the record is an estimate.