From 8949a33481b2838f4f53f229f6e425c5d4f327b5 Mon Sep 17 00:00:00 2001
From: Julien Gautier <jgautier.webdev@gmail.com>
Date: Wed, 29 Apr 2026 00:53:58 +0200
Subject: [PATCH] docs: add CLAUDE.md with project guidance for AI assistants

---
 CLAUDE.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..8c93a3f
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,64 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+A collection of standalone Bash utility scripts for MongoDB operations (backup, restore, local dev environment). No build system, package manager, or test suite — each module is a self-contained shell script.
+
+## Modules
+
+| Module | Script | Purpose |
+|---|---|---|
+| `dbdump_mongo/` | `db-dump.sh` | Dump MongoDB databases across multiple named environments |
+| `dbrestore_mongo/` | `db-restore.sh` | Restore a MongoDB dump to a target instance |
+| `dbutils_mongo/` | `db-start.sh` | Spin up a local MongoDB + Mongo Express via Docker |
+
+## Running the Scripts
+
+```bash
+# Backup — interactive environment picker
+cd dbdump_mongo && bash db-dump.sh
+
+# Restore — interactive backup directory navigator
+cd dbrestore_mongo && bash db-restore.sh
+
+# Local dev database — Docker-based
+cd dbutils_mongo && bash db-start.sh up       # start
+cd dbutils_mongo && bash db-start.sh down      # stop
+cd dbutils_mongo && bash db-start.sh status
+cd dbutils_mongo && bash db-start.sh logs
+cd dbutils_mongo && bash db-start.sh clean     # remove volumes
+cd dbutils_mongo && bash db-start.sh reconfigure
+```
+
+## Environment Setup
+
+Each module requires a `.env` file (copied from the corresponding `.env.example`). The `.env` files are git-ignored. `dbdump_mongo` supports multiple named environments stored as `.env.<name>` files with `chmod 600` permissions.
+
+## Architecture Patterns
+
+All three scripts share the same conventions:
+
+- **Sub-command dispatch**: a `main()` function routes `$1` to `cmd_<action>()` functions.
+- **Colored output**: ANSI escape codes (`\033[...m`) for styled terminal output; consistent separator lines.
+- **Prerequisite checks**: each script validates its required tools (`mongodump`, `mongorestore`, `docker`, `docker compose`) at startup and exits early with a clear message if missing.
+- **Interactive prompts**: `read -p` / `select` menus guide the user through environment selection, directory navigation, and confirmation steps before any destructive action.
+
+### dbdump_mongo — multi-environment credential model
+
+Named environments are stored as `.env.<name>` files alongside the main `.env`. Credentials include `MONGO_USERNAME`, `MONGO_PASSWORD`, `MONGO_HOST`, `MONGO_PORT`, `APP_NAME`. Dumps land in `./dumps/<appName>/<yyyymmdd_hhmm>/`. The script generates MongoDB Atlas-compatible connection strings (ssl, replicaSet flags).
+
+### dbrestore_mongo — backup directory navigation
+
+The script walks through backup directory hierarchies interactively. It detects valid restore targets by checking for `.bson` files (`has_bson_files()`). Before executing `mongorestore`, it shows a summary of connection details and the selected backup path and requires explicit confirmation.
+
+### dbutils_mongo — Docker Compose orchestration
+
+Runs two containers on a `dbutils-network` bridge: MongoDB (configurable port, default `MONGO_PORT`) and Mongo Express (default port `8081`). Data is persisted in named volumes `mongodb-data` and `mongodb-config`. On first run, `setup_credentials()` prompts interactively and writes `.env`. The `mongo-init.js` initializer creates a `dataImportHistory` collection with indexes on `importDate` and `status`.
+
+## External Dependencies
+
+- `mongodump` / `mongorestore` — MongoDB Database Tools (must be installed separately)
+- `docker` + `docker compose` (v2 plugin syntax)
+- `bash` (scripts use `bash`-specific features, not POSIX `sh`)