Coding

MonoStore - Copilot Instructions

MonoStore is a proof-of-concept e-commerce backend built as a monorepo demonstrating high-performance cart and product operations using the actor model. This project showcases modern .NET architecture patterns with event sourcing, CQRS, and microservices concepts within a monolithic deployment.

promptBeginner5 min to valuemarkdown

0 views

Jan 15, 2026

Sign in to like and favorite skills

View Original Source

Share:

Related Skills

PromptBeginner5 minmarkdown

Markdown Converter

Agent skill for markdown-converter

PromptBeginner5 minmarkdown

Nano Banana Pro

Agent skill for nano-banana-pro

PromptBeginner5 minmarkdown

1password

Agent skill for 1password

MonoStore - Copilot Instructions

Project Overview

MonoStore is a proof-of-concept e-commerce backend built as a monorepo demonstrating high-performance cart and product operations using the actor model. This project showcases modern .NET architecture patterns with event sourcing, CQRS, and microservices concepts within a monolithic deployment.

Core Architecture

Technology Stack

.NET 9: Primary framework
Microsoft Orleans: Actor model implementation for distributed systems
Marten: Event sourcing and document database using PostgreSQL
PostgreSQL: Primary database for event store and read models
Next.js 15: Frontend for backoffice administration
.NET Aspire: Local development orchestration and service discovery
Azure Container Apps: Production deployment target

Module Structure

The solution follows a modular monolith pattern with these core modules:

Cart Module (
```
src/cart/
```
): Shopping cart operations using Orleans grains
Product Module (
```
src/product/
```
): Product catalog management
Checkout Module (
```
src/checkout/
```
): Order processing and purchase workflows
Infrastructure (
```
src/infrastructure/
```
): Shared infrastructure concerns (Marten, event sourcing)
API (
```
src/MonoStore.Api/
```
): HTTP API layer
Service (
```
src/MonoStore.Service/
```
): Orleans service host running the grain silos
Backoffice (
```
src/backoffice/
```
): Next.js admin interface

Key Patterns and Practices

Orleans Actor Model

Use Orleans grains for stateful business logic (carts, products)
Implement grain interfaces in
```
MonoStore.Contracts
```
Follow single-responsibility principle for grain design
Leverage Orleans clustering for scalability

Event Sourcing with Marten

All state changes captured as events
Use
```
IEventStore
```
for event persistence
Implement projections for read models
Events should be in past tense (e.g.,
```
CartCreated
```
,
```
ProductAddedToCart
```
)
Store events in PostgreSQL via Marten

API Design

RESTful endpoints following REST conventions
Use minimal APIs pattern in .NET
Implement proper HTTP status codes
Follow async/await patterns consistently
Use dependency injection for service resolution

Module Organization

src/
├── {module}/
│   ├── MonoStore.{Module}.Tests/    # Tests covering the Domain module
│   ├── MonoStore.{Module}.Api/      # HTTP API endpoints
│   └── MonoStore.{Module}.Domain/   # Business logic and Orleans grain implementations

Development Guidelines

Code Style

Use C# 12+ features (file-scoped namespaces, primary constructors, etc.)
Follow Microsoft's C# coding conventions
Use
```
record
```
types for DTOs and value objects
Implement proper async/await patterns
Use nullable reference types consistently

Dependency Injection

Register services in module-specific extension methods
Use
```
IServiceCollection
```
extensions for clean registration
Follow constructor injection pattern
Use scoped lifetimes for business services

Error Handling

Use Result patterns or exceptions appropriately
Implement proper logging with structured logging
Handle Orleans grain lifecycle events
Provide meaningful error messages in APIs

Testing

Write unit tests for business logic
Use integration tests for API endpoints
Test Orleans grains in isolation
Performance test with K6 scripts in
```
performance/
```
directory

Local Development

Aspire Orchestration

Run

dotnet run --project src/aspire/MonoStore.AppHost

for local development

Aspire manages service dependencies and configuration
Access Aspire dashboard for service monitoring
Use Aspire for service discovery between modules

Database Setup

PostgreSQL runs via Aspire orchestration
Marten handles schema migrations automatically
Use connection strings from Aspire service discovery

Frontend Development

Next.js app in
```
src/backoffice/
```
for admin interface
Use TypeScript for type safety
Follow Next.js 15 app router patterns
Integrate with backend APIs via HTTP

Azure Deployment

Infrastructure

Deploy to Azure Container Apps for scalability
PostgreSQL via Azure Database for PostgreSQL
Use Azure Container Registry for image storage

Performance Considerations

Orleans Optimization

Use grain state for frequently accessed data
Implement grain timers for background processing
Configure Orleans clustering for production load
Monitor grain activation/deactivation patterns

Database Performance

Use Marten projections for read-optimized views
Implement proper indexing strategies
Consider read replicas for high-query scenarios
Monitor event store growth and archiving

Caching Strategy

Use Orleans grain state as distributed cache
Implement HTTP caching headers where appropriate
Consider Redis for cross-grain caching if needed

Security Guidelines

Authentication & Authorization

Implement proper authentication for APIs where needed
Use role-based authorization where needed
Secure Orleans cluster communication
Protect admin interface access

Data Protection

Use HTTPS for all communications
Implement proper connection string management
Follow GDPR considerations for user data
Secure Azure resource access with managed identities

Common Tasks

Adding a New Module

Create module directory structure under
```
src/
```
Define contracts in
```
MonoStore.Contracts
```
Implement business logic in
```
MonoStore.{Module}.Domain
```
Create Orleans grains in
```
MonoStore.{Module}.Domain
```
Add API endpoints in
```
MonoStore.{Module}.Api
```
Register services in Aspire host configuration

Adding New Events

Define event record in appropriate module contracts
Implement event handler if needed
Update Marten projections for read models
Add event to grain state persistence

Performance Testing

Use K6 scripts in
```
performance/
```
directory
Test cart operations:
```
k6 run performance/cart.js
```
Test product operations:
```
k6 run performance/product.js
```
Monitor Orleans dashboard during load tests

Troubleshooting

Common Issues

Orleans Clustering: Check service discovery configuration in Aspire
Database Connections: Verify PostgreSQL service is running
Missing Dependencies: Ensure all NuGet packages are restored
Build Errors: Check for missing project references

Debugging

Use Aspire dashboard for service health monitoring
Check Orleans dashboard for grain status
Use structured logging for tracing requests
Monitor PostgreSQL logs for database issues

External Resources