DELTA Resilience (Disaster & Hazardous Events, Losses and Damages Tracking & Analysis)

DELTA Resilience is a comprehensive system, not just an open-source software. Co-developed with data producers and users and building on DesInventar Sendai, DELTA brings together:

• Methodological frameworks
• Data standards and governance,
• Capacity development and technical assistance,
• Open-source software

It supports nationally owned Disaster Tracking Systems to monitor hazardous events and record losses and damages at national and subnational levels—whether countries use the DELTA Resilience software interface or strengthen their existing national platforms.

Visit the project website for more details. See CHANGELOG.md for release history.

Features

• Create, edit and publish hazardous events, disaster events and disaster records
• Geospatial footprints
• Import tools for legacy datasets (DesInventar using DIX - DesInventar eXchange)
• Role based access
• Multi-factor authentication (TOTP)
• Multi-language support (i18n)
• Multi-tenant, multi-country architecture

Technology stack

• TypeScript
• Node.js (v22 recommended)
• React Router v7 (React)
• Vite
• Tailwind CSS v4
• PrimeReact (UI components)
• Drizzle ORM
• PostgreSQL 17 + PostGIS
• Vitest (unit and integration tests)
• Playwright (end-to-end tests)

Project structure

Below is a view of the repository layout and the purpose of key folders/files to help new contributors navigate the codebase.

├── _docs/                     # Developer docs and design docs
├── app/                       # React Router v7 app source
│   ├── backend.server/        # Server-side API handlers and models
│   ├── components/            # Shared UI components (charts, maps, tables, etc.)
│   ├── frontend/              # Shared frontend views and form components
│   ├── pages/                 # Full-page components (access management, org management)
│   ├── routes/                # React Router route modules (under $lang+ prefix)
│   ├── services/              # Application-level service layer
│   ├── utils/                 # Utility functions (auth, email, logging, etc.)
│   ├── types/                 # Global TypeScript types
│   └── db/                    # DB helpers and query layer
├── tests/                     # Test suites (unit, integration, integration-realdb, e2e)
├── locales/                   # i18n translation files
├── scripts/                   # Database init, build and deployment scripts
├── public/                    # Static assets served by the app
├── docker-compose.yml         # Docker Compose setup (app + PostgreSQL/PostGIS + Adminer)
├── Dockerfile.app             # Application container definition
├── Makefile                   # Convenience targets (start, stop, migrate, logs, db-shell)
├── drizzle.config.ts          # Drizzle ORM configuration
├── CHANGELOG.md               # Release history
└── example.env                # Example environment variables

Notes:

• The app/ directory contains the bulk of the application code (React Router routes, frontend components, and server models).

• _docs/ contains developer and design documentation — consult these before contributing.

• scripts/ includes db schema and initialization scripts used in CI/deploy flows.

• public/ contains static front-end assets and theme files.

• build/, uploads/, and logs/ are generated at build/runtime and are not committed to the repository.

Quick start (local development)

Docker (recommended)

The fastest way to get a working environment is Docker Compose, which starts the app, PostgreSQL 17 + PostGIS, and Adminer together.

docker compose build
docker compose up -d
docker compose exec app yarn dbsync

Open http://localhost:3000. Use docker-compose logs -f app to tail logs.

For Windows users, the Docker setup now keeps container node_modules in a separate Docker volume. That avoids native binary mismatches when switching between Docker on Linux containers and running yarn install directly on Windows in the same checkout.

Recommended Docker workflow on Windows:

docker compose down
if (Test-Path node_modules) { Remove-Item -Recurse -Force node_modules }
docker compose build
docker compose up -d
docker compose exec app yarn dbsync

If you use Docker for this checkout, avoid running yarn install on the host in the same folder. If you want a host-native setup too, use a separate clone.

Manual setup

Prerequisites:

• Node.js (22.x recommended)
• Yarn (or use npm)
• PostgreSQL 17 with PostGIS

