(feat): Documentation Updated, email demo, better local metrics

Dockerfile

@@ -20,7 +20,7 @@ RUN mkdir -p pb_public
 RUN CGO_ENABLED=1 GOOS=linux go build -a -installsuffix cgo -o main ./cmd/server
 
 # Final stage
-FROM alpine:latest
+FROM alpine:latest AS production
 
 # Install ca-certificates for HTTPS requests
 RUN apk --no-cache add ca-certificates tzdata
@@ -39,6 +39,12 @@ RUN if [ -d /app/pb_public ] && [ "$(ls -A /app/pb_public 2>/dev/null)" ]; then
 # Copy schema files for migrations
 COPY --from=builder /app/internal ./internal
 
+# Copy monitoring configurations
+COPY --from=builder /app/monitoring ./monitoring
+
+# Copy email templates
+COPY --from=builder /app/templates ./templates
+
 # Create pb_data directory
 RUN mkdir -p pb_data
 

README.md

@@ -1,6 +1,6 @@
 # IMS PocketBase BaaS Starter
 
-A Backend-as-a-Service (BaaS) starter kit built with PocketBase Go framework, enabling custom API routes, business logic, and middleware alongside PocketBase's built-in features. Includes Role-Based Access Control (RBAC), environment-based configuration, and development tools.
+A production-ready Backend-as-a-Service (BaaS) starter kit that extends PocketBase's Go framework with enterprise-grade features. Combines PocketBase's real-time database, authentication, and file storage with custom business logic, advanced middleware, and comprehensive observability. Designed for rapid development with built-in RBAC, job processing, caching, and monitoring capabilities.
 
 ## Features
 
@@ -68,57 +68,32 @@ A Backend-as-a-Service (BaaS) starter kit built with PocketBase Go framework, en
 - Email: `superadmin@ims.com`
 - Password: `superadmin123456`
 
-## Makefile Commands
+## Configuration
 
-| Development                              | Production                                    | Utility                                  |
-| ---------------------------------------- | --------------------------------------------- | ---------------------------------------- |
-| `dev` - Start dev environment            | `build` - Build production image              | `help` - Show all commands               |
-| `dev-build` - Build dev image            | `start` - Start containers                    | `generate-key` - Generate encryption key |
-| `dev-logs` - Show dev logs               | `stop` - Stop containers                      | `setup-env` - Setup environment file     |
-| `dev-stop` - Stop dev containers         | `restart` - Restart containers                | `test` - Run tests                       |
-| `dev-clean` - Clean dev env              | `down` - Stop and remove containers           | `lint` - Run linter                      |
-| `dev-data-clean` - Clean dev data        | `logs` - Show container logs                  | `format` - Format Go code                |
-| `dev-start` - Alias for dev              | `clean` - Remove containers, networks, images | `status` - Show container status         |
-| `dev-status` - Show dev container status | `clean-data` - Remove only volumes            | `prod-start` - Alias for start           |
+The application uses environment variables for configuration. Copy `env.example` to `.env` and update the values:
 
-## Environment Configuration
-
-Copy `env.example` to `.env` and configure the following:
-
-### App Configuration
-
-- `APP_NAME` - Application name
-- `APP_URL` - Application URL
-
-### Job processing settings
-
-- `JOB_MAX_WORKERS` - Concurrent workers (default: 5)
-- `JOB_BATCH_SIZE` - Jobs per cron run (default: 50)
-- `JOB_MAX_RETRIES` - Maximum retry attempts (default: 3)
-- `ENABLE_SYSTEM_QUEUE_CRON` - Enable queue processing (default: true)
-
-### SMTP Configuration (for email)
+```bash
+make setup-env
+make generate-key  # Generate encryption key
+# Edit .env file with your configuration
+```
 
