saas-seeder

## Platform Notes

- Optional helper plugins may help in some environments, but they must not be treated as required for this skill.

# SaaS Seeder Template Bootstrap
Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

<!-- dual-compat-start -->
## Use When

- Bootstrap a new SaaS from the SaaS Seeder Template: setup database, configure environment, create super admin user, and verify three-tier panel structure. Use when initializing a new multi-tenant SaaS project from this template.
- The task needs reusable judgment, domain constraints, or a proven workflow rather than ad hoc advice.

## Do Not Use When

- The task is unrelated to `saas-seeder` or would be better handled by a more specific companion skill.
- The request only needs a trivial answer and none of this skill's constraints or references materially help.

## Required Inputs

- Gather relevant project context, constraints, and the concrete problem to solve; load `references` only as needed.
- Confirm the desired deliverable: design, code, review, migration plan, audit, or documentation.

## Workflow

- Read this `SKILL.md` first, then load only the referenced deep-dive files that are necessary for the task.
- Apply the ordered guidance, checklists, and decision rules in this skill instead of cherry-picking isolated snippets.
- Produce the deliverable with assumptions, risks, and follow-up work made explicit when they matter.

## Quality Standards

- Keep outputs execution-oriented, concise, and aligned with the repository's baseline engineering standards.
- Preserve compatibility with existing project conventions unless the skill explicitly requires a stronger standard.
- Prefer deterministic, reviewable steps over vague advice or tool-specific magic.

## Anti-Patterns

- Treating examples as copy-paste truth without checking fit, constraints, or failure modes.
- Loading every reference file by default instead of using progressive disclosure.

## Outputs

- A concrete result that fits the task: implementation guidance, review findings, architecture decisions, templates, or generated artifacts.
- Clear assumptions, tradeoffs, or unresolved gaps when the task cannot be completed from available context alone.
- References used, companion skills, or follow-up actions when they materially improve execution.

## Evidence Produced

| Category | Artifact | Format | Example |
|----------|----------|--------|---------|
| Release evidence | SaaS bootstrap record | Markdown doc capturing database, super-admin, and environment setup decisions for the seeded SaaS | `docs/saas/bootstrap-record-2026-04-16.md` |

## References

- Use the `references/` directory for deep detail after reading the core workflow below.
<!-- dual-compat-end -->
Bootstrap a new multi-tenant SaaS project using the SaaS Seeder Template with proper three-tier panel architecture, Argon2ID authentication, and franchise isolation.

## Security Baseline (Required)

Always load and apply the **Vibe Security Skill** for any seeder work that touches web pages, APIs, authentication, data access, or file handling. Treat its checklist as mandatory.

## Database Standards (Required)

All database schema setup, seeding, and migrations MUST follow **mysql-best-practices** skill patterns including character sets, indexing, foreign keys, and stored procedures.

## Standard Deployment Environments

All SaaS projects deploy across three environments:

