Docs/add docs and website

.development/.dockerignore

@@ -0,0 +1,62 @@
+# ==============================================================================
+# .dockerignore - Excludes files from Docker build context
+# ==============================================================================
+# This file prevents unnecessary files from being sent to Docker daemon
+# during image builds, speeding up the build process and reducing image size.
+#
+# Note: Source code is bind-mounted at runtime, not copied during build,
+# so this primarily affects base image creation.
+# ==============================================================================
+
+# Version control
+.git
+.gitignore
+
+# Dependencies (installed in container at runtime)
+node_modules
+**/node_modules
+
+# Build outputs (generated in container)
+build
+**/build
+dist
+**/dist
+*.tsbuildinfo
+
+# Environment files (mounted separately per service)
+# Exclude all .env files except development ones
+.env
+.env.*
+packages/**/.env
+packages/**/.env.*
+
+# Keep development environment files (needed for Docker builds)
+!.development/packages/**/.env
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+pnpm-debug.log*
+
+# IDE and editor files
+.vscode
+.idea
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+coverage
+.nyc_output
+
+# Misc
+.cache
+*.tgz
+.npmrc
+.continue
+
+# Keep .development folder (needed for entrypoint scripts)
+!.development

.development/.gitignore

@@ -0,0 +1,17 @@
+# ==============================================================================
+# .gitignore - Keep only source files in Git
+# ==============================================================================
+# This configuration ensures only configuration files are tracked.
+# Runtime files and generated content stay in Docker volumes.
+# ==============================================================================
+
+# Ignore all files by default
+!*
+
+# Track only these specific patterns:
+# - .env files (development environment variables)
+# - Dockerfiles (service image definitions)
+# - entrypoint.sh scripts (container startup scripts)
+# - compose.yml (docker compose configuration)
+# - .dockerignore (build context exclusions)
+# - .gitignore (this file)

.development/README.md

@@ -0,0 +1,153 @@
+# Development Environment
+
+Docker-based development environment for the Arrhes platform.
+
+## Architecture
+
+```
+.development/
+├── compose.yml              # Main Docker Compose configuration
+├── .dockerignore            # Build context exclusions
+├── .gitignore               # Git tracking rules
+└── packages/
+    ├── api/
+    │   ├── Dockerfile       # API service image
+    │   ├── entrypoint.sh    # API startup script
+    │   └── .env             # API environment variables
+    ├── dashboard/
+    │   ├── Dockerfile       # Dashboard service image
+    │   ├── entrypoint.sh    # Dashboard startup script
+    │   └── .env             # Dashboard environment variables
+    ├── tools/
+    │   └── .env             # Tools environment variables
+    └── website/
+        ├── Dockerfile       # Website service image
+        ├── entrypoint.sh    # Website startup script
+        └── .env             # Website environment variables
+```
+
+## Key Concepts
+
+### Source Code Binding
+- **Source files** (packages/) are bind-mounted from host to container
+- Changes made on **either host or container** are instantly synced
+- Enables live editing with IDE on host and HMR in container
+
+### Runtime Isolation
+- **node_modules** stored in Docker volumes (not on host)
+- **Build outputs** stored in Docker volumes
+- Keeps host clean and ensures consistent dependencies
+
+### Services
+
+**Infrastructure:**
+- PostgreSQL (port 5432) - Database
+- RustFS (ports 9000, 9001) - S3-compatible storage
+- Mailpit (ports 1025, 8025) - SMTP server with web UI
+
+**Applications:**
+- API (port 3000) - Hono backend
+- Dashboard (port 5173) - React admin interface
+- Website (port 5174) - React public site
+
+## Usage
+
+### Start all services
+```bash
+# Create required volumes first
+docker volume create arrhes_postgres_data
+docker volume create arrhes_rustfs_data
+
+# Start services
+docker compose -f .development/compose.yml up -d
+```
+
+### View logs
+```bash
+# All services
+docker compose -f .development/compose.yml logs -f
+
+# Specific service
+docker compose -f .development/compose.yml logs -f api
+```
+
+### Stop services
+```bash
+docker compose -f .development/compose.yml down
+```
+
+### Rebuild after changes
+```bash
+# Rebuild specific service
+docker compose -f .development/compose.yml build api
+
+# Rebuild and restart
+docker compose -f .development/compose.yml up -d --build api
+```
+
+### Access running containers
+```bash
+docker compose -f .development/compose.yml exec api bash
+```
+
+## Environment Files
+
+Each service has its own `.env` file in `.development/packages/{service}/.env`:
+
+- **api/.env** - API configuration (database, storage, email)
+- **dashboard/.env** - Dashboard configuration (API URL)
+- **website/.env** - Website configuration (API URL)
+- **tools/.env** - Database tools configuration
+
+These files are bind-mounted into containers at runtime.
+
+## How It Works
+
+1. **Build Phase:**
+   - Dockerfiles create minimal base images with Node.js + PNPM
+   - No source code or dependencies copied during build
+   - Images are lightweight and reusable
+
+2. **Runtime Phase:**
+   - Source code bind-mounted from `../packages` to `/workspace/packages`
+   - node_modules stored in named volumes (isolated per service)
+   - Entrypoint scripts install dependencies and start dev servers
+
+3. **Development:**
+   - Edit code on host with your IDE
+   - Changes instantly reflected in container
+   - Vite HMR updates browser automatically
+   - No manual restarts needed
+
+## Troubleshooting
+
+### Port already in use
+```bash
+# Check what's using the port
+lsof -i :3000
+
+# Stop the conflicting service or change port in compose.yml
+```
+
+### Dependencies not updating
+```bash
+# Remove volume and rebuild
+docker volume rm .dev_api_node_modules
+docker compose -f .development/compose.yml up -d --build api
+```
+
+### Database reset
+```bash
+# Remove database volume (WARNING: deletes all data)
+docker compose -f .development/compose.yml down
+docker volume rm arrhes_postgres_data
+docker volume create arrhes_postgres_data
+docker compose -f .development/compose.yml up -d
+```
+
+### Clean slate
+```bash
+# Remove all containers, volumes (except external), and rebuild
+docker compose -f .development/compose.yml down -v
+docker compose -f .development/compose.yml up -d --build
+```

