# Gishen Email Templates — Design Spec

**Date:** 2026-08-07  
**Status:** Approved for implementation planning  
**Repo:** `Gishen/Gishen-Email-Templates`  
**Remote:** `https://gitea.yaltopia.com/Gishen/Gishen-Email-Templates.git`

## Goal

A shared React Email project that demos and exports transactional (and light marketing) emails for all Gishen surfaces: **Ecom**, **Admin**, and **B2B**. Brand, colors, and logo match the existing Gishen apps. Preview UI supports **English and Amharic**.

## Non-goals (v1)

- Sending mail (SMTP/ESP integration)
- Live backend wiring inside Ecom/Admin/B2B
- Dark-mode email variants
- Pixel-perfect Amharic typography across every client (system + common web-safe fallbacks)

## Architecture

Mirror **Amba-Emails**:

| Piece | Role |
|-------|------|
| `emails/` | React Email templates + shared components |
| `emails/theme.ts` | Gishen brand tokens |
| `emails/i18n/` | `en` / `am` string tables per template family |
| `emails/components/` | `EmailLayout`, `Button`, `Card`, `StatusBanner`, `OrderSummary` |
| `app/` | Next.js preview: template switcher + locale toggle |
| `app/api/email/[template]/route.ts` | Render HTML for demos / future consumer apps |
| `public/brand/` | Logo assets (from Gishen-B2B) |
| `CHANGELOG.md` | Keep a Changelog |
| `README.md` | Templates, props, how to consume |

**Scripts:** `npm run preview` (Next), `npm run email` (React Email CLI), `npm run build` (HTML export).

**Consumer contract:** apps pass props + `locale`; they either call the render API in demo setups or copy exported HTML / import templates later. v1 does not mutate sibling repos beyond using them as brand/reference sources.

## Brand

From `Gishen-B2B/src/data/brand.ts` and Admin Tailwind:

| Token | Value |
|-------|--------|
| brand | `#A8C73A` |
| brandDeep | `#8FAD2F` |
| forest | `#141414` |
| accent | `#E28A1A` |
| cream / background | `#F6F7F2` |
| surface | `#FFFFFF` |
| line | `#E2E5D8` |
| muted | `#5C5F56` |

- Product name: **Gishen Pharmacy**
- Logo: `Gishen-B2B/public/brand/gishen-logo.png` → `public/brand/` + optional data URI for clients that block remote images poorly in local demos
- Footer: `info@gishenpharmacy.org` · `https://gishenpharmacy.org` · Addis Ababa, Ethiopia

## Locales

- Every template accepts `locale: 'en' | 'am'` (default `'en'`).
- Preview UI has an en/am toggle.
- String tables live under `emails/i18n/`; Amharic copy is production-intent for v1 (not `TODO` placeholders).

## Template inventory

### Auth / account

1. `welcome`
2. `password-reset`
3. `email-verify`
4. `user-invite`

### Orders (Ecom / member)

5. `order-confirmation`
6. `order-packing`
7. `order-out-for-delivery`
8. `order-delivered`
9. `order-cancelled`

### B2B

10. `org-invite`
11. `join-code`
12. `approval-needed`
13. `statement-ready`
14. `credit-alert`
15. `organisation-verified`

### Prescriptions

16. `prescription-submitted`
17. `prescription-decision` (approved | rejected via props)
18. `prescription-ready`

### Admin ops

19. `low-stock`
20. `dispatch-assigned`
21. `procurement-alert`

### Marketing

22. `promotional`

### Ecom analytics

23. `shop-summary` — **one** template with `period: 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly'` and summary metrics props (orders, revenue, top SKUs, etc.)

## Shared components

- `EmailLayout` — logo header, cream body shell, branded footer
- `Button` — primary CTA (brand / forest text)
- `Card` — section block with line border
- `StatusBanner` — success / warning / danger / info using brand + accent
- `OrderSummary` — line items + totals for order emails
- `MetricGrid` — for `shop-summary` KPI rows

## Preview app behavior

- List all templates by category
- Live iframe or server-rendered preview of selected template
- Locale toggle (en/am)
- Sample props hardcoded per template for demo realism (Ethiopian pharmacy / B2B context)

## Git / repo setup

1. Create directory, `README.md`, `CHANGELOG.md`, scaffold app
2. `git init` → branch `main`
3. Initial commit(s)
4. `git remote add origin https://gitea.yaltopia.com/Gishen/Gishen-Email-Templates.git`
5. `git push -u origin main` (requires credentials available in environment)

## Reference projects

| Repo | Use |
|------|-----|
| Amba-Emails | Structure, React Email patterns, API route |
| Gishen-B2B | Brand, logo, portal email contexts |
| Gishen-Admin | Ops domains (stock, dispatch, procurement, Rx) |
| Gishen-Ecom | Order + shop summary contexts (clone if auth available) |
| Yaltopia-Ticket-Email | Secondary email reference (clone may need auth) |

**Note:** HTTPS clone of private Gitea repos failed in this environment without credentials. Local `Gishen-Admin` and `Gishen-B2B` copies are sufficient for brand; Ecom specifics use documented B2B/Admin order/stock flows where Ecom is unavailable.

## Success criteria

- `npm install && npm run preview` shows all templates with en/am switching
- Colors and logo clearly match Gishen apps
- HTML render API returns each template
- `CHANGELOG.md` records `0.1.0`
- Remote `main` pushed when credentials allow

## Out-of-scope follow-ups

- Wire templates into Nest/API workers
- ESP (Resend/SendGrid) adapters
- Automated visual regression of rendered HTML