Adjust migrations doc

Author: bcb

docs/gettingstarted.md

@@ -93,6 +93,8 @@ SuperStack automatically:
 3. Launches PostgREST and Swagger UI
 4. Serves everything through Caddy
 
+> 💡 Only Caddy exposes a port – all services are routed through it.
+
 ## Change the Docker images to your own (Recommended)
 
 In `compose.yaml`, change the `explodinglabs` images to your own:

docs/index.md

@@ -42,6 +42,13 @@ It's perfect for:
 Everything runs inside Docker and routes through a single exposed port (via
 Caddy), making it easy to develop locally or deploy remotely.
 
+```mermaid
+flowchart TD
+    Caddy["Caddy (API Gateway)"]
+    Caddy --> Services["Services (PostgREST, Swagger UI + more)"]
+    Services --> Postgres
+```
+
 ---
 
 ## 📚 What's next?

docs/migrations.md

@@ -1,9 +1,27 @@
-# 📜 Migrations
+# Build your App
+
+## Project Structure
+
+```
+📁 bin/                  → Helper scripts (e.g. wrappers for CLI tools)
+📁 caddy/                → Custom Caddy configuration and certificates
+📁 docs/                 → Markdown files for SuperStack documentation
+📁 postgres/             → SQL migrations and configuration of the postgres container
+📄 compose.yaml          → Main Docker Compose config
+📄 compose.override.yaml → Optional local overrides (development only)
+📄 example.env           → Example environment variables — copy to `.env`
+📄 LICENSE               → License file (MIT)
+📄 logo.png              → SuperStack logo for README/docs
+📄 mkdocs.yml            → MkDocs configuration for documentation site
+📄 README.md             → Overview and quick start for the repository
+```
+
+## 📜 Migrations
 
 SuperStack includes a simple built-in system for managing database schema
 migrations.
 
-## ✍️ Writing Migrations
+### ✍️ Writing Migrations
 
 Place your migration scripts in:
 
@@ -18,7 +36,7 @@ Each file should be:
 - Written in plain SQL
 - But can include environment variables.
 
-## ▶️ Applying Migrations
+### ▶️ Applying Migrations
 
 When the Postgres container starts with no existing data, SuperStack will
 automatically run migrations once.
@@ -41,18 +59,7 @@ Already-applied scripts are skipped on subsequent runs.
 
 > 💡 `bin/postgres` is short for `docker compose exec postgres`
 
-## 🔄 Resetting
-
-If you want to start fresh:
-
-```sh
-docker compose down --volumes
-docker compose up -d
-```
-
-This will wipe your database and re-run all migrations from scratch.
-
-## 🔁 Transactions
+### 🔁 Transactions
 
 Use `BEGIN;` and `COMMIT;` to wrap migration files when all included
 statements are transactional. This ensures that all changes are applied
@@ -101,3 +108,13 @@ ALTER SYSTEM
 DISCARD ALL
 LOAD
 ```
+
+### 🔄 Nuke Everything
+
+If you want to start fresh, wipe your database and re-run all migrations from
+scratch:
+
+```sh
+docker compose down --volumes
+docker compose up -d
+```