# 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`)