improve README readability

README.md

@@ -1,20 +1,61 @@
 # xmrcheckout.com
 
-Non-custodial Monero checkout software. Payments go directly from the
+Non-custodial Monero checkout software for merchants. Payments go directly from the customer to the merchant wallet.
-customer to the merchant. This project never requests spend keys and
-never moves funds.
 
-## Run the homepage
+This project is intentionally conservative by design:
+- It never requests or stores private spend keys.
+- It never signs transactions.
+- It never moves funds on behalf of users.
+- View-only access (wallet address + private view key) is the maximum trust boundary.
+
+## Contents
+
+- [What it does](#what-it-does)
+- [Trust model](#trust-model)
+- [Repository layout](#repository-layout)
+- [Screenshots](#screenshots)
+- [Quick start](#quick-start)
+- [Self-hosted deployment](#self-hosted-deployment-docker-compose)
+- [Development (API)](#development-api-python)
+
+## What it does
+
+At a high level:
+1. Your integration creates an invoice (defined in XMR).
+2. The UI shows payment instructions (address + amount).
+3. The system observes the chain using view-only wallet access to detect payments and update invoice status.
+4. Optional integrations (for example webhooks) can be used to trigger your internal order flow.
+
+What it does not do:
+- It does not provide custody, refunds, or any fund-moving automation.
+- It does not act as a financial intermediary.
+- It does not touch fiat rails in the core system.
+
+## Trust model
+
+- Funds always move from the customer to the merchant wallet; xmrcheckout only observes the chain to detect payments.
+- The maximum permission level is view-only wallet access (wallet address + private view key).
+- If any configuration or integration implies spend authority, treat it as a misconfiguration.
+
+## Repository layout
+
+- `ui/`: web UI
+- `api/`: API service (Python)
+- `docker-compose.yml`: local stack and self-hosted deployment
+- `nginx/`: reverse proxy / TLS termination for local HTTPS
+
+## Quick start
+
+### Homepage only (Docker)
 
-### Docker
 ```
 docker build -t xmrcheckout-home .
 docker run --rm -p 8080:80 xmrcheckout-home
 ```
 
-Open `http://localhost:8080` for the homepage.
+Open `http://localhost:8080`.
 
-## Run the full stack locally (Docker Compose)
+### Full stack (Docker Compose)
 
 ```
 docker compose up --build
@@ -26,6 +67,7 @@ The API runs on `http://127.0.0.1:8000` and Postgres on port `5432`.
 ## Self-hosted deployment (Docker Compose)
 
 1. Copy the environment template and fill in required values:
+
 ```
 cp .env.example .env
 ```
@@ -41,33 +83,34 @@ cp .env.example .env
 - Use the bundled wallet-rpc containers:
   - Set `MONERO_WALLET_RPC_URLS=http://wallet-rpc-reconciler-1:18083,http://wallet-rpc-reconciler-2:18083,http://wallet-rpc-reconciler-3:18083`
 - Or point to an external wallet-rpc service:
-  - Set `MONERO_WALLET_RPC_URLS`, `MONERO_WALLET_RPC_USER`,
+  - Set `MONERO_WALLET_RPC_URLS`, `MONERO_WALLET_RPC_USER`, `MONERO_WALLET_RPC_PASSWORD`, and `MONERO_WALLET_RPC_WALLET_PASSWORD`
-    `MONERO_WALLET_RPC_PASSWORD`, and `MONERO_WALLET_RPC_WALLET_PASSWORD`
 
 4. Start the stack:
+
 ```
 docker compose up --build -d
 ```
 
-### Donations (disabled by default)
+### Optional: donations (disabled by default)
 
 Donation endpoints and UI are off by default for self-hosted deployments.
 To enable donations:
 - Set `DONATIONS_ENABLED=true`
 - Set `FOUNDER_PAYMENT_ADDRESS` and `FOUNDER_VIEW_KEY`
 
-The UI uses the same flag (via Compose), so `/donate` stays unavailable
+The UI uses the same flag (via Compose), so `/donate` stays unavailable unless donations are explicitly enabled.
-unless donations are explicitly enabled.
 
-## Run the API (Python)
+## Development (API, Python)
 
 1. Set environment variables (see `api/.env.example`):
+
 ```
 export DATABASE_URL=postgresql://xmrcheckout:xmrcheckout@localhost:5432/xmrcheckout
 export API_KEYS=change-me-1
 ```
 
 2. Install dependencies:
+
 ```
 python -m venv .venv
 source .venv/bin/activate
@@ -75,6 +118,7 @@ pip install -r api/requirements.txt
 ```
 
 3. Start the API:
+
 ```
 uvicorn api.app.main:app --reload
 ```