Skip to content

project-tree.md

Latest commit

 

History

History
320 lines (270 loc) · 13.5 KB

project-tree.md

File metadata and controls

320 lines (270 loc) · 13.5 KB

Project Structure Guide

This document provides a comprehensive overview of the IMS PocketBase BaaS Starter project structure, explaining the purpose and organization of each directory and key files.

Directory Structure Overview

ims-pocketbase-baas-starter/
├── 📁 cmd/                     # Application entry points
├── 📁 docs/                    # Project documentation
├── 📁 internal/                # Private application code
├── 📁 monitoring/              # Monitoring configurations (Prometheus, Grafana)
├── 📁 pb_data/                 # PocketBase data directory
├── 📁 pb_public/               # PocketBase public assets
├── 📁 pkg/                     # Reusable packages
├── 📁 scripts/                 # Build and setup scripts
├── 📁 templates/               # Template files (email templates, etc.)
├── 📁 tmp/                     # Temporary files (git ignored)
├── 🐳 Dockerfile               # Production container definition
├── 🐳 docker-compose.yml       # Production container orchestration
├── 🐹 go.mod                   # Go module definition
├── ⚙️ makefile                 # Development commands
└── 📄 README.md                # Main project documentation

Detailed Directory Breakdown

📁 cmd/ - Application Entry Points

Contains the main application executables following Go project layout standards.

cmd/
├── migrate-gen/          # Migration CLI generator
│   ├── main.go          # CLI entry point
│   ├── cli.go           # Command-line interface logic
│   ├── cli_test.go      # CLI tests
│   ├── template.go      # Migration template generation
│   ├── template_test.go # Template generation tests
│   └── types.go         # CLI-specific types
└── server/              # Main application server
    └── main.go          # Server entry point

Purpose: Separates different executable commands, making the project modular and following Go conventions.

📁 internal/ - Private Application Code

Contains application-specific code that should not be imported by other projects.

internal/
├── app/                 # Application setup and configuration
│   ├── app.go          # Main app initialization and DI orchestration
│   └── app_test.go     # Application setup tests
├── commands/           # CLI commands registration
│   └── commands.go     # CLI command registration and configuration
├── crons/              # Cron job definitions
│   └── crons.go        # Cron job registration and configuration
├── database/           # Database-related code
│   ├── migrations/     # Database schema migrations
│   ├── schema/         # PocketBase schema JSON files
│   └── seeders/        # Data seeding utilities
├── handlers/           # Business logic handlers
│   ├── cron/          # Cron job handlers
│   ├── export/        # Data export handlers
│   ├── hook/          # Event hook handlers
│   ├── jobs/          # Job queue handlers
│   └── route/         # Custom route handlers
├── hooks/             # Event hook registration
│   ├── hooks.go       # Hook registration orchestration
│   └── hooks_test.go  # Hook system tests
├── jobs/              # Job management
│   ├── jobs.go        # Job handler registration (new pattern)
│   └── manager.go     # Job manager singleton
├── middlewares/       # HTTP middlewares
│   ├── middlewares.go # Middleware registration (new pattern)
│   ├── auth.go        # Authentication middleware
│   ├── metrics.go     # Metrics collection middleware
│   └── permission.go  # Permission-based access control
├── routes/            # Custom API routes
│   └── routes.go      # Route registration (new pattern)
└── apidoc/           # API documentation generation
    ├── generator.go   # OpenAPI spec generation
    ├── discovery.go   # Collection discovery
    ├── schema.go      # Schema generation
    └── endpoints.go   # API docs endpoints

📁 pkg/ - Reusable Packages

Contains reusable packages that could potentially be imported by other projects.

pkg/
├── cache/             # Caching system
│   ├── cache.go      # Cache service with TTL support
│   └── cache_test.go # Cache system tests
├── common/            # Common utilities
│   ├── env.go        # Environment variable utilities
│   ├── response.go   # HTTP response utilities
│   └── route.go      # Route configuration
├── cronutils/         # Cron execution utilities
│   ├── utils.go      # Cron validation and execution context
│   └── utils_test.go # Cron utilities tests
├── jobutils/          # Job processing utilities
│   ├── processor.go  # Job processor implementation
│   ├── types.go      # Job-related types and interfaces
│   ├── payload.go    # Job payload parsing utilities
│   ├── file.go       # File handling for jobs
│   └── worker_pool.go # Concurrent job processing
├── logger/            # Centralized logging system
│   ├── logger.go     # Logger singleton implementation
│   ├── utils.go      # Logger utilities
│   └── logger_test.go # Logger tests
├── metrics/           # Metrics and observability
│   ├── metrics.go    # Main metrics interface and factory
│   ├── config.go     # Configuration management
│   ├── prometheus.go # Prometheus implementation
│   ├── opentelemetry.go # OpenTelemetry implementation
│   ├── noop.go       # No-op implementation
│   ├── instrumentation.go # Helper functions
│   ├── types.go      # Metric types and constants
│   └── *_test.go     # Comprehensive test suite
├── migration/         # Migration utilities
│   ├── scanner.go    # Migration file scanning
│   ├── filesystem.go # File system operations
│   └── *_test.go     # Migration tests
├── permission/        # Permission system
│   ├── permissions.go # Permission constants and definitions
│   └── permissions_test.go # Permission tests
└── response/          # HTTP response utilities
    ├── response.go   # Standardized HTTP response helpers
    └── response_test.go # Response utility tests

📊 monitoring/ - Monitoring Configurations

Contains monitoring infrastructure configurations for both development and production environments.

