gov-portals-monorepo/README.md

<<<<<<< HEAD
# gov-portals-monorepo

=======
# Gov Portals Monorepo

Monorepo for next-generation governmental body web portals. Each subdirectory is named by the body’s **initials** and contains one portal application.

**Repository:** https://gitea.d-bis.org/nsatoshi/gov-portals-monorepo.git

# Gov Portals Monorepo

Monorepo for next-generation governmental body web portals. Each subdirectory is named by the body's **initials** and contains one portal application.

**Repository:** https://gitea.d-bis.org/Gov_Web_Portals/gov-portals-monorepo.git

```bash
git clone --recurse-submodules https://gitea.d-bis.org/Gov_Web_Portals/gov-portals-monorepo.git
cd gov-portals-monorepo
pnpm install
```

## Portals

| Directory | Abbreviation | Official / long-form name |
|-----------|----------------|----------------------------|
| `DBIS/`   | DBIS           | Digital Bank of International Settlements |
| `ICCC/`   | ICCC           | International Criminal Court of Commerce |
| `OMNL/`   | OMNL           | Organisation Mondiale du Numérique |
| `XOM/`    | XOM            | Sovereign Military Hospitaller Order of St. John of Jerusalem of Rhodes and of Malta |

**Naming note (XOM):** The directory `XOM/` refers to the sovereign entity recognized in UN relations. In UN and official references the most common abbreviations are **SMOM** (Sovereign Military Order of Malta), **Sovereign Order of Malta**, or simply **Order of Malta**. This project uses **XOM** as the directory name; the official long-form name above is the UN/official style.

## Monorepo and portal repos

This project is a **monorepo**. The canonical repository is:

- **Monorepo:** https://gitea.d-bis.org/Gov_Web_Portals/gov-portals-monorepo.git

The four portals (DBIS, ICCC, OMNL, XOM) are **git submodules** linking to per-portal repos:

| Portal | Submodule | Repository |
|--------|-----------|------------|
| DBIS   | `DBIS/`   | https://gitea.d-bis.org/Gov_Web_Portals/DBIS.git |
| ICCC   | `ICCC/`   | https://gitea.d-bis.org/Gov_Web_Portals/ICCC.git |
| OMNL   | `OMNL/`   | https://gitea.d-bis.org/Gov_Web_Portals/OMNL.git |
| XOM    | `XOM/`    | https://gitea.d-bis.org/Gov_Web_Portals/XOM.git |

Clone with submodules: `git clone --recurse-submodules https://gitea.d-bis.org/Gov_Web_Portals/gov-portals-monorepo.git`

To push the whole monorepo: set `origin` to the monorepo URL, then `git push -u origin main`. Push submodule changes from each portal directory.

## Standardization

All portals **must** follow the same tech stack and policies:

- **[TECH_STACK.md](./TECH_STACK.md)** — Mandatory technologies (Next.js, TypeScript, Tailwind, testing, etc.)
- **[TECH_POLICIES.md](./TECH_POLICIES.md)** — Security, accessibility, quality, and governance

Org structure and navigation (shared across DBIS, ICCC, OMNL, XOM):

- **[ORG_STRUCTURE.md](./ORG_STRUCTURE.md)** — Governance layers, executive admin, mission departments per entity, regional structure, oversight, membership, finance, knowledge, technology
- **[PORTAL_NAVIGATION.md](./PORTAL_NAVIGATION.md)** — Sitemap, main nav, role-based dashboards (public, members, judges/clerks, diplomats, donors, staff), and required workflows (Submit / Apply / Report / Request / Whistleblower)

Shared config at repo root:

- **TypeScript** — `tsconfig.base.json` (portals extend this)
- **ESLint** — `.eslintrc.cjs` (portals extend and add Next/TypeScript rules)
- **Prettier** — `.prettierrc.json`, `.prettierignore`
- **Node** — `.nvmrc` (Node 20 LTS)

## Scaffolding

Each portal (DBIS, ICCC, OMNL, XOM) is scaffolded with the same Next.js App Router structure, navigation, and access control:

- **Shared package** — `packages/shared` provides types (roles, session), nav/sitemap config (base + entity-specific), and Tailwind design tokens. Portals depend on `@public-web-portals/shared` and use `getNavForPortal(portalId)` for header/footer.
- **Structure** — Public routes (about, governance, departments, membership, documents, news, contact, regions), transparency (audit, ethics, whistleblower, sanctions, data-protection), workflow routes (submit, apply, report, request), dashboard (home, submissions, requests), and auth (login, logout). Entity-specific routes vary per portal (see [PORTAL_NAVIGATION.md](./PORTAL_NAVIGATION.md) §5).
- **Access** — Middleware enforces protected routes; placeholder auth uses a `portal-role` cookie. RBAC in `lib/rbac.ts` defines which roles can access which paths. Replace with OIDC/OAuth 2.0 when the identity provider is configured.

See [PORTAL_NAVIGATION.md](./PORTAL_NAVIGATION.md) and [ORG_STRUCTURE.md](./ORG_STRUCTURE.md) for the full sitemap and org-derived navigation.

## Root scripts

From the repo root (e.g. for formatting/linting shared config files):

```bash
pnpm install
pnpm run format:check
pnpm run format
pnpm run lint
```

## Adding a new portal

1. Create a directory with the body’s initials.
2. Bootstrap a Next.js app (TypeScript, Tailwind, App Router) per TECH_STACK.md.
3. In the new portal, extend root configs:
   - `tsconfig.json`: `"extends": "../tsconfig.base.json"` (or path to root).
   - ESLint: extend root `.eslintrc.cjs` and add Next + TypeScript.
   - Use root `.prettierrc.json` (or don’t override).
4. Add a README in the portal linking to TECH_STACK.md and TECH_POLICIES.md.
5. List the new portal in this README and in any CI/docs that enumerate portals.

## Portal checklist

Each portal should satisfy [PORTAL_CHECKLIST.md](./PORTAL_CHECKLIST.md) before release.