Ehsan/hammam-dev.md

# Hammam Dev — EHSAN "Closed Donation Loop" (POC)

> Onboarding brief for any developer or AI coding agent (e.g. OpenClaw) taking over
> this project. Read it fully before editing. The repo is hosted on a self-hosted
> **Gitea** server and runs on a **Mac Mini** via Docker.

## 1. What this product is
A bilingual (Arabic / English, full RTL + LTR) **proof-of-concept charity donation web
app** inspired by the Saudi "EHSAN" (إحسان) platform. Its core idea is a **Closed
Donation Loop**:

- Beneficiaries submit support requests (housing, food, electricity, water, health,
  court-ordered debt, appliances like A/C & refrigerator, etc.).
- Each request/opportunity has a **funding target**. Donations from multiple donors
  **accumulate and are clamped to the target** — a case can never be over-funded.
- A case only **enters the "closed loop" fulfillment pipeline once it is fully funded**.
  This is the central business rule. Do not break it.
- After funding, the flow continues to confirmation / tracking, and a simulated
  WhatsApp notification log records donor/beneficiary messaging.

This is a POC/demo: data is **in-memory mock data** (no real database, no real payments).

## 2. Tech stack
- Monorepo: **pnpm workspaces**, Node.js 24, TypeScript 5.9.
- Web app (`artifacts/ehsan-poc`): React + Vite + **wouter** (routing) +
  **TanStack Query** (data) + **Tailwind CSS** + shadcn/ui components.
- API (`artifacts/api-server`): **Express 5**, all routes mounted under `/api`,
  health at `/api/healthz`. Data lives in `src/lib/mockDb.ts` (in-memory; resets on restart).
- Shared libs under `lib/`: `api-spec` (OpenAPI source of truth), `api-client-react`
  (generated React Query hooks), `api-zod` (Zod schemas), `db` (Drizzle schema, not
  active at runtime since data is in-memory).
- All workspace libs export TypeScript source directly (`./src/index.ts`) — no lib
  pre-build step; Vite/esbuild consume the source.

## 3. Repo map
- `artifacts/ehsan-poc/src/pages/` — screens: home, about, waqf, baraem, request,
  opportunities, donate/:id, cart, login, admin, track/:id, thank-you/:id,
  whatsapp-log, not-found.
- `artifacts/ehsan-poc/src/contexts/` — `LanguageContext` (ar/en + RTL), `CartContext`
  (multi-case donation cart), `AuthContext` (mock admin login).
- `artifacts/ehsan-poc/src/components/` — `Riyal.tsx` (renders the NEW Saudi Riyal
  symbol via an image mask), `layout/` (Header, AppLayout), `ui/` (shadcn components).
- `artifacts/api-server/src/routes/` — `health`, `requests`, `donors`, `stats`,
  `whatsappLog`. Mounted in `routes/index.ts`.
- Root deploy files: `Dockerfile.web`, `Dockerfile.api`, `docker/nginx.conf`,
  `docker-compose.yml`, `deploy.sh`, `scripts/push-to-gitea.sh`, `DEPLOYMENT.md`.

## 4. How to run locally (development)
```bash
pnpm install
pnpm --filter @workspace/api-server run dev   # API
pnpm --filter @workspace/ehsan-poc run dev    # Web (needs PORT and BASE_PATH env)
pnpm run typecheck                            # full typecheck
pnpm run build                                # typecheck + build everything
```
Note: `vite.config.ts` REQUIRES `PORT` and `BASE_PATH` env vars even for `build`
(it throws otherwise), e.g.
`PORT=8080 BASE_PATH=/ pnpm --filter @workspace/ehsan-poc run build`.

## 5. How it runs in production (Mac Mini, Docker)
Two services in `docker-compose.yml`:
- `api` — Express, internal only, listens on `PORT=8080`, healthcheck `/api/healthz`.
- `web` — nginx that serves the built Vite SPA **and reverse-proxies `/api/` to
  `api:8080`**. The browser always calls **same-origin `/api/...`**, so there is NO
  frontend API URL to configure.

Deploy / redeploy on the Mac Mini:
```bash
./deploy.sh    # git pull gitea main → docker compose down → build → up -d
```
App is then served on the Mac Mini at `http://localhost:8080` (override with `WEB_PORT`).

## 6. Deployment flow (how code travels)
```
Edit code → commit → push to Gitea (remote name: gitea, branch: main)
          → on Mac Mini run ./deploy.sh → Docker rebuilds & restarts
```
- Central repo is **Gitea** (no GitHub). Remote name everywhere is `gitea`, branch `main`.
- `scripts/push-to-gitea.sh` pushes from a dev machine; `deploy.sh` redeploys on the Mac Mini.
- An AI agent working directly on the Mac Mini clone should use this loop:
  edit → test → `git commit` → `git push gitea main` → `./deploy.sh`.

## 7. Hard rules / gotchas — do NOT break these
- **amd64 / glibc ONLY.** The pnpm workspace strips every native binary that is not
  `linux-x64-gnu`. Docker build stages MUST use `node:24-bookworm-slim` (glibc, not
  alpine) and `platform: linux/amd64` (runs under Rosetta on Apple Silicon). Do not
  switch the build base to alpine or arm64 — rollup / tailwind-oxide / lightningcss
  will fail to find native binaries.
- **Funding rule.** Donations accumulate and clamp to the target; a case enters the
  fulfillment pipeline only when fully funded. Preserve this.
- **Bilingual + RTL.** Every user-facing string must exist in both Arabic and English
  via `LanguageContext`. Don't hardcode single-language text. Keep RTL layout working.
- **Currency.** Saudi Riyal uses the new official symbol rendered by the `<Riyal/>`
  component (image mask), not the old "ر.س"/"SAR" text. Reuse `<Riyal/>`.
- **Routing base.** The app is mounted under a base path via `import.meta.env.BASE_URL`.
  Use it for routes/links; never hardcode root-relative `/api` in a way that escapes
  the base — call same-origin `/api/...` through the proxy.
- **Data is ephemeral.** mockDb is in-memory; restarting the `api` container resets it.
  If you add persistence, add a database service to `docker-compose.yml` accordingly.
- **HMR quirk (dev):** if you see "useLanguage must be used within a LanguageProvider"
  while the code is correct, it's stale Fast Refresh state — restart the web dev server.
- Always run `pnpm run build` (typecheck + build) before pushing to catch type errors.

## 8. Suggested first task for a new agent
Read `DEPLOYMENT.md`, `artifacts/ehsan-poc/src/App.tsx`, and
`artifacts/api-server/src/routes/index.ts` to confirm the routes and data model, then
summarize your understanding of the funding / closed-loop flow before making any change.