Runnable Scenarios
Runnable scenarios show complete framework workflows inside a GoForj App.
Use these after the Quickstart when you want to build real application behavior instead of only reading individual feature pages.
If you are learning GoForj for the first time, treat this section as the main guided tutorial after Getting Started. Feature pages explain one surface at a time; scenarios show how those surfaces compose inside your App.
The Path
Seven scenarios, in order, each adding one boundary to the same App. Plan on a bit over two hours end to end, or one scenario per sitting. By the end you have a fully observable system: a tested API with caching, file storage, events, queue-backed jobs, a schedule, and operator visibility over all of it.
- JSON API Route · about 15 minutes. A route, controller, service, Wire provider, and service test.
- Cached User Profile · about 15 minutes. A repository boundary and a named cache resource.
- File Upload to Storage · about 20 minutes. Uploads written to a named storage disk.
- Users Created Event · about 25 minutes. A typed event published and handled by a subscriber.
- Reports Generate Job · about 25 minutes. Queue-backed work dispatched from the subscriber and processed by a worker; the selected driver determines durability and process reach.
- Reports Daily Schedule · about 15 minutes. The same job dispatched on a recurring cadence.
- Runtime Observability · about 15 minutes. The whole workflow followed through routes, metrics, inspects, Lighthouse, and logs.
flowchart LR route["JSON API Route"] --> cache["Cached Profile"] cache --> storage["File Upload Storage"] storage --> event["users.created Event"] event --> job["reports:generate Job"] job --> schedule["reports:daily Schedule"] schedule --> observe["Runtime Observability"]
Golden Path State
| Step | App State Before | App State After |
|---|---|---|
| JSON API Route | App with HTTP enabled | One tested user lookup route is registered and visible in route:list. |
| Cached User Profile | User route exists | User lookup has a repository boundary and named profiles cache. |
| File Upload to Storage | App has HTTP and generated storage support | Uploads write to a named uploads storage disk. |
| Users Created Event | User service owns read/write behavior | Creating a user publishes a typed users.created event and a subscriber reacts to it. |
| Reports Generate Job | Event subscriber exists | Subscriber dispatches queue-backed reports:generate work; the selected driver determines durability and process reach. |
| Reports Daily Schedule | Report job exists | reports:daily schedule dispatches the same report job on a recurring cadence. |
| Runtime Observability | API, cache, storage, event, job, and schedule paths exist | The whole workflow can be followed through routes, logs, metrics, inspects, and Lighthouse. |
How to Read These
Each scenario uses the same small internal reporting app shape.
The examples are intentionally local-first. Production drivers, distributed backends, and operational deployment notes appear only after the local path works.
Focused Workflows
Add a Database-Backed Resource is a focused, verified workflow for adding a new persistence boundary. It uses photos as a concrete example while keeping the reusable schema-first order explicit: add and apply the migration, generate the model and repository from the live schema, then extend the App-owned repository package.
After the Path
Finishing all seven leaves you with the App this whole documentation set describes. From there:
- Production Checklist when you want to ship it.
- Cookbook when you come back with a specific task.
- Apps when the Project outgrows a single app.