​
Dashboard Feature Template

​
Status

  • document type: implementation template
  • use this page when an agent needs a default blueprint for a new dashboard feature

​
Goal

Provide a default module shape so an agent does not invent a new structure every time it creates a dashboard feature.

​
Use This Template For

  • new dashboard pages
  • new embedded dashboard workflows
  • new shared feature modules with API, state, and reusable components

​
Default Module Shape

app/javascript/dashboard/
  api/<feature>.js
  stores/<feature>.js
  composables/use<Feature>.js
  components-next/<Feature>/
  routes/dashboard/<feature>/

​
File Placement Rules

​
api/<feature>.js

Create an API client when the feature talks to account-scoped backend endpoints. Typical responsibilities:
  • list
  • show
  • create
  • update
  • delete
  • search or filter helpers

​
stores/<feature>.js

Create a Pinia store when the feature has shared entity state, UI flags, pagination, or CRUD behavior. Prefer dashboard/store/storeFactory.js when the CRUD shape matches existing patterns.

​
composables/use<Feature>.js

Create a composable when the feature has reusable logic such as:
  • derived filters
  • keyboard behavior
  • date formatting and view state
  • bridge logic to legacy Vuex

​
components-next/<Feature>/

Use this folder for:
  • reusable feature blocks
  • cards
  • form sections
  • sidebars
  • rows
  • tiles
  • wrappers around approved third-party primitives

​
routes/dashboard/<feature>/

Use route-local components for:
  • page composition
  • route-specific filters and panels
  • feature flows that are not yet reusable elsewhere

​
Example Blueprint

app/javascript/dashboard/
  api/scheduling.js
  stores/scheduling.js
  composables/useSchedulingFilters.js
  components-next/Scheduling/
    SchedulingHeader.vue
    AppointmentCard.vue
    ResourceColumn.vue
    AppointmentDialog.vue
  routes/dashboard/scheduling/
    Index.vue
    SchedulingPage.vue

​
Reuse Rules Inside A New Module

  • reuse existing shared primitives from components-next first
  • keep feature-specific composition local to the module
  • only promote route-local pieces into components-next after real reuse appears

​
Default Implementation Sequence

  1. backend contract exists or is agreed
  2. create the API client
  3. create the store or composables
  4. identify reusable UI already present in components-next
  5. create missing shared feature components
  6. compose the route page or embedded workflow
  7. add i18n and verification

​
Verification Template

For a normal feature, the minimum verification path is:
  • targeted manual smoke in the dashboard
  • Histoire story for reusable components if the feature adds them
  • targeted Vitest coverage for API client, store, or non-trivial composable when useful

​
What Not To Do

  • do not put every component directly under routes/ if parts are clearly reusable
  • do not create a new parallel shared UI folder outside components-next
  • do not create a new feature store in Vuex
  • do not start with external libraries before checking internal reuse