# Gishen-B2B documentation

Living documentation for the **Gishen-B2B institutional portal** — the corporate medical-benefits client for HR, Finance, and Members.

**Workspace:** `/Users/kirukib/Desktop/Yaltopia Project/Gishen-B2B`

## Standing rule (non-negotiable)

**Whenever UI changes, update `docs/backend/` and `docs/features/INDEX.md` in the same change.**

Do not ship UI-only work with a “spec later” note. Every page, route, field, enum, role gate, or cross-repo contract must be reflected in the backend spec before the work is considered done.

Applies to:

- Scaffold and baseline entities
- New or changed routes/pages
- New UI capabilities (import, invite, package rules, Rx upload, finance export, approvals, etc.)
- Field/enum/status changes
- Role/permission changes
- Cross-repo contracts (Admin activation, Ecom checkout split, events)

**Done checklist for any PR/task:** UI/mock works **and** `docs/backend/` + `docs/features/INDEX.md` reflect it.

## How to extend specs

1. **Product scope** — start at [`product/b2b-features.md`](product/b2b-features.md) for the §3 feature checklist.
2. **Feature map** — update [`features/INDEX.md`](features/INDEX.md) when adding pages; link to per-feature docs under `features/`.
3. **Backend contract** — add or edit entities in [`backend/entities/`](backend/entities/), endpoints in [`backend/endpoints/`](backend/endpoints/), events in [`backend/events/`](backend/events/README.md).
4. **Cross-repo** — record Admin/Ecom/Mobile coordination in [`coordination/`](coordination/).
5. **Clinical withhold** — every entity/endpoint that touches member health data must document what HR_ADMIN and FINANCE must **not** receive; note SUPER_USER bypass where applicable.

## Directory layout

```
docs/
  README.md                 # this file — standing rule + navigation
  product/
    b2b-features.md         # §3 feature checklist (build brief)
  backend/                  # living spec sheet for shared platform API
    OVERVIEW.md             # auth, tenancy, errors, pagination, RBAC
    entities/               # data model
    endpoints/              # REST (or RPC) contract
    events/                 # domain events / webhooks
  coordination/
    gishen-admin.md         # Admin writes commercial terms; Rx queue
    gishen-ecom.md          # shared identity, checkout entitlement split
    open-items.md           # cross-repo flags and decisions
  features/
    INDEX.md                # feature → pages → entities → endpoints
    *.md                    # per-feature notes
```

## Shared backend model

There is **one shared backend** (not built in this repo). This frontend implements §3 UI against mocks typed to the living spec sheet. Backend consolidation happens later after Ecom, Mobile, B2B, and Admin spec sheets stabilize.

## Brand & i18n (reference)

| Token | Value |
|-------|-------|
| Mint (primary) | `#a8c73a` |
| Forest (ink) | `#141414` |
| Accent (credit warnings) | `#e28a1a` |

Launch locales: **English (`en`)** + **Amharic (`am`)**. User preference stored as `user.locale`.

## Related repos

| Repo | Role |
|------|------|
| **Gishen-B2B** (this) | Institutional portal — HR, Finance, Member |
| **Gishen-Admin** | Org commercial activation, pharmacist Rx review, credit/invoice |
| **Gishen-Ecom** | Retail catalog, cart, checkout (entitlement split UI) |
| **Gishen-Mob** | Mobile-only: camera edge detection, biometrics, push |