-- `SMTP_ENABLED` - Enable/disable SMTP
-- `SMTP_HOST` - SMTP server host
-- `SMTP_PORT` - SMTP server port
-- `SMTP_USERNAME` - SMTP username
-- `SMTP_PASSWORD` - SMTP password
-- `SMTP_AUTH_METHOD` - Authentication method
-- `SMTP_TLS` - Enable TLS
+Key configuration areas include app settings, SMTP/email, S3 storage, job processing, rate limiting, and security. For complete configuration details, see the [Environment Configuration Guide](docs/environment-configuration.md).
 
-### S3 Configuration (for file storage)
+## Available Commands
 
-- `S3_ENABLED` - Enable/disable S3
-- `S3_BUCKET` - S3 bucket name
-- `S3_REGION` - S3 region
-- `S3_ENDPOINT` - S3 endpoint
-- `S3_ACCESS_KEY` - S3 access key
-- `S3_SECRET` - S3 secret key
+The project includes comprehensive Makefile commands for development and production:
 
-### Security
+```bash
+make dev          # Start development environment
+make dev-logs     # View development logs
+make build        # Build production image
+make start        # Start production containers
+make test         # Run tests
+make help         # Show all commands
+```
 
-- `PB_ENCRYPTION_KEY` - PocketBase encryption key (32 characters)
+For a complete list of commands and usage examples, see the [Makefile Commands Guide](docs/makefile-commands.md).
 
 ## Development Workflow
 
@@ -142,137 +117,30 @@ Copy `env.example` to `.env` and configure the following:
    - API Documentation (ReDoc): http://localhost:8090/api-docs/redoc
    - OpenAPI JSON: http://localhost:8090/api-docs/openapi.json
    - MailHog Web UI: http://localhost:8025
+   - Grafana Dashboard: http://localhost:3000 (admin/admin)
+   - Prometheus Metrics: http://localhost:9090
 
-## Database
-
-The application includes:
-
-- **Migrations** - Database schema setup
-- **Seeders** - Initial data seeding (RBAC, super admin)
-- **Collections** - User management, roles, permissions
-
-For detailed information about database migrations and schema management, see the [Database Migrations Guide](docs/migrations.md).
-
-## API Documentation
-
-The application automatically generates comprehensive API documentation for all collections and custom routes:
-
-- **Swagger UI** - Interactive API explorer at `http://localhost:8090/api-docs`
-- **ReDoc** - Clean documentation interface at `http://localhost:8090/api-docs/redoc`
-- **OpenAPI JSON** - Machine-readable spec at `http://localhost:8090/api-docs/openapi.json`
-- **Postman Compatible** - Import OpenAPI JSON directly into Postman/Insomnia
-
-**Features:**
-
-- Auto-discovery of all PocketBase collections
-- Complete CRUD operation documentation
-- Authentication flow documentation
-- File upload support with multipart forms
-- Custom route integration
-- Example data generation
-
-For detailed information about the Swagger system, configuration, and usage, see the [Swagger Documentation Guide](docs/swagger.md).
-
-## Cron Jobs & Job Queue System
-
-The application includes a comprehensive background task processing system with:
+## Key Features
 
-- **Cron Jobs** - Scheduled tasks with environment-based control
-- **Job Queue** - Dynamic job processing with concurrent workers
-- **Built-in Handlers** - Email jobs, data processing jobs
-- **Extensible Architecture** - Easy to add custom job types
+- **Database** - Migrations, seeders, and RBAC collections. See [Database Guide](docs/migrations.md)
+- **API Documentation** - Auto-generated Swagger UI, ReDoc, and OpenAPI JSON. See [Swagger Guide](docs/swagger.md)
+- **Background Jobs** - Cron jobs and job queue system. See [Jobs Guide](docs/cron-jobs.md)
+- **Event Hooks** - Comprehensive hook system for extending functionality. See [Hooks Guide](docs/hooks.md)
+- **Caching** - High-performance TTL cache system. See [Caching Guide](docs/caching.md)
+- **Metrics & Observability** - Prometheus metrics and OpenTelemetry support. See [Metrics Guide](docs/metrics.md)
+- **Migration CLI** - Generate migrations with `make migrate-gen name=your_migration`
 
