Determinism over heuristics
Systems yield reproducible, verifiable outcomes. Ambiguous heuristics and uncalibrated thresholds are not accepted.
Standards · Architecture · Governance
How the NainDev ecosystem is built, written down.
One handbook for the decisions every NainDev project shares: how code is layered, how it is verified, how work is tracked and what a repository must document. It is plain Markdown in a public repository, so anyone can read the rules a project is held to.
- 9 architecture documents
- 10 governance documents
- Open to read
Five engineering tenets
Everything else in the handbook follows from these.
Spec-driven engineering
Code is the last artifact of a pipeline: numbered documentation phases, explicit acceptance criteria and recorded decisions come first.
Test-first verification
A feature or fix without an automated test does not exist. Tests bracket every structural refactor.
Clean layering
Domain logic stays decoupled from databases, frameworks and transport. Dependencies flow inward.
Zero-cost production footprint
Portfolio applications and demos run at no recurring infrastructure cost, using static builds, free tiers and public automation.
The paved road
The default stack, marked Adopt on the handbook's technology radar. A project starts here unless its own documentation says otherwise.
| Area | Adopt |
|---|---|
| Backend | ASP.NET Core on .NET 10 with Clean Architecture; Python 3.12+ with FastAPI |
| 3D and data | Trimesh, NumPy, SciPy, Shapely, Pydantic v2 |
| Persistence | PostgreSQL; EF Core 10 for writes, Dapper for reads |
| Frontend | Vanilla JS (ES modules), Astro, Vue 3 with strict TypeScript |
| Testing | xUnit v3, Vitest, Playwright, pytest with Hypothesis, Testcontainers |
| Hosting | GitHub Pages, Cloudflare DNS and SSL, GitHub Actions |
What is in the handbook
Each entry opens the full document on GitHub.
Architecture
| Document | What it covers |
|---|---|
| Enterprise context map | Bounded contexts, interactions and C4 levels 1 and 2 across NainDev. |
| Clean Architecture | Four layers (Domain, Application, Infrastructure, Presentation) for .NET and Python. |
| Dual persistence | Transactional writes through EF Core, fast reads through Dapper. |
| Deterministic 3D validation | GLB and glTF checks C1 to C10, a quantum threshold of 10-12 m² and fail-closed gating. |
| Fitness functions | CI tests that assert layer boundaries, with ArchUnitNET and AST linters. |
| C4 modelling | Context, container and component diagrams in Mermaid. |
| Legacy .NET modernisation | Strangler Fig proxying with YARP, WCF to gRPC and shadow running. |
| 3D conformance rubric | Audit criteria and pass or fail thresholds for geometry and PBR. |
| FinOps and capacity | Cost models for a zero-cost portfolio and for a 10k requests per minute production system. |
Governance
| Document | What it covers |
|---|---|
| Spec-driven lifecycle | The numbered docs/ folder convention, TDD gates and task tagging. |
| ADR template | A standard format for recording design trade-offs. |
| Technical due diligence | A framework for evaluating a codebase: modularity, FinOps and resilience. |
| Two-audience README | One README that serves both a buyer and a senior architect. |
| Dependabot governance | Grouped weekly updates across npm, pip, NuGet and Actions. |
| Local development | The same Taskfile commands in every repository: dev, test, build. |
| Zero-cost philosophy | How a multi-application portfolio runs at no recurring cost. |
| Visual identity | The technical blueprint look, dual-theme banners and showcase integration. |
| UI localisation | Spanish by default with an English toggle, and code and docs in English. |
| Licensing policy | All rights reserved for brand and portfolio, MIT or AGPL for code. |
Who does each task
Every task in a repository roadmap carries one of three ownership tags, so it is clear what can run without a person.
Runs end to end in CI or with an AI assistant, with no manual step.
Needs a human action to close: authorisation, an account or a key.
Reserved for the principal architect: business strategy, client agreements and final approvals.
Isolation rule: private and client code stays separate. No business rules, credentials or internal schemas move into public repositories, and public material is scanned for confidential names before it is published.