monica-application-project-unit-development

name

monica-application-project-unit-development

description

Shared Monica-native DDD ProjectUnit development guidance for application projects. Use when creating, naming, placing, or refactoring ApplicationService, RequestDto, DomainService, Entity, Repository, DomainEvent, DomainEventHandler, LocalEventHandler, Configuration, RecurringJob, or TriggeredJob types, or when deciding which ProjectUnits a new feature requires in either microservice or modular monolith solutions.

Monica Application ProjectUnit Development

Overview

Use this skill for unit-level application development in Monica-based DDD projects. It defines the common ProjectUnit language shared by both monica-application-microservice and monica-application-modular-monolith.

Workflow

1. Start with the architecture skill to choose the target subdomain, project, and folder layout.
2. Read 00-project-unit-overview.md and 02-project-unit-composition-map.md to identify the units the feature needs.
3. Load only the template references relevant to the units you are creating or changing.
4. Keep the boundary thin: ApplicationService returns Res, while internal DomainService, repository, and entity logic stay on normal .NET return types and exceptions.
5. Prefer rich entities and value objects over procedural handlers that directly mutate persistence state.

Ground Rules

• Use Monica-native base classes and interfaces only. Do not introduce Our* wrappers or FIPS-specific conventions.
• Follow the naming, placement, and boundary rules in 01-project-unit-naming-and-boundaries.md. These rules are aligned with the current Monica.Framework/ProjectUnits discovery behavior.
• Keep persistence concerns in repositories and persistence classes, not in request handlers.
• Keep repository implementations in the owning subdomain or service infrastructure boundary. Do not move a repository or adapter to Platform just because it uses an external library; only project-common reusable infrastructure belongs in Platform.
• Keep contracts stable: requests, DTOs, and events are not persistence entities.
• If a handler returns Res<string>, use Res.Ok<string>(value) instead of Res.Ok(value) to avoid the non-generic string overload.
• For HTTP-exposed ApplicationService handlers, prefer the controller route pattern api/{version}/{DomainName(PascalCase)} and keep only the request-specific segment on the handler method, such as GET api/v1/Documentation/tree.
• If host composition must consume a Configuration ProjectUnit during registration, register Mo.AddConfiguration(...) first and then call Mo.RegisterInstantly(builder) before the dependent registration code runs.

Reference Navigation

• Unit catalog and responsibilities: 00-project-unit-overview.md
• Naming, placement, and boundary rules: 01-project-unit-naming-and-boundaries.md
• Unit selection by feature shape: 02-project-unit-composition-map.md
• ApplicationService templates: 10-application-service-template.md
• DomainService templates: 11-domain-service-template.md
• Entity, request, and event templates: 12-entity-request-event-template.md
• Repository and DbContext templates: 13-repository-and-persistence-template.md
• Event handler templates: 14-event-handler-template.md
• Job templates: 15-job-template.md
• Configuration templates: 16-configuration-template.md
• Completion checklist: 17-feature-checklist.md

Scope Notes

• This skill is architecture-agnostic. It explains unit design, not solution topology.
• Use monica-application-microservice to decide service splits, published-language layout, and migration project boundaries.
• Use monica-application-modular-monolith to decide module splits, host composition, and cross-module contracts.