1. Clone the repository

    git clone https://github.com/unisdr/delta.git
    cd delta

2. Install dependencies

yarn install

3. Copy example env and configure

cp example.env .env
# edit .env and set DATABASE_URL, SESSION_SECRET, EMAIL config, etc.

4. Apply database schema (drizzle)

yarn run dbsync

This migration step updates the database schema from its current version to the latest version defined by the app's Drizzle migrations. In practice, it creates or alters tables, columns, indexes, and related database objects so the running application and the database structure match.

5. Run in development mode

yarn run dev

Open http://localhost:3000.

Follow this full guide or continue with the admin setup.

Windows & VS Code Setup

DELTA runs on Windows but requires a few additional setup steps due to Node.js and database tooling differences.

Prerequisites on Windows

• Node.js 22.x: Download from nodejs.org. Installer includes npm but we use yarn.
• PostgreSQL 17 with PostGIS:
  • Download PostgreSQL installer from postgresql.org
  • During installation, choose PostGIS in the "Additional Packages" step (or install via Stack Builder after PostgreSQL is installed)
  • Note the password you set for the postgres user
  • Add PostgreSQL bin/ folder to your system PATH so psql, pg_dump, and other tools are available in PowerShell
• Yarn: Install globally via npm:

  npm install -g yarn

Initial Setup on Windows

After cloning the repo:

# 1. Install dependencies (do NOT use pnpm — DELTA uses yarn only)
yarn install

# 2. Copy and configure environment
copy example.env .env

# 3. Edit .env with Windows paths for DATABASE_URL and EMAIL_TRANSPORT
# Example DATABASE_URL for local PostgreSQL:
# DATABASE_URL="postgresql://postgres:YOUR_PASSWORD@localhost:5432/delta?schema=public"

# 4. Create the database and enable PostGIS
psql -U postgres -c "CREATE DATABASE delta;"
psql -U postgres -d delta -c "CREATE EXTENSION postgis;"

# 5. Apply migrations
yarn run dbsync

# 6. Start dev server
yarn run dev

VS Code Configuration

