# Architecture Ignite is a Laravel 13 + Vue 3 app connected by Inertia.js: Laravel controllers render Vue page components directly, with no separate REST/JSON API layer for the frontend to consume. ```mermaid flowchart TD subgraph browser["Browser (SPA)"] client["Vue 3 + TypeScript + Inertia Client
Tailwind CSS"] end subgraph backend["Laravel Backend"] controllers["Controllers"] models["Models (Eloquent ORM)"] db[("PostgreSQL")] fortify["Fortify (auth)"] adapter["Inertia server-side adapter"] controllers --> models --> db fortify -.-> controllers adapter -.-> controllers end client -- "Inertia protocol (JSON over HTTP)" --> controllers ``` ## Backend ### Routes Routes are split by feature under `routes/`, not kept in one file: - `routes/web.php`: public routes and the dashboard - `routes/auth.php`: authentication (Fortify-backed) - `routes/goals.php`: goal management, including nested resources like `goals/{goal}/entries` - `routes/settings.php`: user settings Resource routes follow standard RESTful conventions and are grouped with `Route::controller(...)->group(...)` per feature. See `routes/goals.php` for the pattern. ### Controllers Grouped by feature in subdirectories under `app/Http/Controllers/`: - `Auth/`: authentication (works with Fortify's action pipeline, but ships its own controllers and Vue pages rather than Fortify's built-in views) - `Goals/`: `GoalController`, `GoalEntryController` - `Settings/`: user settings Every controller returns an Inertia response (`Inertia::render(...)`), never raw JSON, and uses route model binding for model parameters. See `app/Http/Controllers/Goals/GoalController.php` for a representative example. ### Validation Form submissions are validated by form requests under `app/Http/Requests/`, which carry both the rules and the authorization check. Rule sets shared with another entry point live in `app/Rules/` (`GoalRules`, `GoalEntryRules`, `MilestoneRules`, `CategoryRules`), so the web form and the MCP tools validate identically. Forms validate as they are filled, using [Laravel Precognition](https://laravel.com/docs/13.x/precognition), which Inertia supports out of the box. The routes involved carry the `HandlePrecognitiveRequests` middleware, and the frontend calls `validate('field')` on a field's `change` event. Precognition resolves the route's form request and then stops, so the rules are never duplicated in JavaScript and the action itself never runs. It only reaches validation performed while the controller's parameters are resolved, which is why these routes type-hint a form request rather than calling `$request->validate()` in the method body. ### Models The core data graph, all under `app/Models/`: - `Goal`: the central model. `$with` eager-loads only `category` by default. Opening a single goal goes through `GoalService::findAndLoadRelationships`, shared by the goal page and the MCP `get_goal` tool, which adds the 20 newest entries, ordered milestones, and the streak; `GoalController::show` also sends `entriesCount` with the page and a lightweight `chartEntries` set as a deferred Inertia prop (`Inertia::defer`), fetched in a second request so the page renders before the full entry history arrives. Callers that only need to resolve and authorize a record use the lean `find` method on `GoalService`, `GoalEntryService`, `MilestoneService`, or `CategoryService`, never `findOrFail` directly. Carries accessors such as `getProgressPercentageAttribute()` and methods like `markAsCompleted()`. `status` is one of `not_started`, `in_progress`, `completed`, `paused`, `abandoned`; `priority` is one of `low`, `medium`, `high`. See [Goal Types](/features/goal-types) for `type` and `direction`. - `GoalEntry`: incremental progress records tied to a goal, with a timestamp. - `Category`: user-defined grouping for goals. - `Milestone`: checkpoints that break a goal into steps. - `Theme`: a user's own primary color for the app; see [Themes](/features/themes). - `Achievement` / `UserAchievement`: gamification records. - `UserDataKey`: a user's wrapped data key, on its own connection. `Goal`, `GoalEntry`, `Milestone`, `Category` and `User` use the `EncryptsUserData` trait; see [Data Encryption](/features/encryption). Relationships are declared the standard Eloquent way (`belongsTo`, `hasMany`) on each model; see `app/Models/Goal.php` for the full relationship set and accessors. ### Middleware `HandleInertiaRequests` shares common data (auth user, locale, supported locales, flash messages) with every Inertia response. `SetLocale` resolves and applies the request locale. `HandleAppearance` supports dark mode. ## Frontend ### Directory layout ```text resources/js/ ├── app.ts / ssr.ts # entry points ├── actions/ # Wayfinder-generated actions (generated, do not edit) ├── routes/ # Wayfinder-generated route helpers (generated, do not edit) ├── wayfinder/ # Wayfinder config (generated, do not edit) ├── components/ # reusable Vue components (ui/ = shadcn-vue primitives) ├── composables/ # Vue composables (useAppearance, useTwoFactorAuth, ...) ├── layouts/ # page layout shells ├── pages/ # Inertia page components, mirroring controller structure └── types/ # TypeScript type definitions ``` Page components under `pages/` mirror the backend controller structure (e.g. `pages/Goals/{Index,Create,Edit,Show}.vue` for `GoalController`) and receive their data as props passed straight from `Inertia::render()`. ### Inertia data flow Controllers call `Inertia::render('PageName', $data)`; the matching Vue component under `resources/js/pages/` receives `$data` as props. Forms submit through Inertia's `useForm()` composable, and successful responses trigger client-side navigation without a full page reload; there is no REST client, fetch layer, or separate API schema to keep in sync. ### Wayfinder route helpers [Laravel Wayfinder](https://github.com/laravel/wayfinder) generates type-safe TypeScript route helpers from the backend route definitions, into `resources/js/routes/` and `resources/js/actions/`. This gives autocomplete and type checking for route calls in Vue components (e.g. `goals.show({ goal: id })`) instead of hand-written URL strings. These directories are generated; do not edit them directly. Configured in `vite.config.ts` with `formVariants: true`. ### TypeScript types - `resources/js/types/models.d.ts`: interfaces mirroring the Eloquent models (`Goal`, `GoalEntry`, `Category`, `Milestone`, ...) - `resources/js/types/index.d.ts`: Inertia page props and shared/global types (`User`, `PageProps`, `NavItem`, ...) - `resources/js/types/globals.d.ts`: global type declarations The path alias `@/*` maps to `resources/js/*`. ### State management There is no global state library (Pinia/Vuex) in use. Page state is owned by Inertia props, cross-cutting logic lives in composables, and local component state uses `ref()`/`reactive()`. Pinia is a candidate only if client-side state needs to persist across navigations, gets shared across many unrelated components, or real-time updates (websockets) enter the picture. ## Further reading - [Self-Hosting](/self-hosting) for how this app is actually deployed to production - [Testing](/testing) for how backend and frontend code is tested