73 lines
4.6 KiB
Markdown
73 lines
4.6 KiB
Markdown
---
|
|
name: project-route-structure
|
|
description: "Always apply in this project when creating, moving, or refactoring Laravel route definitions in routes/**/*.php; changing route prefixes, names, middleware, scoped bindings, or route files; or adding frontend-facing endpoints that Wayfinder generates. Documents the KanbanGit route-file layout and grouping conventions."
|
|
---
|
|
|
|
# Project Route Structure
|
|
|
|
## When to Apply
|
|
|
|
Activate this skill whenever work in this project changes:
|
|
|
|
- `routes/**/*.php`
|
|
- Route names, URI prefixes, middleware groups, scoped bindings, or controller route registrations
|
|
- Frontend-facing endpoints that require regenerated Wayfinder output
|
|
|
|
Use this together with `laravel-best-practices`. Also activate `wayfinder-development` when route changes affect generated frontend route/action imports.
|
|
|
|
## Route Files
|
|
|
|
- `routes/web.php` is the web entry point only. Keep public shell routes here, such as `home` and `dashboard`, then require domain route files.
|
|
- `routes/web/projects.php` owns the main `projects.*` structure.
|
|
- `routes/web/admin.php` owns all `admin.*` routes.
|
|
- `routes/web/teams.php` owns all `teams.*` routes.
|
|
- `routes/web/settings.php` owns account settings routes, but keeps their existing route names such as `profile.edit`, `security.edit`, and `git-connections.edit`.
|
|
- `routes/web/project/*.php` contains larger nested project route sections that would make `routes/web/projects.php` too deeply indented.
|
|
|
|
Add a new route file only when a domain gets large enough to stand alone. Otherwise, extend the existing domain file.
|
|
|
|
## Grouping Pattern
|
|
|
|
- Put shared middleware, URI prefixes, route name prefixes, and controller declarations on groups instead of repeating them on each route.
|
|
- Prefer this nesting order when it reads naturally: `middleware(...)`, `prefix(...)`, `name(...)`, `controller(...)`, then `group(...)`.
|
|
- Keep public route names stable unless the user explicitly asks for a public interface change.
|
|
- Keep route URIs stable when reorganizing route files; this kind of change should be structural.
|
|
- Use `function (): void` for route group closures.
|
|
- For large nested sections, keep the structural group in the parent file and `require` a child file from inside the group. For example, keep `Route::prefix('tickets')->name('tickets.')->group(...)` in `routes/web/projects.php`, then require `routes/web/project/tickets.php` inside it.
|
|
|
|
## Project Routes
|
|
|
|
Project routes should follow this shape:
|
|
|
|
- Top-level group: `middleware(['auth', 'verified'])`, `prefix('projects')`, `name('projects.')`.
|
|
- Project create/store routes live under `can:create-project`.
|
|
- Routes under `{project}` use project gates by capability:
|
|
- Read pages: `can:view-project,project`
|
|
- Mutations: `can:write-project,project`
|
|
- Project settings and access management: `can:admin-project,project`
|
|
- Project delete: `can:access-admin`
|
|
- `projects/{project}/permissions/...` must not be inside `Route::scopeBindings()`, because `Project` does not define `users()` or `teams()` child relationships.
|
|
- Use `Route::scopeBindings()` only around nested project resources that should bind through project-owned relationships, such as tickets and project settings children.
|
|
- Keep the outer `{project}` group in `routes/web/projects.php`; it is part of the main project structure.
|
|
- Keep compact view routes, such as show, board, and backlog, directly in `routes/web/projects.php`.
|
|
- Keep ticket subroutes grouped under `tickets.` in `routes/web/projects.php`, with the route contents in `routes/web/project/tickets.php`.
|
|
- Keep settings subroutes grouped under `settings.` in `routes/web/projects.php`, with the route contents in `routes/web/project/settings.php`.
|
|
- Split dense settings subsections further under `routes/web/project/settings/`, such as `board.php`, `metadata.php`, and `repositories.php`.
|
|
|
|
## Settings Routes
|
|
|
|
- Keep the `settings` URI prefix grouped.
|
|
- Keep profile edit/update behind `auth` only.
|
|
- Keep profile deletion, security, git connections, and appearance behind `auth` plus `verified`.
|
|
- Do not rename settings routes to a `settings.*` namespace unless the frontend/tests are intentionally updated.
|
|
|
|
## Verification
|
|
|
|
After changing route files:
|
|
|
|
1. Run `php artisan route:list --except-vendor`.
|
|
2. Run `php artisan wayfinder:generate --with-form --no-interaction` when any route signature, name, method, or controller action changed.
|
|
3. Run `vendor/bin/pint --dirty --format agent` for PHP route formatting.
|
|
4. Run the affected feature tests, usually `php artisan test --compact tests/Feature/Projects tests/Feature/Teams tests/Feature/Admin tests/Feature/Settings`.
|
|
5. Run `git diff --check` before finalizing.
|