Add these settings to your .vscode/settings.json (or create it if it doesn't exist):

{
	"editor.defaultFormatter": "esbenp.prettier-vscode",
	"editor.formatOnSave": true,
	"[typescript]": {
		"editor.defaultFormatter": "esbenp.prettier-vscode"
	},
	"[typescriptreact]": {
		"editor.defaultFormatter": "esbenp.prettier-vscode"
	},
	"editor.tabSize": 2,
	"editor.insertSpaces": false,
	"[json]": {
		"editor.insertSpaces": true
	},
	"search.exclude": {
		"**/node_modules": true,
		"**/build": true,
		"**/.git": true
	}
}

Common Issues on Windows

Issue: pnpm warnings after running yarn install

If you see warnings like "Moving @electric-sql/pglite that was installed by a different package manager", this is residual from pnpm. Clean and reinstall:

# from the repo root
if (Test-Path node_modules) { Remove-Item -Recurse -Force node_modules }
if (Test-Path package-lock.json) { Remove-Item -Force package-lock.json }
if (Test-Path pnpm-lock.yaml) { Remove-Item -Force pnpm-lock.yaml }
yarn install

Issue: Vitest extension error Cannot find module @rollup/rollup-win32-x64-msvc

This usually means node_modules contains the wrong optional Rollup binary for your platform (often after installs done by another package manager or from a different OS).

# from the repo root
if (Test-Path node_modules) { Remove-Item -Recurse -Force node_modules }
yarn install

Then reload VS Code so the Vitest extension respawns with the repaired dependencies.

Issue: psql not found

PostgreSQL bin/ folder is not in your PATH. Add it manually:

1. Find your PostgreSQL installation (usually C:\Program Files\PostgreSQL\17\bin)
2. Right-click This PC → Properties → Advanced system settings → Environment Variables
3. Under "System variables", find or create PATH
4. Add the PostgreSQL bin/ folder path
5. Restart PowerShell

Issue: Permission denied on yarn run dev

PowerShell execution policy may be blocking scripts. Run:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Issue: Database connection fails

Check your DATABASE_URL in .env:

• Use localhost (not 127.0.0.1 on some systems)
• Verify the password matches what you set during PostgreSQL installation
• Ensure the delta database exists: psql -U postgres -l
• Test the connection: psql -U postgres -d delta -c "\dt"

Troubleshooting TypeScript in VS Code

If TypeScript intellisense is not working:

1. Open the Command Palette (Ctrl+Shift+P)
2. Type "TypeScript: Restart TS Server" and press Enter
3. If still broken, run: yarn run tsc to check for compilation errors

Environment variables

Copy example.env to .env and update values. Key variables:

• DATABASE_URL (required): Postgres connection string. Example: postgresql://user:pass@localhost:5432/dts?schema=public
• SESSION_SECRET (required): long random string for session signing
• PUBLIC_URL: base URL of the application (used in emails, links)
• NODE_ENV: development or production
• EMAIL_TRANSPORT: smtp or file (file is useful for dev)
• EMAIL_FROM: default sender address for outgoing emails
• SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_SECURE: SMTP settings when EMAIL_TRANSPORT=smtp
• AUTHENTICATION_SUPPORTED: form, sso_azure_b2c, or comma-separated values
• SSO_AZURE_B2C_*: configuration for Azure B2C SSO when used Security notes:
• Never commit .env to source control. Use a secrets manager for production.

Database

• Uses PostgreSQL 17 with PostGIS. Create your DB and enable PostGIS extensions before applying migrations.
• Apply migrations using drizzle-kit: yarn dbsync.
• A migration moves the database schema from the current applied migration state to the latest one tracked in app/drizzle/.
• Migrations change schema, not your source data format. They are used when the app's database structure has evolved and the database must be brought up to date.
• Backup and restore: use pg_dump/pg_restore for database backups; ensure PostGIS types are preserved.

Testing

The project has three test layers:

• Unit + integration tests (Vitest with PGlite in-memory DB):

yarn test:run2

• Real-DB integration tests (Vitest against a live PostgreSQL instance):

cp example.env.test .env.test
# configure .env.test with a test database URL
yarn test:run3

• End-to-end tests (Playwright, runs the full app on port 4000):

yarn test:e2e

Useful commands

• Install dependencies: yarn install
• Run dev: yarn run dev
• Apply migrations: yarn run dbsync
• Run unit/integration tests: yarn test:run2
• Run E2E tests: yarn test:e2e
• Build production artifact: yarn run build

Production deployment (recommendations)

• Use a managed Postgres (RDS, Cloud SQL, Azure DB) or a highly available Postgres cluster
• Use Docker or Kubernetes for deployment. Store secrets in a vault or orchestrator secrets store
• Terminate TLS at the load balancer / ingress and enable secure cookies and HSTS
• Configure monitoring (logs, metrics, Sentry for errors)
• Use a CDN for static assets if serving at scale

Minimal production checklist:

• Strong SESSION_SECRET and secure storage of DB credentials
• HTTPS enabled
• Backups and monitoring configured

Security & secrets

• Set SESSION_SECRET to a secure, randomly generated value
• Use environment-based secret management (Vault, cloud secrets manager)
• Validate and sanitize uploads; enforce limits on attachment sizes
• Change the default password

Contributing

See CONTRIBUTING.md for branch naming, commit style, and PR conventions. Full developer documentation is in _docs/ — start there for architecture guides, code conventions, and feature-specific references.

Acknowledgements

DELTA Resilience is built with and supported by the following open-source and OSS-sponsored tools:

Tool	Area	Notes
CodeRabbit	Code review	AI-assisted PR reviews, free for open-source projects
GitHub	Source control & CI/CD	Source control, Actions, and GHCR free for public repositories
BrowserStack	Cross-browser testing	Cross-browser testing via open-source sponsorship