monitoring/
├── local/             # Development monitoring setup
│   ├── grafana/       # Grafana configuration
│   │   ├── dashboards/    # Pre-built dashboards
│   │   └── provisioning/ # Grafana provisioning config
│   └── prometheus/    # Prometheus configuration
│       └── prometheus.yml # Local metrics scraping
└── production/        # Production monitoring setup
    ├── grafana/       # Production Grafana config
    ├── prometheus/    # Production Prometheus config
    └── alertmanager/  # Alert management configuration

📁 docs/ - Project Documentation

Comprehensive documentation for all aspects of the project.

docs/
├── README.md              # Documentation index
├── dependency-injection.md # DI patterns and strategies
├── cron-jobs.md          # Job queue and cron system
├── hooks.md              # Event hooks system
├── logger.md             # Logging system
├── middleware.md         # Custom middleware
├── migrations.md         # Database migrations
├── apidoc.md            # API documentation
├── cli-commands.md       # CLI commands and usage
├── git-hooks.md          # Git hooks setup
└── project-tree.md       # This file - project structure

📁 templates/ - Template Files

Contains template files used by the application.

templates/
└── emails/              # Email templates
    ├── welcome.html    # HTML welcome email template
    └── welcome.txt     # Plain text welcome email template

Purpose: Stores template files that can be used by the application for generating dynamic content, such as emails or documents.

Key Design Principles

1. Clean Architecture

  • Clear separation between internal/ (private) and pkg/ (public) code
  • Layered architecture with proper dependency flow
  • Domain-driven design with focused packages

2. Dependency Injection Patterns

  • Singleton Pattern: Shared services (pkg/metrics, pkg/logger, pkg/cache)
  • Constructor Injection: Business logic components (internal/handlers)
  • Factory Pattern: Configurable implementations (pkg/metrics/config.go)
  • Interface-Based: Loose coupling throughout the application

3. Testing Strategy

  • Co-located test files following Go conventions (*_test.go)
  • Comprehensive test coverage for all packages
  • Mock-friendly architecture with interface-based design
  • Singleton reset functionality for isolated testing

4. Configuration Management

  • Environment-driven configuration (.env files)
  • Centralized environment utilities (pkg/common/env.go)
  • Sensible defaults with override capabilities
  • Production and development configurations

File Naming Conventions

Go Files

  • *.go - Implementation files
  • *_test.go - Test files (co-located with implementation)
  • types.go - Type definitions and constants
  • config.go - Configuration structures and loading

Documentation Files

  • README.md - Main documentation or directory index
  • *.md - Specific topic documentation
  • CONTRIBUTING.md - Contribution guidelines
  • LICENSE.md - License information

Configuration Files

  • .env - Environment variables (not in version control)
  • .env.example - Environment template
  • .env.production - Production environment template
  • docker-compose.yml - Production container configuration
  • docker-compose.dev.yml - Development container configuration
  • Dockerfile - Production container definition
  • makefile - Development commands

Temporary Files

  • tmp/ - Temporary files and directories (git ignored)
  • tmp/ - Temporary files directory (git ignored)

Monitoring Files

  • monitoring/local/ - Development monitoring setup
  • monitoring/production/ - Production monitoring deployment
  • monitoring/*/prometheus/ - Prometheus configurations
  • monitoring/*/grafana/ - Grafana dashboards and provisioning

Package Dependencies

Dependency Flow

internal/app/ (orchestrates everything)
    ↓
internal/middlewares/ (HTTP layer)
    ↓
internal/handlers/ (business logic)
    ↓
pkg/ (utilities and services)

Key Relationships

  • internal/app/app.go orchestrates all dependency injection
  • pkg/metrics/ provides observability across all layers
  • pkg/logger/ provides logging across all components
  • pkg/cache/ provides caching for performance optimization
  • internal/middlewares/ provides cross-cutting concerns
  • internal/handlers/ implements business logic

Development Workflow Integration

Hot Reload Support

  • .air.toml - Air configuration for hot reload
  • docker-compose.dev.yml - Development environment with volume mounts
  • Dockerfile.dev - Development container with Air

Code Quality

  • makefile - Standardized development commands
  • .githooks/ - Pre-commit and pre-push validation
  • scripts/ - Setup and utility scripts

Testing Infrastructure

  • Comprehensive test coverage across all packages
  • Benchmark tests for performance-critical components
  • Integration tests for complex workflows
  • Mock-friendly architecture for isolated testing

Production Deployment

Container Strategy

  • Multi-stage Docker builds for optimized production images
  • Separate development and production configurations
  • Volume mounts for persistent data (pb_data/)
  • Health checks and monitoring endpoints

Monitoring and Observability

  • Local Development: monitoring/local/ - Prometheus + Grafana for development
  • Production Deployment: monitoring/production/ - Scalable monitoring infrastructure
  • Metrics Collection: Prometheus scraping with configurable intervals
  • Visualization: Grafana dashboards with pre-built PocketBase metrics
  • Alerting: Alertmanager integration for production notifications
  • Structured Logging: Multiple log levels with centralized collection

Best Practices Demonstrated

  1. Go Project Layout: Follows standard Go project structure
  2. Separation of Concerns: Clear boundaries between layers
  3. Dependency Injection: Multiple strategies for different use cases
  4. Testing: Comprehensive test coverage with proper isolation
  5. Documentation: Extensive documentation for all components
  6. Configuration: Environment-driven with sensible defaults
  7. Containerization: Production-ready Docker setup
  8. Code Quality: Linting, formatting, and Git hooks

Navigation Tips

  • Start with README.md for project overview
  • Explore internal/app/app.go to understand application initialization
  • Review pkg/ packages to understand core utilities
  • Check docs/ for detailed guides on specific topics
  • Use makefile commands for development workflow
  • Refer to .env.example for configuration options

This structure provides a solid foundation for building scalable, maintainable Backend-as-a-Service applications with PocketBase and Go.