-For detailed information about cron jobs, job queue system, and creating custom handlers, see the [Cron Jobs & Job Queue Guide](docs/cron-jobs.md).
-
-## Event Hooks System
-
-The application includes a comprehensive event hook system that allows you to extend PocketBase functionality through organized event handlers:
-
-- **Record Hooks** - Handle record creation, updates, and deletions
-- **Collection Hooks** - Manage collection lifecycle events
-- **Request Hooks** - Intercept API requests for custom logic
-- **Mailer Hooks** - Customize email sending behavior
-- **Realtime Hooks** - Handle WebSocket connections and messages
-- **Organized Structure** - Clean separation of concerns with dedicated handler files
-- **Example Implementations** - Ready-to-use examples for common use cases like audit logging, user settings creation, and data validation
-
-**Key Features:**
-
-- Collection-specific hooks for targeted functionality
-- Comprehensive error handling and logging
-- Easy registration and management
-- Extensible architecture for custom business logic
-
-For detailed information about the hooks system, available events, and creating custom handlers, see the [Event Hooks Guide](docs/hooks.md).
-
-## Caching System
-
-The application features a high-performance Go-based caching system with:
-
-- **TTL Support** - Automatic expiration of cached items
-- **Memory Efficient** - Optimized for performance and memory usage
-- **Thread Safe** - Concurrent access support
-- **Easy Integration** - Simple API for cache operations
-- **Configurable** - Customizable cache settings and cleanup intervals
-
-**Use Cases:**
-
-- API response caching
-- Database query result caching
-- Session data storage
-- Temporary data storage with automatic cleanup
-
-### Migration CLI Generator
-
-The project includes a CLI tool to generate migration files automatically:
-
-```bash
-make migrate-gen name=add_user_profiles
-```
+## Project Structure
 
-**Features:** Automatic sequential numbering, name sanitization, input validation, and helpful next-step guidance.
+This project follows Go project layout standards with clean architecture and modular design. The codebase is organized into:
 
-## Project Structure
+- **`cmd/`** - Application entry points (server, CLI tools)
+- **`internal/`** - Private application code (handlers, hooks, middleware)
+- **`pkg/`** - Reusable packages (cache, logger, metrics, utilities)
+- **`docs/`** - Comprehensive project documentation
+- **`monitoring/`** - Development and production monitoring configurations
 
-```
-├── cmd/
-│   ├── migrate-gen/     # Migration CLI generator
-│   └── server/          # Application entry point
-├── docs/                # Project documentation
-│   ├── README.md       # Documentation index
-│   ├── cron-jobs.md    # Cron jobs & job queue guide
-│   ├── middleware.md   # Custom middleware guide
-│   └── migrations.md   # Database migration guide
-├── internal/
-│   ├── app/            # Application setup and configuration
-│   ├── crons/          # Cron job definitions and registration
-│   ├── database/
-│   │   ├── migrations/ # Database migrations
-│   │   ├── schema/     # PocketBase schema files
-│   │   └── seeders/    # Data seeders (RBAC, admin, settings)
-│   ├── handlers/
-│   │   ├── cron/       # Cron job handlers
-│   │   ├── hook/       # Event hook handlers
-│   │   ├── jobs/       # Job queue handlers
-│   │   └── route/      # Custom route handlers
-│   ├── hooks/          # Event hook registration and management
-│   ├── jobs/           # Job processor management
-│   ├── middlewares/    # HTTP middlewares (auth, permissions)
-│   └── routes/         # Custom API route definitions
-├── pkg/
-│   ├── cronutils/      # Cron execution utilities
-│   ├── jobutils/       # Job processing utilities
-│   └── migration/      # Migration utilities and scanner
-├── pb_data/            # PocketBase data directory
-├── pb_public/          # PocketBase public assets
-├── .github/            # GitHub workflows and templates
-├── Dockerfile          # Production Dockerfile
-├── Dockerfile.dev      # Development Dockerfile
-├── docker-compose.yml  # Production compose
-├── docker-compose.dev.yml # Development compose
-├── Makefile           # Development commands
-└── .env.example       # Environment template
-```
+For detailed information about the complete project structure, package organization, architectural decisions, and navigation guidance, see the **[📁 docs/](docs/)** folder which contains comprehensive guides for all aspects of the project.
 
 ## Contributing
 

