Standards Documentation
This index gives humans and AI agents one navigation map.
Intent
This index gives humans and AI agents one navigation map. Read foundation documents to understand the method, then load only the conventions related to the current task.
Foundations
| Document | Read when |
|---|---|
| Supported scope | Evaluating whether an application fits version 1. |
| Engineering principles | Making a design choice not covered by a narrower convention. |
| Agentic Domain-Driven Delivery | Planning, documenting, or implementing product behavior. |
| Agent operating protocol | Configuring or reviewing agent behavior. |
| Release standard | Deciding whether a use case or application v1 is complete. |
Platform profile
The dotnet-nextjs profile selects the baseline stack and lists every convention included in version 1.
Repository conventions
| Document | Covers |
|---|---|
| Repository structure | Monorepo tree, app placement, solution placement, shared packages, and project documentation. |
| Naming and code style | Files, C# types, TypeScript files, suffixes, async methods, exceptions, and generic-name restrictions. |
| Dependencies | Project references, package ownership, version pins, and package approval. |
| Configuration | SDK pins, central package files, build properties, environment access, and secrets. |
| Repository writing | ASCII-safe prose, normative language, document structure, and repeatable writing checks. |
Backend conventions
| Document | Covers |
|---|---|
| Architecture | Four-project modular monolith, dependency direction, capability slices, and Worker activation. |
| Domain | Aggregate roots, mandatory state records, value objects, IDs, entities, services, events, repositories, errors, and persistence-neutral object design. |
| Application | Commands, queries, handlers, validators, results, reactions, ports, and folders. |
| Marten persistence | Sessions, repositories, queries, commit pipeline, event collection, JSON contracts, document evolution, aliases, indexes, and schema changes. |
| HTTP API | Minimal API endpoints, routes, transport models, status codes, Problem Details, authorization, and OpenAPI. |
Frontend conventions
| Document | Covers |
|---|---|
| Frontend structure | App tree, feature boundaries, shared code, generated types, and multiple frontends. |
| Rendering and routes | App Router, Server Components, client boundaries, route files, loading, errors, and metadata. |
| Components and UI | Component categories, props, shadcn/ui ownership, accessibility, variants, and content safety. |
| Data, forms, and state | Typed API access, reads, mutations, forms, URL state, local state, and optional client caches. |
| Frontend testing | Vitest, Playwright, test placement, acceptance trace, and browser-risk boundaries. |
Quality and operations
| Document | Covers |
|---|---|
| Backend testing | Test projects, naming, fixtures, PostgreSQL integration, architecture tests, and acceptance trace. |
| Security | Authentication, authorization, trust boundaries, secrets, SQL, errors, browser security, and dependencies. |
| Operations | Aspire, diagnostics, health, schema rollout, backup, deployment, rollback, and Worker operation. |
| Continuous integration | Pull request gates, generated contracts, supply-chain scans, schema artifacts, promotion, and branch protection. |
Extensions
Extensions are inactive until a current requirement meets their activation criteria and the consumer lists the extension in standards.project.json.
Read the extension index to select conditional standards for API compatibility, authentication, BDD, caching, concurrency, data lifecycle, deployment, external services, localization, scheduled jobs, tenancy, durable delivery, EF Core, realtime behavior, or reporting.
Reference and templates
- Glossary defines repository terms.
- Decision records explain baseline choices.
- Adopt standards v1 gives a greenfield consumer sequence.
- V1 release scope states the complete baseline, conditional catalog, release contents, and exclusions.
- Model a Domain capability turns human discovery into aggregate, state, invariant, event, and use-case documentation.
- Document templates provide consumer starting points.
- Runbook template gives the required operational record shape.
- V2 roadmap records evidence-gated candidates after v1 adoption.
Schemas are not part of the human reading path. They validate only standards.manifest.json and consumer standards.project.json files.