docs: expand README with architecture and roadmap

README.md

@@ -1,30 +1,56 @@
 <p align="center">
-  <img src="images/dockervault-logo.png" alt="DockerVault logo" width="400">
+  <img src="images/dockervault-logo.png" alt="DockerVault logo" width="840">
 </p>
 
-🚀 What is DockerVault?
+<p align="center">
-
+  <b>Simple, reliable backups for Docker environments.</b>
-DockerVault is a lightweight backup system designed to make Docker backups simple, transparent, and predictable.
+</p>
-
-It helps you:
-
-* Discover Docker containers automatically
-* Backup volumes, bind mounts, and configurations
-* Keep track of backup history
-* Restore data safely when needed
-
-Built for homelabs and small-scale infrastructure.
 
 ---
 
-## ✨ Features (planned)
+## 🚀 What is DockerVault?
 
-* 🔍 Auto-discovery of Docker containers
+DockerVault is a CLI-first backup system for Docker environments.
-* 💾 Backup of volumes and bind mounts
+
-* 🧠 Smart selection of what to back up
+It is designed to make backups simple, transparent, and reliable without unnecessary complexity. The goal is to provide a practical way to discover containers, identify important data, and manage backups in a structured and predictable way.
-* 📦 Incremental backups (future)
+
-* 🔁 Restore system
+DockerVault is aimed at homelabs, self-hosted infrastructure, and small-scale server environments where control, clarity, and recoverability matter.
-* 🖥 Multi-node support (future)
+
+---
+
+## ✨ Goals
+
+DockerVault is being built to:
+
+- Discover Docker containers automatically
+- Identify volumes, bind mounts, and relevant configuration data
+- Keep track of backup history and metadata
+- Use a proven backup backend instead of reinventing backup logic
+- Make restore operations easier and safer
+- Stay simple enough to understand and debug
+
+---
+
+## ⚙️ Technology
+
+DockerVault is planned as a modular, CLI-first tool.
+
+### Current design direction
+
+- **Core language:** Python
+- **Backup engine:** BorgBackup
+- **Metadata storage:** SQLite
+- **Interface:** CLI first
+- **Platform focus:** Linux Docker hosts
+
+### Why this stack?
+
+- **Python** makes it fast to build, maintain, and extend
+- **BorgBackup** is mature, reliable, and well-suited for deduplicated backups
+- **SQLite** keeps metadata simple, local, and easy to inspect
+- **CLI first** keeps the project transparent and easy to debug
+
+The project philosophy is clear: use proven tools where it makes sense, and avoid building complexity just for the sake of it.
 
 ---
 
@@ -33,65 +59,124 @@ Built for homelabs and small-scale infrastructure.
 DockerVault follows a simple flow:
 
 1. Scan Docker environment
-2. Identify containers, volumes, and mounts
+2. Detect containers, volumes, bind mounts, and configs
-3. Store metadata (SQLite)
+3. Store metadata in SQLite
-4. Execute backups
+4. Build backup jobs from discovered data
-5. Restore when needed
+5. Execute backups through Borg
+6. Restore data when needed
 
-More details: `docs/architecture.md`
+More detailed architecture notes will live in `docs/architecture.md`.
 
 ---
 
-## ⚡ Quick Start (coming soon)
+## 📦 What DockerVault is expected to back up
 
-```bash
+DockerVault is intended to focus on the parts of Docker environments that actually matter:
-git clone git@git.lanx.dk:ed/dockervault.git
-cd dockervault
 
-# planned commands
+- Docker volumes
-dockervault init
+- Bind mounts
-dockervault scan
+- Selected configuration files
-dockervault backup
+- Backup metadata
-```
+- Restore-related information
+
+It is not intended to blindly copy everything without structure. The purpose is to know what is being backed up and why.
+
+---
+
+## 🔁 Restore philosophy
+
+Backups are only useful if restore is realistic.
+
+DockerVault is being designed with restore in mind from the beginning:
+
+- Clear mapping between containers and stored data
+- Metadata that explains what belongs to what
+- Predictable restore flow
+- Minimal guesswork during recovery
+
+The long-term goal is not just to create archives, but to support actual recovery when needed.
+
+---
+
+## 🧩 Planned Features
+
+### Core features
+
+- Docker container discovery
+- Volume detection
+- Bind mount detection
+- Backup job creation
+- Borg-based backup execution
+- SQLite-based metadata tracking
+- Restore workflow
+
+### Future possibilities
+
+- Scheduled backups
+- Retention policies
+- Pre-backup and post-backup hooks
+- E-mail notifications
+- `ntfy` notifications
+- Web interface
+- Multi-node support
+- Remote repository support
+- Backup health/status reporting
+- Configuration profiles
+- Selective backup policies per container
+
+---
+
+## 🛣 Roadmap
+
+### Phase 1 – Foundation
+- Repository structure
+- Documentation
+- CLI skeleton
+- Initial project design
+
+### Phase 2 – Discovery
+- Scan Docker environment
+- Detect containers
+- Detect volumes and bind mounts
+
+### Phase 3 – Backup Engine
+- Integrate BorgBackup
+- Build backup job flow
+- Store metadata in SQLite
+
+### Phase 4 – Restore
+- Basic restore workflow
+- Restore metadata mapping
+- Safer recovery process
+
+### Phase 5 – Usability
+- Better CLI commands
+- Config handling
+- Scheduling support
+- Notifications
+
+### Phase 6 – Expansion
+- Web interface
+- Multi-node support
+- More advanced backup policies
 
 ---
 
 ## 📁 Project Structure
 
-```
+Planned structure:
+
+```text
 dockervault/
-├── cmd/
+├── cmd/          # CLI commands
-├── core/
+├── core/         # core logic
-├── scanner/
+├── scanner/      # Docker discovery
-├── backup/
+├── backup/       # backup engine integration
-├── restore/
+├── restore/      # restore logic
-├── config/
+├── config/       # configuration handling
-├── database/
+├── database/     # SQLite handling
-├── docs/
+├── docs/         # project documentation
-└── scripts/
+├── scripts/      # helper scripts
-```
+├── images/       # logos and visual assets
-
+├── README.md
----
+└── LICENSE
-
-## 🧩 Roadmap
-
-See `docs/roadmap.md`
-
----
-
-## 🤝 Philosophy
-
-DockerVault is built on a few simple principles:
-
-* Keep it simple
-* Be transparent
-* Avoid unnecessary complexity
-* Build something we actually want to use
-
-No magic. No hidden behavior.
-
----
-
-## 📜 License
-
-GNU General Public License v2.0