docker-compose.dev.yml

@@ -33,7 +33,7 @@ services:
     ports:
       - "9090:9090"
     volumes:
-      - ./docker/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
+      - ./monitoring/local/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
       - prometheus_data:/prometheus
     command:
       - '--config.file=/etc/prometheus/prometheus.yml'
@@ -51,8 +51,8 @@ services:
       - "3000:3000"
     volumes:
       - grafana_data:/var/lib/grafana
-      - ./docker/grafana/provisioning:/etc/grafana/provisioning
-      - ./docker/grafana/dashboards:/var/lib/grafana/dashboards
+      - ./monitoring/local/grafana/provisioning:/etc/grafana/provisioning
+      - ./monitoring/local/grafana/dashboards:/var/lib/grafana/dashboards
     environment:
       - GF_SECURITY_ADMIN_USER=admin
       - GF_SECURITY_ADMIN_PASSWORD=admin

docker-compose.monitoring.yml

@@ -0,0 +1,83 @@
+# Production Docker Compose for Monitoring Server
+# This runs Prometheus and Grafana on a separate server
+version: '3.8'
+
+services:
+  prometheus:
+    image: prom/prometheus:latest
+    ports:
+      - "9090:9090"
+    volumes:
+      - ./prometheus/prometheus.prod.yml:/etc/prometheus/prometheus.yml
+      - prometheus_data:/prometheus
+    command:
+      - '--config.file=/etc/prometheus/prometheus.yml'
+      - '--storage.tsdb.path=/prometheus'
+      - '--web.console.libraries=/etc/prometheus/console_libraries'
+      - '--web.console.templates=/etc/prometheus/consoles'
+      - '--storage.tsdb.retention.time=30d'  # Keep data for 30 days
+      - '--web.enable-lifecycle'
+      - '--web.enable-admin-api'
+    networks:
+      - monitoring-network
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:9090/-/healthy"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+  grafana:
+    image: grafana/grafana:latest
+    ports:
+      - "3000:3000"
+    volumes:
+      - grafana_data:/var/lib/grafana
+      - ./grafana/provisioning:/etc/grafana/provisioning
+      - ./grafana/dashboards:/var/lib/grafana/dashboards
+    environment:
+      # Production Grafana settings
+      - GF_SECURITY_ADMIN_USER=${GRAFANA_ADMIN_USER:-admin}
+      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_ADMIN_PASSWORD:-changeme}
+      - GF_USERS_ALLOW_SIGN_UP=false
+      - GF_SECURITY_ALLOW_EMBEDDING=true
+      - GF_AUTH_ANONYMOUS_ENABLED=false
+      - GF_INSTALL_PLUGINS=grafana-piechart-panel
+      # Security headers
+      - GF_SECURITY_COOKIE_SECURE=true
+      - GF_SECURITY_COOKIE_SAMESITE=strict
+    networks:
+      - monitoring-network
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:3000/api/health || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    depends_on:
+      - prometheus
+
+  # Optional: Add Alertmanager for alerts
+  alertmanager:
+    image: prom/alertmanager:latest
+    ports:
+      - "9093:9093"
+    volumes:
+      - ./alertmanager/alertmanager.yml:/etc/alertmanager/alertmanager.yml
+      - alertmanager_data:/alertmanager
+    command:
+      - '--config.file=/etc/alertmanager/alertmanager.yml'
+      - '--storage.path=/alertmanager'
+      - '--web.external-url=http://localhost:9093'
+    networks:
+      - monitoring-network
+    restart: unless-stopped
+
+volumes:
+  prometheus_data:
+  grafana_data:
+  alertmanager_data:
+
+networks:
+  monitoring-network:
+    driver: bridge