hosting-backend/openspec/project.md

Project Context

Purpose

A Laravel-based hosting backend API that manages user portfolios and static site deployments. The system allows users to:

• Register and authenticate via OAuth 2.0 (Passport)
• Create and manage multiple portfolios with custom domains
• Upload static site files (HTML/CSS/JS)
• Deploy sites to Kubernetes infrastructure
• Retrieve portfolio information via public endpoints

Tech Stack

• Language: PHP 8.2
• Framework: Laravel 12
• Authentication: Laravel Passport (OAuth 2.0 tokens)
• Database: MySQL (production), SQLite (development)
• Cache/Session: Database-backed
• Queue System: Database-backed
• Container: Docker with Alpine Linux
• Orchestration: Kubernetes (k3s)
• CI/CD: Gitea Actions (tag-driven deployment)
• Package Manager: Composer
• Testing: PHPUnit 11.5.3
• Code Formatting: Laravel Pint

Project Conventions

Code Style

• PSR-4 Autoloading: All classes use appropriate namespaces (App\Http\Controllers, App\Models, App\Jobs, etc.)
• Naming Conventions:
  • Controllers: Plural resource names (PortfolioController, AuthController)
  • Models: Singular (User, Portfolio)
  • Methods: camelCase (getPortfolioName, getStoragePath)
  • Database Tables: Plural (portfolios, users)
• Response Format: All API responses use ApiResponse helper with consistent structure:

  {
    "success": true/false,
    "message": "Human-readable message",
    "data": {...}
  }
  

• Code Organization: Separation of concerns with Models, Controllers, Services, Jobs, Policies, and Helpers
• Documentation: PHPDoc comments on public methods

Architecture Patterns

• MVC Pattern: Models (Eloquent ORM), Controllers (HTTP handlers), Views (API responses)
• Authorization: Laravel Policies (PortfolioPolicy) for centralized authorization logic
• Service Layer: Business logic extracted into Services (PortfolioUploadService)
• Job Queue: Background jobs for long-running operations (DeployStaticSiteJob)
• Dependency Injection: Constructor injection used throughout (services, repositories)
• RESTful API: Follows REST conventions for resource endpoints (/portfolios, /portfolios/{id})

Testing Strategy

• Framework: PHPUnit with Laravel's test helpers
• Test Organization:
  • Feature tests: Integration tests for HTTP endpoints (/tests/Feature/)
  • Unit tests: Isolated unit tests (/tests/Unit/)
• Test Database: In-memory SQLite for fast test execution
• Test Running: composer test clears config cache and runs PHPUnit
• Coverage: Code coverage reports include /app directory
• Test Optimization: BCRYPT_ROUNDS set to 4 for faster password hashing in tests

Git Workflow

• Main Branch: Primary development branch is 'main'
• Deployment Strategy: Tag-based deployments
  • Tags matching PRE_ALPHA* trigger alpha deployment to hosting-alpha namespace
  • Tags matching PROD* trigger production deployment to hosting namespace
• Commit Convention: Follow conventional commits for clarity
• CI/CD: Gitea Actions workflows automatically build, push to registry, and deploy on tags

Domain Context

Portfolio Management

• Each user can have multiple portfolios (hasMany relationship)
• Portfolios have domain, path, active status, and deployment tracking
• Active status controls whether uploads are allowed (verified through PortfolioPolicy)

Deployment Process

1. User uploads ZIP file containing site files
2. Files stored at portfolios/{name}/{id}/index.html
3. Deploy job dispatched to queue
4. Artisan command runs Ansible playbook for infrastructure deployment
5. Site becomes accessible at configured domain

Authentication

• OAuth 2.0 token-based (Laravel Passport)
• Users create personal access tokens for API requests
• Token stored in Authorization header: Bearer {token}

Important Constraints

• File Upload Limit: 10MB max file size per upload
• Activation Required: Portfolio must be marked as active (paid) to allow uploads
• Active Field: Represents subscription/payment status (controls upload/deploy access)
• Authorization: Only portfolio owner can view/update/delete/deploy
• Rate Limiting: Handled by deployment job (prevents simultaneous deploys)
• Database-Backed Queue: Tasks persist in database (no external queue service)

External Dependencies

• Kubernetes (k3s): Container orchestration platform
• Docker Registry: For storing built container images
• Ansible: Infrastructure provisioning and deployment orchestration
• Nginx: Web server configuration for deployed sites
• Supervisor: Process manager for application workers
• Git: Version control (Gitea)

Recent Code Cleaning & Refactoring (Q1 2025)

Applied DRY Principles

1. AuthController: Refactored to use ApiResponse helper consistently (eliminates duplicate response formatting)
2. Portfolio Attributes: Created model methods (getPortfolioName, getPortfolioDomain, getStoragePath) to reduce controller code duplication
3. API Responses: Standardized all responses through ApiResponse helper

Applied KISS Principles

1. Removed Unused Code: Deleted empty StaticSiteController and unused routes
2. Removed Debug Routes: Cleaned up test routes (/ping, /pute)
3. Authorization Refactor: Replaced manual authorization checks with Laravel Policies for cleaner, maintainable authorization
4. Service Layer: Extracted file upload logic into PortfolioUploadService for better separation of concerns

Code Quality Improvements

• Authorization logic centralized in PortfolioPolicy
• File upload responsibility separated into dedicated service
• Consistent API response formatting across all endpoints
• Removed unnecessary getAttribute() calls (using direct property access)
• Eliminated manual validation duplication