| Environment | OS | Database | Web Root |
|---|---|---|---|
| **Development** | Windows 11 (WAMP) | MySQL 8.x | `C:\wamp64\www\{project}\` |
| **Staging** | Ubuntu VPS | MySQL 8.x | `/var/www/html/{project}/` |
| **Production** | Debian VPS | MySQL 8.x | `/var/www/html/{project}/` |

**Cross-platform rules:** Use `utf8mb4_unicode_ci` collation. Match file/directory case exactly (Linux is case-sensitive). Use forward slashes in PHP paths. Production migrations go in `database/migrations-production/` (non-destructive, idempotent).

## When to Use

Use when the user says:

- "Using the seeder-script skill, prepare this repository for [SaaS name]"
- "Bootstrap a new SaaS from this template"
- "Initialize the SaaS Seeder Template"
- "Setup database for new SaaS project"
- "Start a new project from the template"

## Project Preparation Workflow

**BEFORE bootstrapping, developers MUST provide:**

### 1. Requirements & Design Specifications

Place in `docs/project-requirements/`:

```
docs/project-requirements/
├── requirements.md          # Detailed feature requirements
├── business-rules.md         # Business logic and validation rules
├── user-types.md             # User types and their permissions
├── workflows.md              # Key user workflows and processes
└── ui-mockups/               # UI mockups or wireframes (optional)
```

**Use the `project-requirements` skill to create these files with AI assistance.**

### 1.1 Documentation Readiness (Required)

- Confirm end-user manual scope is defined for each core feature
- Plan manual locations in `/manuals/` and a public entry point (e.g., `/public/user-manuals.php`)
- Ensure specs are written in a way that can be translated into manuals and step-by-step guides

### 2. Database Schema Files

Place in `database/schema/`:

```
database/schema/
├── core-schema.sql           # Main database schema
├── seed-data.sql             # Sample/seed data (optional)
└── schema-diagram.png        # Database diagram (optional)
```

**Schema Requirements:**

- All franchise-scoped tables MUST have `franchise_id` column
- Use `utf8mb4_unicode_ci` collation
- Include proper indexes and foreign keys

### AI Agent Preparation Steps

When starting a new project:

1. **Read Project Requirements**
   - Load all files from `docs/project-requirements/`
   - Understand user types, workflows, business rules
   - Identify custom tables needed beyond template defaults

2. **Review Database Schema**
   - Read schema files from `database/schema/`
   - Validate against multi-tenant patterns (franchise_id filtering)
   - Ensure collation is utf8mb4_unicode_ci
   - Check for proper indexes and foreign keys

3. **Update Project Documentation**
   - Replace README.md with project-specific content
   - Update AGENTS.md with project-specific guidance
   - Remove template docs from docs/ (keep only project-relevant ones)
   - Add project-specific documentation based on requirements
   - Ensure `docs/plans/INDEX.md` exists as the master plan status index and is maintained as plans are created or updated

4. **Customize Template**
   - Update branding (SaaS Seeder → Project Name)
   - Set SESSION_PREFIX to project-specific value
   - Customize user types enum if needed
   - Update environment variable examples
   - Register GIS settings when mapping is required (tile provider keys such as system_settings.osm_api_key)

5. **Validate Completeness**
   - Check all requirements are documented
   - Verify database schema follows multi-tenant patterns
   - Ensure session prefix is customized
   - Confirm user types match requirements

## Critical Architecture Standards

**See `references/architecture.md` for complete details.**

### Three-Tier Panel Structure (CORE Concept)

1. **`/public/` (root)** - Franchise Admin Panel (THE MAIN WORKSPACE)
   - Single franchise management
   - User types: `owner`, `staff`
   - Files: `dashboard.php`, `skeleton.php`

2. **`/public/adminpanel/`** - Super Admin Panel
   - System-wide management
   - Multi-franchise oversight
   - User type: `super_admin`

3. **`/public/memberpanel/`** - End User Portal
   - Self-service for end users
   - User types: `member`, `student`, `customer`, `patient`

**Key Principle:** `/public/` root is NOT a redirect router - it's the franchise admin workspace!

### Session Prefix System

**All session variables use a prefix:**

```php
define('SESSION_PREFIX', 'saas_app_'); // Change per SaaS

