# Developer tools: documentation site using Laravel

## Summary

A documentation site blueprint for developer tools built with Laravel on Ample. Domain schema: customer_workspaces (name, plan, api_key_count): customer organizations; doc_versions (product_version, title, object_key, published_at): versioned reference docs and guides; sdk_releases (language, version, changelog_object_key, released_at): SDK releases and changelogs; customer_assets (workspace_id, title, object_key, visibility): customer-specific artifacts; state_transitions (record_type, from_state, to_state): the allowed state machine. Public information: versioned API reference and guides, SDK release notes, status page links. Technical basis verified on Laravel: a workspace-scoped table, an explicit state machine (draft to review to published) that rejects invalid transitions, and a cross-workspace read that returns nothing (transitions=true isolation=true).

## Infrastructure requirements

- Compute: verified (Apps run in isolated x86_64 Firecracker microVMs that auto-pause when idle and wake on request; sizes are the priced VM sizes.)
- Postgres: verified (Managed PostgreSQL 16 runs in its own microVM and is auto-provisioned when an app needs a database and no DATABASE_URL is supplied.)
- CDN: verified (The CDN host serves objects from published buckets. It does not front app compute and is not a cache or key-value store.)

## Prerequisites

- A Laravel project (composer install --no-dev from composer.lock, then FrankenPHP serving public/ (php-server with the index.php fallback) reading PORT on the php-8.5 template)
- A PostgreSQL driver reading DATABASE_URL (auto-provisioned when omitted)
- Bucket credentials from `ample bucket create` passed as encrypted S3_* environment variables and a published bucket for public assets (CDN_*)

## Exact tested configuration

- template: `php-8.5`
- runtime: `php`
- size: `s-1vcpu-1gb`
- install: `composer install --no-dev --prefer-dist --no-interaction --no-progress --optimize-autoloader`
- start: `frankenphp php-server --listen :$PORT --root public`

## Steps

1. **Model the developer tools domain.** Create the tables customer_workspaces, doc_versions, sdk_releases, customer_assets, state_transitions.
2. **Workflow step 1.** Model versioned documents with a state machine (draft, review, published) scoped to a product version.
3. **Workflow step 2.** Publish assets for released versions to the CDN bucket.
4. **Workflow step 3.** Serve only published versions publicly.
5. **Workflow step 4.** Deploy and verify the version list and a published page.
6. **Deploy.** Run the synchronous deploy once and read the result.
7. **Verify.** Run the pattern self-test(s) from the example and your own acceptance checks for the developer tools workflow.

## Success checks

- app responds on its public URL (`/` on the live URL)
- relational-records self-test from the example (`/p/relational-records` on the live URL)

## Limitations

- The technical basis (relational records on Laravel) was verified with the pattern fixture; the developer tools schema and workflow are an original design for this blueprint and were not executed as a separate application.
- API keys and usage logs are secrets or personal data; keep them out of documentation workflows.

## Cost estimate

Estimated 10.00 USD per month (size prices from pricing.toml at build revision a1b8c38919e59cd035ebabaced73cf84ece24371).
- app server x1 `s-1vcpu-1gb`: 5.00 USD
- managed PostgreSQL database x1 `s-1vcpu-1gb`: 5.00 USD

## Verification evidence

- canary_run on 2026-09-20T20:36:21Z at revision `118ad1c6d7d23d4c2ce069254bab9ec9d37cd57b-dirty (CLI 118ad1c)`: Laravel pattern fixture deployed on Ample.