What developers write:           What readers need:
──────────────────────────────   ──────────────────────────────
How it was implemented           Why this approach was chosen
Every edge case in prose         What the common path looks like
Complete API reference first     Quick start that works in 5 min
10-page design doc before code   1-page summary + detail on demand

# OrderService

Processes customer orders: validates inventory, charges payment, and publishes
OrderPlaced events for downstream services.

## Quick Start

    dotnet run --project OrderService.Api
    # API available at http://localhost:5000

## Prerequisites

- .NET 8 SDK
- Docker (for PostgreSQL and RabbitMQ)
- `dotnet user-secrets set "ConnectionStrings:Postgres" "Host=localhost;..."`

## Running Tests

    dotnet test

## Architecture

OrderService follows Vertical Slice Architecture. Each feature is in its own
folder under `Features/`. See [ARCHITECTURE.md](./ARCHITECTURE.md) for full detail.

## Configuration

| Key                        | Default | Description              |
|----------------------------|---------|--------------------------|
| ConnectionStrings:Postgres | —       | PostgreSQL connection     |
| RabbitMq:Host              | —       | RabbitMQ host             |
| Payment:ApiKey             | —       | Stripe API key            |

# ADR-003: Use PostgreSQL for Order Storage

**Date:** 2026-04-17
**Status:** Accepted

## Context

We need a persistent store for orders. Requirements:
- ACID transactions (partial writes must not succeed)
- JSON support for flexible order metadata
- Query support for reporting (aggregate orders by date, product, status)
- Team has strong SQL expertise

## Decision

Use PostgreSQL 16.

## Alternatives Considered

**MongoDB:** rejected — ACID transactions across documents added complexity
without clear benefit for our data model.

**SQL Server:** viable, but PostgreSQL is open-source, has lower hosting cost,
and the team has more operational experience with it.

## Consequences

- **Positive:** strong ACID guarantees, jsonb for metadata, excellent .NET
  support via Npgsql + EF Core
- **Negative:** operational team must maintain a Postgres instance (accepted
  cost — we use Azure Database for PostgreSQL)

# Design: Order Cancellation Service

**Author:** Asma Hafeez  
**Status:** In Review  
**Date:** 2026-04-17

## Problem

Customers can currently only cancel orders via customer support. We need a
self-service cancellation flow. Orders cannot be cancelled after shipment.

## Proposed Solution

Add a `CancelOrder` endpoint to OrderService. Cancellation is only allowed
when order status is Pending or Processing. A CancellationRequested domain
event triggers a refund via PaymentService.

## Non-Goals

- Partial order cancellation (future work)
- Cancellation reason analytics (not required for v1)

## Open Questions

1. Should we notify the warehouse synchronously or via event?
2. What is the SLA for refund processing? (need input from payments team)

## Risks

- If the refund call fails after order is marked cancelled, we need
  a compensation saga. Needs further design.

BAD: "Working on the authentication feature."

GOOD:
Status: On track for Thursday release.

Done this week:
• Login and logout endpoints complete, unit tested
• JWT validation middleware deployed to staging

Next:
• Role-based authorization (2 days)
• End-to-end test with the frontend (1 day)

Risks:
• Frontend integration depends on the auth team's updated token format.
  Meeting with them tomorrow. If format changes, +1 day.

1. Lead with the conclusion
   "We should use Redis. Here's why." — not three paragraphs then the answer.

2. One idea per paragraph
   If a paragraph has two ideas, split it.

3. Use plain words
   "use" not "utilize"
   "fix" not "remediate"
   "show" not "surface"

4. Prefer active voice
   "The service validates the token" — not "The token is validated by the service."

5. Delete the unnecessary words
   "In order to" → "To"
   "Due to the fact that" → "Because"
   "At this point in time" → "Now"

6. Structure for skimming
   Headers, bullets, and bold let readers find what they need.
   Not every reader will read every word — design for that.

Use written async communication for:
  • Design decisions that need input from multiple people
  • Status updates and progress reports
  • Technical context for new team members
  • Decisions that should be reviewable in 6 months

Use meetings for:
  • High-bandwidth disagreements that need real-time resolution
  • Relationship-building
  • Complex ambiguous problems that benefit from back-and-forth

The written output of a meeting is more valuable than the meeting itself.
Write decisions down immediately after. "Per our conversation" emails decay.