PHPackages                             protoframework/proto-project - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. protoframework/proto-project

ActiveProject[Framework](/categories/framework)

protoframework/proto-project
============================

This is a project that uses the Proto Framework.

1.2.6(2mo ago)06MITJavaScriptPHP >=8.4CI passing

Since Aug 5Pushed 2mo agoCompare

[ Source](https://github.com/chrisdurfee/proto-project)[ Packagist](https://packagist.org/packages/protoframework/proto-project)[ RSS](/packages/protoframework-proto-project/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (10)Versions (56)Used By (0)

Proto Project
=============

[](#proto-project)

This repository is a **project skeleton** for building applications on the [Proto Framework](https://github.com/chrisdurfee/proto), with [Base Framework](https://github.com/chrisdurfee/base) on the front end. It includes the files, settings, and configuration you need to bootstrap a large, multi-app platform.

The project is published on Packagist and can be set up in just a few commands. It uses Docker, Composer, NPM, Vite, Base, PHP 8.4+, MariaDB, Redis, and more.

It wires up Docker, a sensible folder structure, and a minimal entry point so you can start writing modules and apps right away. It also includes a companion document to help AI agents understand the project structure, dependencies, and configuration.

The template ships with three front-end apps—**Main (Consumer)**, **CRM (Admin)**, and **Developer**—built with Base + Vite, plus a PHP backend API service. These apps connect to the Proto backend via REST APIs and WebSockets for real-time features.

Each app includes the [Base UI](https://github.com/chrisdurfee/ui) package for pre-built components and styles to speed up development. All apps are **PWAs** with install prompts, support for light/dark mode, and theme customization.

Out of the box, the front end includes working user auth flows: login, password reset, “forgot password,” multi-factor authentication, user activity tracking, session resume, session heartbeat, push-notification support, caching, and more.

The application layer includes a robust user system with roles, permissions, organizations, followers/following, blocking, and more.

On the backend, an integrated **OpenAI** service powers AI features such as chat, completions, embeddings, and other intelligent workflows.

---

� Prerequisites
---------------

[](#-prerequisites)

### For Containerized Development (Recommended)

[](#for-containerized-development-recommended)

- [Docker Desktop](https://www.docker.com/products/docker-desktop/) (Windows/macOS) or Docker Engine (Linux or if you are using WSL2)
- Git
- Composer
- Node.js (for frontend development)

### For Traditional Development

[](#for-traditional-development)

- Git
- PHP 8.4+
- Composer
- MySQL/MariaDB
- Node.js (for frontend development)

### Framework Requirements

[](#framework-requirements)

- **Proto Framework**: v1.0+

---

�📦 Installation
---------------

[](#-installation)

Choose one of the two approaches:

### 1. Create a brand-new project via Composer (Recommended)

[](#1-create-a-brand-new-project-via-composer-recommended)

```
composer create-project protoframework/proto-project my-app
cd my-app
composer install

```

### 2. Clone & install

[](#2-clone--install)

```
git clone https://github.com/protoframework/proto-project.git my-app
cd my-app
composer install

```

---

🐳 Local Development (Hybrid Setup)
----------------------------------

[](#-local-development-hybrid-setup)

This project uses a **hybrid development approach** that combines the best of both worlds:

- **Backend services** run in Docker containers (no local PHP/MySQL needed)
- **Frontend apps** run locally with Vite for lightning-fast hot reload

### Configuration Sync

[](#configuration-sync)

First, create your Common/Config/.env file by copying the example:

```
cp ./common/Config/.env-example ./common/Config/.env

```

Update the environment variables as needed. Then, sync your Proto configuration to Docker:

```
# Generate Docker .env from Proto configuration
./infrastructure/scripts/run.sh sync-config

# Or run directly: node infrastructure/scripts/sync-config.js

```

### Quick Start

[](#quick-start)

**1. Start Backend Services:**

```
docker compose -f infrastructure/docker-compose.yaml up -d      # Start development

```

> **✨ Automatic Setup**:
>
> - First run will build the Docker image (may take 2-3 minutes)
> - Dependencies install automatically if `vendor/` is missing
> - Database migrations run automatically (disable with `AUTO_MIGRATE=false`)
> - Bind mounts provide live code editing while keeping container benefits

### 🔐 Trusting the Local Certificate (Remote Development)

[](#-trusting-the-local-certificate-remote-development)

**If you are accessing this workspace remotely (e.g., via SSH or a cloud IDE) but viewing the site on your local Windows or Mac computer:**

1. **Download the certificate file:** `infrastructure/docker/ssl/localhost.crt`
2. **Install it on your computer:**
    - **Windows:** Double-click the `.crt` file -> "Install Certificate" -> "Current User" -> "Place all certificates in the following store" -> **"Trusted Root Certification Authorities"**.
    - **Mac:** Double-click the `.crt` file to open Keychain Access. Find the "localhost" cert, double-click it, expand "Trust", and set "When using this certificate" to "Always Trust".
    - **Chrome (Browser Store):** Go to `chrome://certificate-manager`, click "Local certificates", and look for an "Import" option (often under "Custom" or "Your certificates") to add the `.crt` file directly.
3. **Restart Chrome.**

**2. Start Frontend Apps** (in separate terminals):

```
# Main App
cd apps/main
npm install  # (first time only)
npm run dev

# CRM App
cd apps/crm
npm install  # (first time only)
npm run dev

# Developer App
cd apps/developer
npm install  # (first time only)
npm run dev

```

### Available Services

[](#available-services)

ServiceURLDescription🌐 Main AppMain application (Vite dev server)🌐 CRM AppCRM interface (Vite dev server)🌐 Developer ToolsDeveloper UI with scaffolding tools (Vite dev server)🚀 HTTPS API ServerPHP backend API (containerized)🚀 API ServerPHP backend API (containerized)🗄️ PHPMyAdminDatabase management interface🗄️ Databaselocalhost:3307MariaDB 11.7.2 server📝 Cachelocalhost:6380Redis server### Development Workflow

[](#development-workflow)

**Backend Changes:**

```
# View API logs
docker compose -f infrastructure/docker-compose.yaml logs -f web

# Access PHP container
docker compose -f infrastructure/docker-compose.yaml exec web bash

# Restart backend if needed
docker compose -f infrastructure/docker-compose.yaml restart web

# Manual migration control (if AUTO_MIGRATE=false)
docker compose -f infrastructure/docker-compose.yaml exec web php infrastructure/scripts/run-migrations.php

```

**Frontend Changes:**

- Edit any `.js`, `.css`, or other frontend files
- Changes appear instantly in browser (hot module reload)
- No need to restart anything!

**Database Management:**

```
# Access database directly
docker compose -f infrastructure/docker-compose.yaml exec mariadb mariadb -uroot -proot proto

# Or use phpMyAdmin at http://localhost:8081

```

### Why This Approach?

[](#why-this-approach)

✅ **Lightning Fast HMR**: Native Vite performance on your host machine ✅ **Instant Updates**: File changes reflect immediately in browser ✅ **Clean Architecture**: Backend and frontend properly separated ✅ **Easy API Access**: Frontend apps automatically proxy `/api` requests to containerized backend ✅ **No Setup Complexity**: No need for local PHP/MySQL installation ✅ **Auto-Migration**: Database schema automatically updates on container start

For detailed setup instructions, see [infrastructure/docs/DEVELOPMENT.md](infrastructure/docs/DEVELOPMENT.md).

---

🤖 Automated Features
--------------------

[](#-automated-features)

The Docker setup includes several automation features to streamline development:

### **Build-Time Automation**

[](#build-time-automation)

When you build the Docker image (`docker-compose -f infrastructure/docker-compose.yaml build`), the following happens automatically:

- ✅ **Configuration Sync**: Reads `common/Config/.env` and generates Docker environment variables
- ✅ **PHP Validation**: Checks PHP syntax across the codebase
- ✅ **Apache Module Setup**: Enables all required modules for `.htaccess` functionality
- ✅ **Build Verification**: Ensures all critical files and directories are present

### **Runtime Automation**

[](#runtime-automation)

When you start the container (`docker-compose -f infrastructure/docker-compose.yaml up`), the following happens automatically:

- ✅ **Service Dependencies**: Waits for database and Redis to be ready before starting
- ✅ **Database Migrations**: Runs pending migrations automatically (configurable)
- ✅ **Health Checks**: Verifies autoloader and critical dependencies
- ✅ **Apache Startup**: Starts Apache with optimized configuration

### **Migration Control**

[](#migration-control)

By default, database migrations run automatically for convenience:

```
# Default behavior - migrations run automatically
docker compose -f infrastructure/docker-compose.yaml up -d

```

For production or when you want manual control:

```
# Disable auto-migrations
echo "AUTO_MIGRATE=false" >> .env
docker compose -f infrastructure/docker-compose.yaml up -d

# Then run migrations manually when ready
docker compose -f infrastructure/docker-compose.yaml exec web php infrastructure/scripts/run-migrations.php

```

### **SSL Setup (Manual)**

[](#ssl-setup-manual)

For security reasons, SSL certificate setup remains manual:

```
# Set up SSL certificates (production only)
./infrastructure/scripts/run.sh setup-ssl yourdomain.com your-email@yourdomain.com

```

This automation makes the development experience much smoother while maintaining production safety controls.

---

🏗️ Directory Layout
-------------------

[](#️-directory-layout)

```
proto-project/
├─ apps/                   # Frontend PWAs (main, crm, developer)
├─ common/                 # Shared Proto framework code
├─ modules/                # Proto framework feature modules
├─ public/                 # HTTP entrypoints & public assets
├─ vendor/                 # Composer dependencies
├─ infrastructure/         # Development & deployment infrastructure
│  ├─ config/              # Configuration files
│  │  ├─ domain.config.js  # Domain configuration system
│  │  ├─ docker-compose.production.yaml # Production Docker setup
│  │  └─ docker-compose.traefik.yaml # Traefik reverse proxy
│  ├─ docker/              # Docker-related files
│  │  ├─ apache-subdomain.conf # Apache virtual host config
│  │  ├─ apache-vhost.conf # Standard Apache config
│  │  ├─ Dockerfile        # Docker image definition
│  │  ├─ entrypoint.sh     # Container startup script
│  │  ├─ php/              # PHP configuration
│  │  └─ mysql/            # MySQL initialization scripts
│  ├─ docs/                # Documentation
│  │  ├─ DEVELOPMENT.md    # Development setup guide
│  │  ├─ SSL-SETUP.md      # SSL certificate setup
│  │  ├─ SUBDOMAIN-DEPLOYMENT.md # Production deployment
│  │  └─ ...               # Other documentation
│  ├─ scripts/             # Build and setup scripts
│  │  ├─ build-production.* # Production build scripts
│  │  ├─ setup-ssl.*       # SSL certificate setup
│  │  ├─ sync-config.*     # Configuration sync scripts
│  │  ├─ run.sh / run.bat  # Script runner
│  │  └─ ...               # Other utility scripts
│  ├─ docker-compose.yaml  # Development Docker setup
│  └─ sync-config.js       # Configuration sync utility
└─ README.md               # This file

```

---

🚀 Quick Commands
----------------

[](#-quick-commands)

```
# Configuration
docker compose -f infrastructure/docker-compose.yaml down         # Stop all services
./infrastructure/scripts/run.sh sync-config              # Sync Proto config to Docker
node infrastructure/scripts/sync-config.js               # Alternative: direct sync

# Development
docker compose -f infrastructure/docker-compose.yaml up -d              # Start backend services (auto-migrates by default)
cd apps/main && npm run dev       # Start main app
cd apps/crm && npm run dev        # Start CRM app
cd apps/developer && npm run dev  # Start developer tools

# Database
AUTO_MIGRATE=false docker compose -f infrastructure/docker-compose.yaml up -d  # Start without auto-migration
./infrastructure/scripts/run.sh migrations               # Run database migrations manually
docker compose -f infrastructure/docker-compose.yaml exec web php infrastructure/scripts/run-migrations.php  # Alternative manual migration

# Production
# SSL & Production
./infrastructure/scripts/run.sh setup-ssl yourdomain.com your-email@domain.com  # Setup SSL
./infrastructure/scripts/run.sh build                    # Build all apps for production
docker compose -f infrastructure/config/docker-compose.production.yaml up -d  # Deploy production

# Utilities
./infrastructure/scripts/run.sh help                     # Show all available scripts
docker compose -f infrastructure/docker-compose.yaml logs -f web        # Watch container startup and migration logs

```

### Application Settings

[](#application-settings)

Your application-specific settings live in **`common/Config/.env`**. Proto reads JSON-encoded environment variables from there:

```
{
  "APP_ENV": "dev",
  "siteName": "My Application",
  "domain": {
    "production": "yourdomain.com",
    "development": "localhost",
    "subdomains": {
      "api": "api",
      "main": "app",
      "crm": "crm",
      "developer": "dev"
    },
    "ssl": true,
    "ports": {
      "development": {
        "api": 8443,
        "main": 3000,
        "crm": 3001,
        "developer": 3002
      }
    }
  }
}

```

### Domain Configuration

[](#domain-configuration)

The project uses a **hybrid domain configuration system** that automatically adapts URLs based on your environment:

**Development Mode:**

- All apps use `localhost` with specific ports
- No SSL/HTTPS required for local development

**Production Mode:**

- Uses subdomains with your configured domain
- Automatic SSL/HTTPS based on configuration
- All frontend apps automatically use correct API endpoints

**To change your domain:**

1. Edit the `"production"` value in `common/Config/.env`
2. All apps will automatically use the new domain
3. No code changes required in individual apps

The domain configuration is handled by `domain.config.js`, which reads from your Proto configuration and provides fallback defaults if needed.

### SSL Certificate Setup (Production)

[](#ssl-certificate-setup-production)

For production deployment with HTTPS, use the automated SSL setup:

**Quick SSL Setup:**

```
# Linux/macOS
./infrastructure/scripts/run.sh setup-ssl yourdomain.com your-email@yourdomain.com

# Windows
infrastructure\scripts\run.bat setup-ssl yourdomain.com your-email@yourdomain.com

```

This automatically:

- ✅ Requests free Let's Encrypt SSL certificates for all subdomains
- ✅ Sets up certificate renewal scripts
- ✅ Configures Apache for HTTPS
- ✅ Creates production-ready deployment files

**Manual SSL Setup:**See [infrastructure/docs/SSL-SETUP.md](infrastructure/docs/SSL-SETUP.md) for detailed SSL configuration options including custom certificates and Traefik reverse proxy setup.---

⚙️ Configuration
----------------

[](#️-configuration)

All you need in your front-controller is:

```