// ALWAYS use helpers
setSession('user_id', 123);        // Sets $_SESSION['saas_app_user_id']
$userId = getSession('user_id');   // Gets $_SESSION['saas_app_user_id']
hasSession('user_id');             // Checks if exists
```

**Customize per SaaS:** `school_`, `restaurant_`, `clinic_`, etc.

### Password Hashing

**Uses Argon2ID (NOT bcrypt):**

```
Algorithm: Argon2ID + salt(32 chars) + pepper(64+ chars)
Hash: salt + Argon2ID(HMAC-SHA256(password, pepper) + salt)
```

**CRITICAL:** Use `super-user-dev.php` to create admin users, NOT migration defaults!

## Required Files And Paths

- `docs/seeder-template/migration.sql` - Core auth/RBAC schema
- `docs/seeder-template/fix-collation-and-create-franchises.sql` - Collation fixes + franchises table
- `docs/project-requirements/` - Project requirements (developer provides)
- `database/schema/` - Project database schemas (developer provides)
- `public/super-user-dev.php` - Super admin creator (DEV ONLY)
- `public/dashboard.php` - Franchise admin dashboard
- `public/skeleton.php` - Page template
- `.env` - Environment configuration

## Standard Workflow

**See `references/workflow.md` for complete step-by-step guide.**

### Quick Bootstrap Steps

1. **Environment Setup**
   - Ask for DB credentials, cookie domain, encryption keys
   - Create/update `.env` file

2. **Install Dependencies**

   ```bash
   composer install
   ```

3. **Install PHP Development Tools**

   **See `references/php-tooling.md` for complete setup guide.**

   **Quick install:**

   ```bash
   # Check existing tools
   composer show | grep -E "(phpstan|phpunit|pest|php-cs-fixer)"

   # Install essential tools
   composer require --dev phpstan/phpstan
   composer require --dev friendsofphp/php-cs-fixer
   composer require --dev pestphp/pest --with-all-dependencies
   ```

   **Create configs and add composer scripts (see references/php-tooling.md for details).**

4. **Database Setup**

   ```bash
   .\setup-database.ps1  # Windows PowerShell
   ```

5. **Fix Collations**

   ```bash
   .\fix-database.ps1  # Creates franchises table
   ```

6. **Create Super Admin**
   - Visit `http://localhost:8000/super-user-dev.php`
   - Uses correct Argon2ID hashing

7. **Verify Setup**
   - Login at `http://localhost:8000/sign-in.php`
   - See landing page with navigation buttons

8. **Project Customization**
   - Update SESSION_PREFIX in `src/config/session.php`
   - Customize user types enum
   - Apply project database schema
   - Update branding throughout
   - Create project-specific AGENTS.md

## Seeding Rules

### User Types & Franchise Requirements

- `super_admin` - Platform operators (franchise_id CAN be NULL)
- `owner` - Franchise owners (franchise_id REQUIRED)
- `staff` - Franchise staff with permissions (franchise_id REQUIRED)
- Custom types - End users (franchise_id REQUIRED)

### Franchise Data

**ALWAYS filter by franchise_id:**

```php
// CORRECT
$stmt = $db->prepare("SELECT * FROM students WHERE franchise_id = ?");
$stmt->execute([getSession('franchise_id')]);

// WRONG - data leakage!
$stmt = $db->prepare("SELECT * FROM students");
```

### Permission Codes

- Uppercase with underscores
- Format: `RESOURCE_ACTION`
- Examples: `INVOICE_CREATE`, `STUDENT_DELETE`, `REPORT_VIEW`

## Troubleshooting

**See `references/troubleshooting.md` for complete guide.**

### Common Issues

**Session Not Persisting**

- HTTPS auto-detection already handled
- Localhost HTTP works without HTTPS requirement

**Password Mismatch**

- Use `super-user-dev.php`, NOT manual password_hash()
- Template uses Argon2ID, not bcrypt

**Collation Errors**

- Run `.\fix-database.ps1`
- Fixes utf8mb4_unicode_ci mismatches

**Missing Franchises Table**

- Run `.\fix-database.ps1`
- Creates tbl_franchises with default data

## Output After Completion

### For New Project from Template

Report to user:

```
✅ [Project Name] Initialized!

Requirements Loaded:
- ✅ Read from docs/project-requirements/
- ✅ Database schema reviewed from database/schema/
- ✅ User types customized: [list custom types]
- ✅ Session prefix set to: [prefix]_

Database Setup:
- ✅ Core schema applied
- ✅ Seed data loaded (if provided)
- ✅ Multi-tenant validation passed

PHP Development Tools Installed:
- ✅ PHPStan (level 8) - Static analysis
- ✅ PHP CS Fixer - PSR-12 formatting
- ✅ PHPUnit/Pest - Testing framework
- ✅ Configuration files created
- ✅ Composer scripts configured

Project Documentation:
- ✅ README.md updated for [Project Name]
- ✅ AGENTS.md created with project-specific guidance
- ✅ Template docs archived/removed

Branding:
- ✅ Updated throughout application
- ✅ Landing page customized
- ✅ Login page branded

Next Steps:
1. Review updated AGENTS.md for project-specific guidance
2. Create super admin at http://localhost:8000/super-user-dev.php
3. Login and verify three-tier panel structure
4. Run quality checks: composer quality
5. Begin implementing features from docs/project-requirements/

Development Commands:
- composer test          # Run tests
- composer stan          # Static analysis
- composer cs-fix        # Format code (PSR-12)
- composer quality       # Run all checks

References:
- Requirements: docs/project-requirements/
- Schema: database/schema/
- Development Guide: AGENTS.md
```

## File Structure After Setup

### Template Structure (Before Project Customization)

```
saas-seeder/
├── public/                # Web root
│   ├── index.php         # Landing page with nav buttons
│   ├── sign-in.php       # Login
│   ├── super-user-dev.php # Super admin creator
│   ├── dashboard.php     # Franchise admin dashboard
│   ├── skeleton.php      # Page template
│   ├── adminpanel/       # Super admin panel
│   ├── memberpanel/      # End user portal
│   └── assets/           # Shared CSS/JS
├── src/
│   ├── config/
│   │   ├── auth.php      # Auth functions + access control
│   │   ├── session.php   # Session prefix helpers
│   │   └── database.php  # Database connection
│   └── Auth/             # Auth services, helpers, DTOs
├── docs/
│   ├── seeder-template/  # Template schemas
│   ├── PANEL-STRUCTURE.md # Architecture guide
│   └── project-requirements/ # ⭐ PUT PROJECT REQUIREMENTS HERE
│       ├── requirements.md
│       ├── business-rules.md
│       ├── user-types.md
│       └── workflows.md
├── database/
│   └── schema/           # ⭐ PUT DATABASE SCHEMAS HERE
│       ├── core-schema.sql
│       └── seed-data.sql
├── .env                  # Environment config
├── composer.json         # Dependencies
├── setup-database.ps1    # Setup script
├── fix-database.ps1      # Fix script
└── AGENTS.md             # Development guide
```

## References

**Complete documentation in subdirectories:**

- `references/architecture.md` - Complete architectural standards
- `references/workflow.md` - Detailed step-by-step workflow
- `references/troubleshooting.md` - Common issues and solutions
- `references/php-tooling.md` - PHP development tools setup and usage guide

**External references:**

- `../../docs/PANEL-STRUCTURE.md` - Three-tier architecture guide
- `../../AGENTS.md` - Development guidelines
- `../project-requirements/` - Skill for creating requirements docs

## Quality Assurance

**See `references/php-tooling.md` for complete guide.**

### Quick Commands

```bash
composer cs-fix     # Format code (PSR-12)
composer stan       # Static analysis
composer test       # Run tests
composer quality    # All checks
```

### Pre-Commit Workflow

```bash
composer quality && git commit -m "feat: description"
```

### What to Test

✅ Authentication, franchise isolation, permissions, password hashing, session management, input validation

**See `references/php-tooling.md` for testing examples, CI/CD setup, and IDE integration.**

## Security Checklist Before Production

- [ ] Remove `super-user-dev.php` or restrict access
- [ ] Change `SESSION_PREFIX` from `saas_app_`
- [ ] Set strong `PASSWORD_PEPPER` (64+ chars)
- [ ] Set strong `COOKIE_ENCRYPTION_KEY` (32+ chars)
- [ ] Set `APP_ENV=production`
- [ ] Enable HTTPS (session cookies require it)
- [ ] Review all queries for franchise_id filtering
- [ ] Set proper file permissions on `.env` (600)