.development/compose.yml

@@ -0,0 +1,151 @@
+# ==============================================================================
+# Arrhes Platform - Development Environment
+# ==============================================================================
+# Docker Compose configuration for local development
+#
+# Architecture:
+# - Source code: bind-mounted from host (live editing on both host and container)
+# - Runtime files: isolated in Docker volumes (node_modules, build outputs)
+# - Infrastructure: PostgreSQL, RustFS (S3), Mailpit (SMTP)
+# - Services: API, Dashboard, Website
+#
+# Usage:
+#   docker compose -f .development/compose.yml up -d     # Start all services
+#   docker compose -f .development/compose.yml down      # Stop all services
+#   docker compose -f .development/compose.yml logs -f   # View logs
+# ==============================================================================
+
+services:
+  # ============================================================================
+  # Infrastructure Services
+  # ============================================================================
+
+  # PostgreSQL - Relational database for application data
+  postgres:
+    image: postgres:18.1
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: admin
+      POSTGRES_DB: default
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d default"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  # RustFS - S3-compatible object storage for attachments/files
+  rustfs:
+    image: rustfs/rustfs:latest
+    restart: unless-stopped
+    environment:
+      RUSTFS_CONSOLE_ENABLE: true
+      RUSTFS_ACCESS_KEY: rustfsadmin
+      RUSTFS_SECRET_KEY: rustfsadmin
+      RUSTFS_VOLUMES: /data
+    ports:
+      - "9000:9000"  # API
+      - "9001:9001"  # Web Console
+    volumes:
+      - rustfs_data:/data
+    init: true
+    healthcheck:
+      test: ["CMD-SHELL", "wget --quiet --tries=1 --spider http://localhost:9000 2>&1 | grep -q '403 Forbidden' && exit 0 || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  # Mailpit - Development SMTP server with web interface
+  mailpit:
+    image: axllent/mailpit:latest
+    restart: unless-stopped
+    ports:
+      - "1025:1025"  # SMTP
+      - "8025:8025"  # Web UI
+    healthcheck:
+      test: ["CMD-SHELL", "wget --quiet --tries=1 --spider http://localhost:8025 || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  # ============================================================================
+  # Application Services
+  # ============================================================================
+
+  # API - Backend service (Hono framework on Node.js)
+  api:
+    build:
+      context: ..
+      dockerfile: .development/packages/api/Dockerfile
+      args:
+        NODE_VERSION: "25.2.1"
+        PNPM_VERSION: "10.26.1"
+    ports:
+      - "3000:3000"  # API server
+    volumes:
+      # Source code - bind-mounted for live editing (synced between host and container)
+      - ../packages:/workspace/packages:cached
+      - ../package.json:/workspace/package.json:cached
+      - ../pnpm-workspace.yaml:/workspace/pnpm-workspace.yaml:cached
+      - ../pnpm-lock.yaml:/workspace/pnpm-lock.yaml:cached
+      - ../.development:/workspace/.development:cached
+
+      # Environment files - use .development versions
+      - ./packages/api/.env:/workspace/packages/api/.env:cached
+      - ./packages/tools/.env:/workspace/packages/tools/.env:cached
+
+      # Runtime files - isolated in Docker volumes (NOT on host)
+      - api_node_modules:/workspace/node_modules
+      - metadata_build:/workspace/packages/metadata/build
+      - pnpm_store:/root/.local/share/pnpm/store
+    depends_on:
+      postgres:
+        condition: service_healthy
+      rustfs:
+        condition: service_healthy
+      mailpit:
+        condition: service_healthy
+
+  # Dashboard - Frontend admin interface (React + Vite)
+  dashboard:
+    build:
+      context: ..
+      dockerfile: .development/packages/dashboard/Dockerfile
+      args:
+        NODE_VERSION: "25.2.1"
+        PNPM_VERSION: "10.26.1"
+    ports:
+      - "5173:5173"  # Vite dev server
+    volumes:
+      # Source code only - bind-mounted for live editing
+      # node_modules and metadata/build stay inside the image (installed at build time)
+      - ../packages/dashboard/src:/workspace/packages/dashboard/src:cached
+      - ../packages/dashboard/public:/workspace/packages/dashboard/public:cached
+      - ../packages/dashboard/vite.config.ts:/workspace/packages/dashboard/vite.config.ts:cached
+      - ../packages/dashboard/tsconfig.json:/workspace/packages/dashboard/tsconfig.json:cached
+      - ../packages/dashboard/panda.config.ts:/workspace/packages/dashboard/panda.config.ts:cached
+      # Shared UI package for live editing
+      - ../packages/ui/src:/workspace/packages/ui/src:cached
+      - ../packages/ui/tsconfig.json:/workspace/packages/ui/tsconfig.json:cached
+      - ../packages/ui/panda.config.ts:/workspace/packages/ui/panda.config.ts:cached
+
+# ==============================================================================
+# Named Volumes (Runtime data isolated from host)
+# ==============================================================================
+volumes:
+  # Application runtime dependencies - isolated per service
+  api_node_modules:
+
+  # Shared build output - metadata package used by multiple services
+  metadata_build:
+
+  # PNPM global store cache - shared across all Node services for efficiency
+  pnpm_store:
+
+  # Persistent infrastructure data - survives container restarts
+  postgres_data:
+  rustfs_data: