From c04943574d55565e0430684771abd8650fa0db37 Mon Sep 17 00:00:00 2001 From: Abhishekfm Date: Fri, 15 May 2026 16:13:21 +0530 Subject: [PATCH 1/3] docs: Update README.md to reflect project structure and branding integration --- README.md | 163 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 141 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 2a1d30f2..6d9d471f 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,161 @@ -# IDS-DRR +# IDS-DRR Frontend -This is the frontend repository of IDS-DRR built using **React**, **Next.js**, and **GraphQL**. +The frontend for **IDS-DRR** (Integrated Data System for Disaster Risk Reduction), built with **React 19**, **Next.js 15**, **TypeScript**, and **GraphQL**. -## Dependencies +This repository ships with **no deployment-specific content**. All branding, copy, languages, states, partners, "About" page, footer, etc. live in a separate **branding package** that is plugged in at install time. This keeps the core app reusable across deployments while individual deployments (e.g. India) maintain their own content in their own repos. -The following dependencies must be available globally on your system: + -- Download and install [https://nodejs.org/en/](NodeJS LTS v18+) and npm +> Reference branding implementation: [ids-drr-india-branding](https://github.com/CivicDataLab/ids-drr-india-branding). -## Installation & Setup +![Coverage](https://img.shields.io/badge/Tests_Coverage-60%25-yellow) -1. Clone the repository +--- -`git clone https://github.com/CivicDataLab/IDS-DRR-Frontend.git` +## Table of contents -2. Navigate to the project directory. +- [Requirements](#requirements) +- [Quick start](#quick-start) +- [Environment variables](#environment-variables) +- [How the branding plugin works](#how-the-branding-plugin-works) +- [Available scripts](#available-scripts) +- [Project structure](#project-structure) +- [License](#license) -`cd IDS-DRR-Frontend` +--- -3. Install the dependencies. +## Requirements -`npm install --force` +- **Node.js** v22.x (LTS) — matches the version used in CI (`.github/workflows/pre-merge.yml`) +- **npm** v10+ +- A code editor with **Prettier** and **ESLint** integration (configs are committed in `package.json`) -4. Create your local environment configuration in `.env.local` +You do **not** need Docker, the India branding repo, or any deployment credentials to develop or contribute. -## Usage +--- -After completing the installation steps, you can run the project locally by executing: +## Quick start -`npm run dev` +```bash +git clone https://github.com/CivicDataLab/IDS-DRR-Frontend.git +cd IDS-DRR-Frontend +npm install --force +cp .env .env.local # then edit values as needed (see below) +npm run dev +``` -## Running Tests +The app will be available at . -`npm run test` +> `--force` is intentional. The Next.js 15 / React 19 / `opub-ui` peer-dep tree emits a handful of harmless warnings; CI uses the same flag (`.github/workflows/pre-merge.yml`). -![Coverage](https://img.shields.io/badge/Tests_Coverage-60%25-yellow) +With no branding configured, the app runs against an empty in-repo "stub" — features like the About page or partner logos are hidden, and the rest of the app (charts, maps, datasets, search) works normally. That's the right experience for working on the core frontend. + +--- + +## Environment variables + +Copy `.env` to `.env.local` and adjust. Most of these have sensible defaults; the only ones you'll typically need to change for local work are the backend URLs. + +| Variable | Purpose | Required for local dev? | +| --------------------------------------- | -------------------------------------------------------- | ----------------------- | +| `BACKEND_URL` | GraphQL backend used at build time / SSR | Yes, for SSR pages | +| `NEXT_PUBLIC_BACKEND_URL` | Same, exposed to the browser. Drives `features.datasets` | Yes | +| `DATA_MANAGEMENT_LAYER_URL` | Data management layer URL (server-side) | Yes, for SSR | +| `NEXT_PUBLIC_DATA_MANAGEMENT_LAYER_URL` | Same, exposed to the browser | Yes | +| `SITE_URL` | Canonical site URL (used in metadata, OG tags) | Optional | +| `NEXT_PUBLIC_GOOGLE_ANALYTICS_APP_ID` | GA4 property id | Optional | +| `SENTRY_*` | Error tracking | Optional in dev | + +> Any variable prefixed with `NEXT_PUBLIC_` is bundled into the client JavaScript — never put secrets in those. + +--- + +## How the branding plugin works + +This section is short but worth reading once — almost every "where do I add this?" question comes back to it. + +The frontend imports a single npm package called `ids-drr-branding`. There are different _implementations_ of that package, each named identically so they can be swapped without code changes: + +| Implementation | Where it lives | When it's used | +| ---------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------ | +| **Stub** (empty) | `branding-stub/` in this repo | Default. OSS dev, CI, anyone without deployment access | +| **India** (reference) | `CivicDataLab/ids-drr-india-branding` (separate repo) | The India deployment | +| **Your deployment** (future state / org) | your own repo | Any new deployment that forks IDS-DRR | + +`package.json` declares `"ids-drr-branding": "file:./branding-stub"`, so by default the stub is what gets installed. The stub exports `undefined` for every optional component and `{}` for `config`. The frontend handles those gracefully — `app/[locale]/about-us/page.tsx`, for example, returns a 404 when no `AboutPage` is provided. See `config/branding.ts` and `config/site.ts` for the full contract. + +**Where new code should live:** + +- Generic feature (chart, map, search, GraphQL query, layout, i18n machinery): **this repo**. +- India-specific content (a logo, a partner name, the About-page copy, the glossary CSV): **the india-branding repo**. + +If you're not sure which side a change belongs on, open an issue and ask before opening the PR — getting this wrong is the most common reason a PR gets bounced. + +**Running locally with the real India branding (only if you have access):** + +If you also have the `ids-drr-india-branding` repo cloned somewhere on disk and want to develop against it: + +```bash +# from this repo's root +npm install --no-save --install-links file:/absolute/path/to/ids-drr-india-branding +``` + +- `--no-save` keeps `package.json` and `package-lock.json` unchanged. The lockfile must stay pinned to the stub so OSS contributors and CI are unaffected. +- `--install-links` copies the package contents instead of symlinking, so its transitive deps resolve correctly. + +You'll need to re-run that command after any subsequent `npm install` or `npm ci` (those revert `node_modules/ids-drr-branding` back to the stub). To return to the stub explicitly, just run `npm install --force` again. + +> If you only intend to contribute generic improvements to the frontend, you do **not** need this step. Stay on the stub. + +--- + +## Available scripts + +| Script | What it does | +| ----------------------- | ------------------------------------------------------------ | +| `npm run dev` | Start the Next.js dev server + GraphQL codegen in watch mode | +| `npm run build` | Generate GraphQL types and build the production bundle | +| `npm start` | Start the built production server | +| `npm run lint` | ESLint — zero warnings allowed | +| `npm run type-check` | `tsc --noEmit` | +| `npm run knip` | Detect unused files, exports, and dependencies | +| `npm run test` | Jest test suite | +| `npm run test:watch` | Jest in watch mode | +| `npm run test:coverage` | Jest with coverage report | +| `npm run generate` | GraphQL codegen in watch mode | +| `npm run build:tokens` | Regenerate design tokens (Style Dictionary) | +| `npm run clean` | Remove `node_modules` and `package-lock.json` | + +--- + +## Project structure + +``` +IDS-DRR-Frontend/ +├── app/ # Next.js App Router pages (locale-prefixed) +├── branding-stub/ # Empty default branding package (package name: ids-drr-branding) +├── components/ # Shared React components +├── config/ +│ ├── branding.ts # Re-exports the branding namespace with safe defaults +│ ├── site.ts # Site-wide config derived from branding.config +│ └── codegen.ts # GraphQL codegen config +├── gql/ # GraphQL queries and generated types +├── hooks/ # Reusable React hooks +├── i18n/ # next-intl setup +├── lib/ # Pure utilities (routes, formatters, glossary, ...) +├── locales/ # Frontend-owned base translations +├── public/ # Static assets shipped with the core app +├── styles/tokens/ # Design tokens (Style Dictionary output) +├── tests/ # Jest tests and fixtures +├── types/ # Shared TS types +├── next.config.ts +└── tailwind.config.js +``` + +The branding contract itself lives in the external [ids-drr-branding-types](https://github.com/open-contracting/ids-drr-branding-types) package — read its `src/index.ts` to see which slots a branding implementation can fill in. + +--- -## Get Involved +## License -- Start by reading our Code of conduct -- Get familiar with our contributor guidelines explaining the different ways in which you can support this project! We need your help! +[MIT](./LICENSE) © CivicDataLab From ede460908d68d0e52bbef9a5e43a3bf62665d433 Mon Sep 17 00:00:00 2001 From: Abhishekfm Date: Wed, 20 May 2026 15:14:03 +0530 Subject: [PATCH 2/3] docs: Update README.md with branding contract and example implementation details --- README.md | 50 +++++++++++++++++++++++++++----------------------- 1 file changed, 27 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 6d9d471f..648327c8 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,9 @@ This repository ships with **no deployment-specific content**. All branding, cop -> Reference branding implementation: [ids-drr-india-branding](https://github.com/CivicDataLab/ids-drr-india-branding). +> Branding contract: [ids-drr-branding-types](https://github.com/CivicDataLab/ids-drr-branding-types). + +> Example branding implementation: [ids-drr-india-branding](https://github.com/CivicDataLab/ids-drr-india-branding). ![Coverage](https://img.shields.io/badge/Tests_Coverage-60%25-yellow) @@ -17,7 +19,7 @@ This repository ships with **no deployment-specific content**. All branding, cop - [Requirements](#requirements) - [Quick start](#quick-start) - [Environment variables](#environment-variables) -- [How the branding plugin works](#how-the-branding-plugin-works) +- [How the branding package works](#how-the-branding-package-works) - [Available scripts](#available-scripts) - [Project structure](#project-structure) - [License](#license) @@ -56,42 +58,44 @@ With no branding configured, the app runs against an empty in-repo "stub" — fe Copy `.env` to `.env.local` and adjust. Most of these have sensible defaults; the only ones you'll typically need to change for local work are the backend URLs. -| Variable | Purpose | Required for local dev? | -| --------------------------------------- | -------------------------------------------------------- | ----------------------- | -| `BACKEND_URL` | GraphQL backend used at build time / SSR | Yes, for SSR pages | -| `NEXT_PUBLIC_BACKEND_URL` | Same, exposed to the browser. Drives `features.datasets` | Yes | -| `DATA_MANAGEMENT_LAYER_URL` | Data management layer URL (server-side) | Yes, for SSR | -| `NEXT_PUBLIC_DATA_MANAGEMENT_LAYER_URL` | Same, exposed to the browser | Yes | -| `SITE_URL` | Canonical site URL (used in metadata, OG tags) | Optional | -| `NEXT_PUBLIC_GOOGLE_ANALYTICS_APP_ID` | GA4 property id | Optional | -| `SENTRY_*` | Error tracking | Optional in dev | +| Variable | Purpose | Required for local dev? | +| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | +| `BACKEND_URL` | URL of a [DataSpaceBackend](https://github.com/CivicDataLab/DataSpaceBackend) deployment (Django + GraphQL). Used server-side for the datasets/search API. | Yes, if you're working on dataset pages | +| `NEXT_PUBLIC_BACKEND_URL` | Same DataSpaceBackend URL, exposed to the browser. Its presence also enables `features.datasets` (the datasets nav link and pages). | Yes, if you're working on dataset pages | +| `DATA_MANAGEMENT_LAYER_URL` | URL of an [IDS-DRR-Data-Management](https://github.com/CivicDataLab/IDS-DRR-Data-Management) deployment. Used server-side. | Yes, for analytics / SSR pages | +| `NEXT_PUBLIC_DATA_MANAGEMENT_LAYER_URL` | Same data-management URL, exposed to the browser. | Yes, for analytics / SSR pages | +| `SITE_URL` | Canonical site URL (used in metadata and OG tags). | Optional | +| `NEXT_PUBLIC_GOOGLE_ANALYTICS_APP_ID` | GA4 property id. | Optional | +| `SENTRY_*` | Error tracking. | Optional in dev | > Any variable prefixed with `NEXT_PUBLIC_` is bundled into the client JavaScript — never put secrets in those. --- -## How the branding plugin works +## How the branding package works This section is short but worth reading once — almost every "where do I add this?" question comes back to it. -The frontend imports a single npm package called `ids-drr-branding`. There are different _implementations_ of that package, each named identically so they can be swapped without code changes: +The frontend imports a single npm package called `ids-drr-branding`. The **contract** for that package — the shape of its `config` object and the optional React components it can export — is defined by [ids-drr-branding-types](https://github.com/CivicDataLab/ids-drr-branding-types). That repo's `src/index.ts` is the source of truth; the inline comments there are the canonical documentation of every configurable field (states, resources, locales, messages, brand assets, links, feature flags, and so on). + +Different deployments provide **different implementations** of that contract. They all use the same package name (`ids-drr-branding`) so they're drop-in replacements for each other. -| Implementation | Where it lives | When it's used | -| ---------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------ | -| **Stub** (empty) | `branding-stub/` in this repo | Default. OSS dev, CI, anyone without deployment access | -| **India** (reference) | `CivicDataLab/ids-drr-india-branding` (separate repo) | The India deployment | -| **Your deployment** (future state / org) | your own repo | Any new deployment that forks IDS-DRR | +| Implementation | Where it lives | When it's used | +| ---------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------ | +| **Stub** (empty) | `branding-stub/` in this repo | Default. OSS dev, CI, anyone without deployment access | +| **India** (example implementation) | [ids-drr-india-branding](https://github.com/CivicDataLab/ids-drr-india-branding) | The India deployment. Read this for a worked example. | +| **Your deployment** (future state / org) | your own repo, following the contract from `ids-drr-branding-types` | Any new deployment that forks IDS-DRR | -`package.json` declares `"ids-drr-branding": "file:./branding-stub"`, so by default the stub is what gets installed. The stub exports `undefined` for every optional component and `{}` for `config`. The frontend handles those gracefully — `app/[locale]/about-us/page.tsx`, for example, returns a 404 when no `AboutPage` is provided. See `config/branding.ts` and `config/site.ts` for the full contract. +`package.json` declares `"ids-drr-branding": "file:./branding-stub"`, so by default the stub is what gets installed. The stub exports `undefined` for every optional component and `{}` for `config`. The frontend handles those gracefully — `app/[locale]/about-us/page.tsx`, for example, returns a 404 when no `AboutPage` is provided. **Where new code should live:** - Generic feature (chart, map, search, GraphQL query, layout, i18n machinery): **this repo**. -- India-specific content (a logo, a partner name, the About-page copy, the glossary CSV): **the india-branding repo**. +- Deployment-specific content (a logo, a partner name, the About-page copy, the glossary CSV): **the relevant branding repo** (e.g. `ids-drr-india-branding` for India). -If you're not sure which side a change belongs on, open an issue and ask before opening the PR — getting this wrong is the most common reason a PR gets bounced. +If you're not sure which side a change belongs on, open an issue and ask before opening the PR. -**Running locally with the real India branding (only if you have access):** +**Example: Running locally with the real India branding:** If you also have the `ids-drr-india-branding` repo cloned somewhere on disk and want to develop against it: @@ -152,7 +156,7 @@ IDS-DRR-Frontend/ └── tailwind.config.js ``` -The branding contract itself lives in the external [ids-drr-branding-types](https://github.com/open-contracting/ids-drr-branding-types) package — read its `src/index.ts` to see which slots a branding implementation can fill in. +For the branding contract, see [ids-drr-branding-types](https://github.com/CivicDataLab/ids-drr-branding-types) (covered above in [How the branding package works](#how-the-branding-package-works)). --- From e5f0d4cc72a438aa03ad568791f738e5e69b3ba0 Mon Sep 17 00:00:00 2001 From: Abhishekfm Date: Wed, 20 May 2026 15:21:28 +0530 Subject: [PATCH 3/3] docs: Update README.md to correct project name --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 648327c8..664d5095 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # IDS-DRR Frontend -The frontend for **IDS-DRR** (Integrated Data System for Disaster Risk Reduction), built with **React 19**, **Next.js 15**, **TypeScript**, and **GraphQL**. +The frontend for **IDS-DRR** (Intelligent Data Solution for Disaster Risk Reduction), built with **React 19**, **Next.js 15**, **TypeScript**, and **GraphQL**. This repository ships with **no deployment-specific content**. All branding, copy, languages, states, partners, "About" page, footer, etc. live in a separate **branding package** that is plugged in at install time. This keeps the core app reusable across deployments while individual deployments (e.g. India) maintain their own content in their own repos. @@ -58,15 +58,15 @@ With no branding configured, the app runs against an empty in-repo "stub" — fe Copy `.env` to `.env.local` and adjust. Most of these have sensible defaults; the only ones you'll typically need to change for local work are the backend URLs. -| Variable | Purpose | Required for local dev? | -| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | +| Variable | Purpose | Required for local dev? | +| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | `BACKEND_URL` | URL of a [DataSpaceBackend](https://github.com/CivicDataLab/DataSpaceBackend) deployment (Django + GraphQL). Used server-side for the datasets/search API. | Yes, if you're working on dataset pages | | `NEXT_PUBLIC_BACKEND_URL` | Same DataSpaceBackend URL, exposed to the browser. Its presence also enables `features.datasets` (the datasets nav link and pages). | Yes, if you're working on dataset pages | -| `DATA_MANAGEMENT_LAYER_URL` | URL of an [IDS-DRR-Data-Management](https://github.com/CivicDataLab/IDS-DRR-Data-Management) deployment. Used server-side. | Yes, for analytics / SSR pages | -| `NEXT_PUBLIC_DATA_MANAGEMENT_LAYER_URL` | Same data-management URL, exposed to the browser. | Yes, for analytics / SSR pages | -| `SITE_URL` | Canonical site URL (used in metadata and OG tags). | Optional | -| `NEXT_PUBLIC_GOOGLE_ANALYTICS_APP_ID` | GA4 property id. | Optional | -| `SENTRY_*` | Error tracking. | Optional in dev | +| `DATA_MANAGEMENT_LAYER_URL` | URL of an [IDS-DRR-Data-Management](https://github.com/CivicDataLab/IDS-DRR-Data-Management) deployment. Used server-side. | Yes, for analytics / SSR pages | +| `NEXT_PUBLIC_DATA_MANAGEMENT_LAYER_URL` | Same data-management URL, exposed to the browser. | Yes, for analytics / SSR pages | +| `SITE_URL` | Canonical site URL (used in metadata and OG tags). | Optional | +| `NEXT_PUBLIC_GOOGLE_ANALYTICS_APP_ID` | GA4 property id. | Optional | +| `SENTRY_*` | Error tracking. | Optional in dev | > Any variable prefixed with `NEXT_PUBLIC_` is bundled into the client JavaScript — never put secrets in those.