From 6426cd3aae40cae9da3296d448d3904f5a4e1498 Mon Sep 17 00:00:00 2001
From: amasen02 <amasen02@users.noreply.github.com>
Date: Sat, 12 Sep 2026 21:33:43 +0530
Subject: [PATCH] docs: add local development quickstart guide using Docker
 Compose (#7)

- Create docs/quickstart.md with Docker Compose stack setup & Aspire launch instructions
- Document default mapped container ports and credentials
- Link quickstart from README.md documentation index
- Add dynamic Star History chart and star prompt
- Closes #7
---
 README.md          | 10 ++++++
 docs/quickstart.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+)
 create mode 100644 docs/quickstart.md

diff --git a/README.md b/README.md
index ee08206..7c13848 100644
--- a/README.md
+++ b/README.md
@@ -344,6 +344,7 @@ warning instead of failing every build):
 Open the **[`index.html`](index.html)** landing page for the animated architecture guide. The
 deeper references are:
 
+- [`docs/quickstart.md`](docs/quickstart.md) &mdash; Step-by-step local setup with Docker Compose & Aspire.
 - [`ARCHITECTURE.md`](ARCHITECTURE.md) &mdash; C4 narrative + cross-cutting map.
 - [`docs/CONVENTIONS.md`](docs/CONVENTIONS.md) &mdash; naming, async, LINQ discipline.
 - [`docs/adr/`](docs/adr/) &mdash; architecture decision records.
@@ -390,6 +391,15 @@ This project is, and will remain, free and open source. As maintainer I commit t
 
 ---
 
+
+---
+
+## Stargazers over time
+
+[![Star History Chart](https://api.star-history.com/svg?repos=amasen02/freshcart-backend&type=Date)](https://star-history.com/#amasen02/freshcart-backend&Date)
+
+⭐ **Found this useful? Please star the repository to support its development!**
+
 ## License
 
 MIT &mdash; see [`LICENSE`](LICENSE). You are free to use, modify, and distribute this software,
diff --git a/docs/quickstart.md b/docs/quickstart.md
new file mode 100644
index 0000000..3b63c07
--- /dev/null
+++ b/docs/quickstart.md
@@ -0,0 +1,86 @@
+# Local Development Quickstart Guide
+
+This guide walks you through bootstrapping the **FreshCart** microservices backend on your local development machine using Docker Compose and the .NET CLI.
+
+---
+
+## 1. Prerequisites
+
+Ensure you have the following installed on your workstation:
+- **.NET SDK** (9.0 or 10.0-preview) &mdash; [Download .NET](https://dotnet.microsoft.com/download)
+- **Docker Desktop** (or Docker Engine with Compose v2) &mdash; [Get Docker](https://www.docker.com/products/docker-desktop)
+- **Git**
+
+Verify prerequisites in your terminal:
+```bash
+dotnet --version
+docker compose version
+```
+
+---
+
+## 2. Clone the Repository
+
+```bash
+git clone https://github.com/amasen02/freshcart-backend.git
+cd freshcart-backend
+```
+
+---
+
+## 3. Launch Backing Services (Infrastructure Stack)
+
+FreshCart relies on PostgreSQL, Redis, RabbitMQ, and OpenTelemetry collector for event-driven messaging, caching, and observability. Launch them via the provided Docker Compose stack:
+
+```bash
+docker compose -f deploy/docker/docker-compose.yaml up -d
+```
+
+### Checking Container Health
+Verify that all supporting databases and brokers are healthy:
+```bash
+docker compose -f deploy/docker/docker-compose.yaml ps
+```
+
+Default ports mapped locally:
+| Service | Technology | Port | Credentials |
+| :--- | :--- | :--- | :--- |
+| **Identity & Catalog DB** | PostgreSQL | `5432` | `postgres` / `postgres` |
+| **Distributed Cache** | Redis | `6379` | None (local dev) |
+| **Event Bus** | RabbitMQ | `5672` (AMQP), `15672` (UI) | `guest` / `guest` |
+| **Metrics** | Prometheus | `9090` | N/A |
+| **Dashboards** | Grafana | `3000` | `admin` / `admin` |
+
+---
+
+## 4. Run via .NET Aspire AppHost (Recommended)
+
+FreshCart is orchestrated using **.NET Aspire**. The `FreshCart.AppHost` automatically configures service discovery, connection strings, and resilience pipelines:
+
+```bash
+dotnet run --project src/FreshCart.AppHost/FreshCart.AppHost.csproj
+```
+
+Once started, the terminal will output the **Aspire Dashboard URL** (typically `https://localhost:17000`). Open it in your browser to inspect live metrics, structured logs, and distributed traces across all microservices.
+
+---
+
+## 5. Running Tests
+
+Run the full suite of unit and component integration tests:
+```bash
+# Run all unit tests
+dotnet test --filter "Category!=Integration"
+
+# Run tests with detailed summary
+dotnet test --logger "console;verbosity=normal"
+```
+
+---
+
+## 6. Stopping the Environment
+
+To tear down the Docker background containers:
+```bash
+docker compose -f deploy/docker/docker-compose.yaml down -v
+```