Skip to content

Commit 0663d44

Browse files
AurelienT-AvaCopilot
AurelienT-Ava
and
Copilot
committed
docs: add project overview and onboarding guide
Adds a concise developer onboarding document covering: - Business purpose and main features - Architecture overview with service diagram - Key technologies and frameworks - Repository structure - Important entry points and API endpoints - CI/CD and deployment guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 93509ed commit 0663d44

1 file changed

Lines changed: 189 additions & 0 deletions

File tree

‎docs/project-overview.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# eShop – Project Overview & Onboarding Guide
2+
3+
## Business Purpose
4+
5+
**eShop** is a reference .NET application implementing a fully functional e-commerce website ("AdventureWorks"). It demonstrates modern **microservices architecture** patterns using **.NET Aspire** and serves as a best-practice blueprint for building scalable, cloud-ready applications.
6+
7+
---
8+
9+
## Main Features
10+
11+
| Feature | Description |
12+
|---|---|
13+
| Product Catalog | Browse, search, and filter products with AI-powered recommendations |
14+
| Shopping Basket | Cart management backed by Redis |
15+
| Order Processing | Full order lifecycle with grace period and state machine |
16+
| Payment Processing | Event-driven payment handling |
17+
| Authentication | OpenID Connect / JWT via Duende IdentityServer |
18+
| Webhooks | External system integration via webhook subscriptions |
19+
| Web UI | Blazor Interactive Server web application |
20+
| Mobile App | Cross-platform .NET MAUI application |
21+
| AI Integration | Product recommendations via OpenAI / Azure OpenAI / Ollama |
22+
23+
---
24+
25+
## Architecture Overview
26+
27+
This is a **true microservices architecture** orchestrated by **.NET Aspire**.
28+
29+
```
30+
┌─────────────────────────────────────────────────────────────┐
31+
│ eShop.AppHost │
32+
│ (.NET Aspire Orchestration Host) │
33+
└──────────────────────────┬──────────────────────────────────┘
34+
│ Manages
35+
┌──────────────────┼──────────────────┐
36+
▼ ▼ ▼
37+
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
38+
│ Identity.API │ │ Catalog.API │ │ Basket.API │
39+
│ (AuthN/Z) │ │ (Products) │ │ (Cart + Redis) │
40+
└──────────────┘ └──────────────┘ └──────────────────┘
41+
┌──────────────────┬──────────────────┐
42+
▼ ▼ ▼
43+
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
44+
│ Ordering.API │ │ Webhooks.API │ │ OrderProcessor │
45+
│ (Orders) │ │ (Webhooks) │ │ PaymentProcessor │
46+
└──────────────┘ └──────────────┘ └──────────────────┘
47+
┌──────────────────┬──────────────────┐
48+
▼ ▼ ▼
49+
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
50+
│ WebApp │ │ HybridApp │ │ WebhookClient │
51+
│ (Blazor) │ │ (MAUI) │ │ (Test Client) │
52+
└──────────────┘ └──────────────┘ └──────────────────┘
53+
54+
Infrastructure: PostgreSQL + pgvector | Redis | RabbitMQ
55+
```
56+
57+
### Key Architecture Patterns
58+
59+
- **CQRS** – Commands/Queries separated via MediatR (see `Ordering.API/Application/`)
60+
- **Domain-Driven Design (DDD)** – Aggregates, Value Objects, Domain Events in `Ordering.Domain`
61+
- **Event-Driven** – Integration events published over RabbitMQ between services
62+
- **Transactional Outbox** – `IntegrationEventLogEF` ensures reliable event delivery
63+
- **Repository Pattern** – Abstracted data access in `Ordering.Infrastructure`
64+
- **gRPC** – High-performance communication for Basket service
65+
- **Idempotency** – Duplicate request detection via `IdentifiedCommand<T>`
66+
67+
---
68+
69+
## Key Technologies & Frameworks
70+
71+
| Category | Technology | Version |
72+
|---|---|---|
73+
| Runtime | .NET SDK | 10.0 |
74+
| Orchestration | .NET Aspire | 13.1.0 |
75+
| Web Framework | ASP.NET Core / Blazor | 10.0 |
76+
| Mobile | .NET MAUI | Latest |
77+
| CQRS / Mediator | MediatR | 13.0.0 |
78+
| ORM | Entity Framework Core | 10.0.1 |
79+
| Database | PostgreSQL + pgvector | – |
80+
| Cache | Redis | – |
81+
| Message Bus | RabbitMQ | – |
82+
| Identity | Duende IdentityServer | 7.3.2 |
83+
| gRPC | gRPC.AspNetCore | 2.71.0 |
84+
| Validation | FluentValidation | 12.0.0 |
85+
| Observability | OpenTelemetry | 1.14.0 |
86+
| API Versioning | Asp.Versioning | 8.1.0 |
87+
| API Docs | Scalar / OpenAPI | 2.8.6 |
88+
| AI | Azure OpenAI / Ollama | Beta |
89+
| Testing | MSTest + Playwright | – |
90+
91+
---
92+
93+
## Repository Structure
94+
95+
```
96+
eShop/
97+
├── src/
98+
│ ├── eShop.AppHost/ # ▶ PRIMARY ENTRY POINT – Aspire orchestration
99+
│ ├── eShop.ServiceDefaults/ # Shared service config (health, auth, OpenAPI)
100+
│ ├── Identity.API/ # Authentication & authorization
101+
│ ├── Catalog.API/ # Product catalog + AI recommendations
102+
│ ├── Basket.API/ # Shopping cart (Redis + gRPC)
103+
│ ├── Ordering.API/ # Order management (CQRS, REST)
104+
│ ├── Ordering.Domain/ # DDD aggregates & domain events
105+
│ ├── Ordering.Infrastructure/ # EF Core persistence & repositories
106+
│ ├── Webhooks.API/ # External webhook management
107+
│ ├── OrderProcessor/ # Background: order grace period state machine
108+
│ ├── PaymentProcessor/ # Background: payment event handling
109+
│ ├── WebApp/ # Blazor Interactive Server frontend
110+
│ ├── WebAppComponents/ # Shared Razor component library
111+
│ ├── HybridApp/ # .NET MAUI mobile app
112+
│ ├── ClientApp/ # Mobile client app
113+
│ ├── WebhookClient/ # Webhook test client
114+
│ ├── EventBus/ # Event bus abstraction
115+
│ ├── EventBusRabbitMQ/ # RabbitMQ event bus implementation
116+
│ └── IntegrationEventLogEF/ # Outbox pattern implementation
117+
├── tests/
118+
│ ├── Basket.UnitTests/
119+
│ ├── Ordering.UnitTests/
120+
│ ├── Ordering.FunctionalTests/
121+
│ ├── Catalog.FunctionalTests/
122+
│ └── ClientApp.UnitTests/
123+
├── e2e/ # Playwright end-to-end tests
124+
├── docs/ # Documentation
125+
├── .github/workflows/ # CI/CD pipelines
126+
├── eShop.slnx # Full solution
127+
├── eShop.Web.slnf # Web projects solution filter
128+
├── Directory.Packages.props # Centralized NuGet package versions
129+
└── global.json # SDK version pin
130+
```
131+
132+
---
133+
134+
## Important Entry Points & Components
135+
136+
### Starting the Application
137+
138+
```powershell
139+
dotnet run --project src/eShop.AppHost/eShop.AppHost.csproj
140+
```
141+
142+
The **Aspire Dashboard** URL is printed to the console — use it to monitor all services, traces, logs, and metrics.
143+
144+
### Key Files
145+
146+
| File | Purpose |
147+
|---|---|
148+
| `src/eShop.AppHost/Program.cs` | Service composition – wires all microservices, databases, and message brokers |
149+
| `src/WebApp/Program.cs` | Blazor web app startup |
150+
| `src/Ordering.API/Application/` | CQRS commands, queries, handlers, and MediatR pipeline behaviors |
151+
| `src/Ordering.Domain/AggregatesModel/` | DDD aggregates: `OrderAggregate`, `BuyerAggregate` |
152+
| `src/EventBusRabbitMQ/RabbitMQEventBus.cs` | Event bus implementation |
153+
| `src/eShop.ServiceDefaults/Extensions.cs` | Common extensions applied to all services |
154+
| `Directory.Packages.props` | Central place to update NuGet dependency versions |
155+
156+
### Key API Endpoints
157+
158+
| Service | Endpoint | Description |
159+
|---|---|---|
160+
| Ordering.API | `POST /api/orders/` | Create a new order |
161+
| Ordering.API | `GET /api/orders/{id}` | Get order by ID |
162+
| Ordering.API | `PUT /api/orders/cancel` | Cancel an order |
163+
| Ordering.API | `PUT /api/orders/ship` | Ship an order |
164+
| Catalog.API | `GET /api/catalog/items` | List catalog items |
165+
| Basket.API | gRPC `BasketService` | Manage shopping basket |
166+
| Identity.API | `/.well-known/openid-configuration` | OIDC discovery endpoint |
167+
168+
---
169+
170+
## CI/CD
171+
172+
| Workflow | Trigger | What it does |
173+
|---|---|---|
174+
| `pr-validation.yml` | PR / push to `main` | Build + test all web projects |
175+
| `pr-validation-maui.yml` | PR / push to `main` | Build + test MAUI app |
176+
| `playwright.yml` | Scheduled / manual | End-to-end browser tests |
177+
| `markdownlint.yml` | PR | Lint documentation |
178+
179+
---
180+
181+
## Deployment
182+
183+
```bash
184+
# Azure (via Azure Developer CLI)
185+
azd init
186+
azd up
187+
```
188+
189+
Aspire auto-detects all services and provisions Azure Container Apps, PostgreSQL, Redis, and Service Bus.

0 commit comments

Comments
 (0)