About

NEvo (short for .NET Evolution) is a lightweight framework built around a simple philosophy: flexibility, modularity, and extensibility. It was born out of the need for a system that evolves with your application — not the other way around.

Rather than enforcing a fixed architecture or full-stack solution, NEvo provides the building blocks you need, when you need them. Start with minimal infrastructure for a simple CRUD service. Add CQRS when read/write scaling becomes essential. Introduce messaging, observability, or event-driven design as your system grows. All without rewriting your core.

NEvo encourages you to compose architecture patterns that fit your current context — whether you're building a modular monolith, a set of microservices, or transitioning between the two. Every piece is optional, every behavior overrideable, and every integration open for extension.

This is .NET Evolution — build only what matters, and scale when you're ready.

---

Packages

Package	Responsibility	Tags	Status
NEvo.Core	Core primitives and abstractions shared across the framework		Pre-Alpha
NEvo.Web	HTTP client wrapper with pluggable authentication strategies (OAuth, none) and a REST client base (NEvo.Web.Client)		Pre-Alpha
NEvo.Web.Authorization	Authorization middleware and policies for web layer		Pre-Alpha
NEvo.Authorization	Core abstractions and infrastructure for authorization logic		Pre-Alpha
NEvo.Messaging	Messaging infrastructure: event dispatching, base contracts		Pre-Alpha
NEvo.Messaging.Web	Integration of messaging with the HTTP/web pipeline		Pre-Alpha
NEvo.Messaging.Cqrs	CQRS layer built on top of messaging (commands/queries + handlers)		Pre-Alpha
NEvo.Messaging.Authorization	Authorization hooks for messaging layer		In progress
NEvo.Messaging.EntityFramework	EF-based implementation for message persistence (e.g. Outbox)		In progress
NEvo.Ddd.EventSourcing	Core components for event-sourced aggregates and sequential event processing		In progress
NEvo.EntityFramework	Shared EF infrastructure and base persistence types		Pre-Alpha
NEvo.Orchestrating	Process orchestration, sagas, and workflow coordination		In progress
NEvo.Orchestrating.EntityFramework	EF-based persistence for orchestrations		In progress

---

Working with AI

This repository uses a human-led, spec-anchored workflow for AI-assisted development — the owner makes architectural and scope decisions, agents propose options and implement approved work inside a declared context.

• Start here: AGENTS.md — portable entry point for any AI agent (change classes, decision policy, context loading rules).
• Full workflow: docs/ai/specification-workflow.md — vendor-neutral description of discovery, specification, task decomposition, and review.
• Tooling: node tools/specs.mjs <next|context|start|...> and node tools/docs.mjs <validate|find|...> drive specification and documentation lifecycle deterministically — see the workflow doc for the full command list.
• Dashboard: npm run dashboard:dev opens the local, live-updating view of current and archived specifications. See docs/development/local-setup.md for installation and production-build commands.
• Claude Code: exposes this workflow through namespaced /nevo-ai:* commands (spec-create, spec-refine, spec-review, spec-approve, task-next, task-start, task-review) — see CLAUDE.md.
• Cursor / Copilot: follow AGENTS.md and docs/ai/specification-workflow.md directly via .cursor/rules/ and .github/copilot-instructions.md.

Specifications live in specs/active/ (in progress) and specs/archive/ (completed); durable architecture and process decisions live in docs/development/ and docs/decisions/.