From 977275c079a32d4c95cf6bbaa846214db7233897 Mon Sep 17 00:00:00 2001 From: root Date: Wed, 23 Sep 2026 16:05:27 +0300 Subject: [PATCH] Replace stock Laravel README with project docs Explains what dreamstudio does and how the generation flow, budget enforcement, and model/pricing table work. --- README.md | 75 ++++++++++++++++++++++++++----------------------------- 1 file changed, 35 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 5ad1377..72dad3a 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,53 @@ -

Laravel Logo

+# dreamstudio -

-Build Status -Total Downloads -Latest Stable Version -License -

+A Laravel app that generates images, video, and text through [Runware.ai](https://runware.ai)'s API, with every generation's real cost tracked and a hard monthly spending cap enforced before any request goes out. -## About Laravel +It's the shared foundation for three ad-monetized products (an SEO image gallery site, a free viral tool, a faceless Shorts channel) that will sit on top of the same Runware integration — but on its own it's a working generator: submit a prompt, pick a type, get an image/video/text result, and always know exactly what it cost. -Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as: +## How it works -- [Simple, fast routing engine](https://laravel.com/docs/routing). -- [Powerful dependency injection container](https://laravel.com/docs/container). -- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage. -- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent). -- Database agnostic [schema migrations](https://laravel.com/docs/migrations). -- [Robust background job processing](https://laravel.com/docs/queues). -- [Real-time event broadcasting](https://laravel.com/docs/broadcasting). +**Generation flow** (`app/Services/Runware/GenerationService.php`) +1. Resolve which model to use — an explicit override, or the cheapest active model for that type (see "Models" below). +2. Estimate the cost of the request (`CostEstimator`) and check it against the remaining monthly budget (`BudgetGuard`) *before* calling Runware. +3. Call the API (`RunwareClient`) and persist a `Generation` row with the result. +4. Reconcile the estimate with the real cost Runware reports and convert it to EUR. -Laravel is accessible, powerful, and provides tools required for large, robust applications. +Image and text generation run synchronously in the request. Video is different — Runware generates it asynchronously, so submitting a video prompt queues `App\Jobs\GenerateVideoJob`, which submits the task, polls Runware's `getResponse` endpoint until it's done, downloads the result, and records the final cost. All generated files are downloaded and stored on local disk (`storage/app/public`, served via the `public` symlink) rather than left on Runware's CDN. -## Learning Laravel +**Budget enforcement** (`app/Services/Runware/BudgetGuard.php`) +- A configurable hard cap in EUR (`RUNWARE_MONTHLY_CAP_EUR`, default 20) resets every calendar month. +- Every request is checked *before* it's sent: current month's spend + this request's estimated cost + a safety margin must stay under the cap, or it's rejected with no API call made. +- The check-and-reserve step is protected by an atomic cache lock, so two requests arriving at the same time can't both slip through right at the boundary. +- Runware bills in USD; conversion to EUR uses a live rate fetched daily (`CurrencyRateService`, via the free Frankfurter API) and cached, falling back to a configured static rate if the fetch ever fails — the cap never stops enforcing just because a rate refresh failed. -Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework. +**Models & pricing** (`app/Models/RunwareModel.php`, `/runware-models`) +Runware's model-search API doesn't return pricing, so there's no way to discover "the cheapest model" from their API directly. Instead, models are entered locally (AIR id, label, unit, USD price) through the `/runware-models` admin page, and the cheapest *active* model per type is automatically flagged as the default whenever a model is added, updated, or removed — no manual "set default" step. -In addition, [Laracasts](https://laracasts.com) contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library. +## Stack -You can also watch bite-sized lessons with real-world projects on [Laravel Learn](https://laravel.com/learn), where you will be guided through building a Laravel application from scratch while learning PHP fundamentals. +Laravel 13, MySQL in production (a local sqlite fallback is used when the shared dev DB is unavailable — see `.env`), Blade + Tailwind (no frontend framework), local disk storage for generated media, database-backed queue for the video job. -## Agentic Development +## Routes -Laravel's predictable structure and conventions make it ideal for AI coding agents like Claude Code, Cursor, and GitHub Copilot. Install [Laravel Boost](https://laravel.com/docs/ai) to supercharge your AI workflow: +- `/generations` — submit a new generation (image/video/text) and see history + the live budget widget. +- `/runware-models` — add/activate/deactivate/delete models and their prices. + +## Setup ```bash -composer require laravel/boost --dev - -php artisan boost:install +composer install +npm install && npm run build # or npm run dev +cp .env.example .env && php artisan key:generate +php artisan migrate +php artisan storage:link ``` -Boost provides your agent 15+ tools and skills that help agents build Laravel applications while following best practices. +Set `RUNWARE_API_KEY` in `.env`, then add at least one model per type at `/runware-models` (prices from [runware.ai/pricing](https://runware.ai/pricing)). Run `php artisan queue:work` for video generations to actually process. -## Contributing +## Tests -Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions). +```bash +php artisan test +``` -## Code of Conduct - -In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct). - -## Security Vulnerabilities - -If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed. - -## License - -The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT). +Runware calls are mocked with `Http::fake()` in `tests/Feature/GenerationServiceTest.php` and `RunwareModelDefaultTest.php` — no API key needed to run the suite.