Attainly/ai/frontend-context.md

Frontend context

Read ai/shared.md first. This file covers frontend-specific rules.

Current state

The Vue frontend has not been scaffolded yet. The backend has Inertia Laravel installed and an Inertia route, but there is no package.json, Vue source tree, Vite configuration, or frontend test setup.

• Do not create the frontend unless the user explicitly asks.
• Do not invent a frontend directory, package manager, dependency version, or command before the scaffold establishes it.
• When the frontend is created, update this file with its actual paths, package versions, scripts, and testing tools.

Vue conventions

Apply these rules once a Vue 3 frontend exists:

• Use the Composition API and <script setup lang="ts">.
• Use PascalCase component filenames.
• Keep page, component, composable, and store responsibilities distinct.
• Prefer small components with explicit props and emitted events.
• Keep component styles scoped unless the scaffold establishes a deliberate global styling system.
• Follow the routing and page conventions established by the chosen Inertia or Vue Router scaffold. Do not mix the two approaches without an explicit architectural reason.
• Inspect similar files before introducing a new component, composable, store, or data-access pattern.

TypeScript

• Enable and preserve strict mode.
• Do not use any. Model unknown external values as unknown and narrow or validate them.
• Derive types from runtime schemas when a schema library is adopted. Do not maintain a hand-written type that can drift from its validation schema.
• Validate payloads at trust boundaries, especially backend responses and user-submitted forms.
• Keep request and response types close to the API or store boundary that owns them.
• Add a path alias only when it is configured consistently in Vite, TypeScript, tests, and Cypress.

State and API access

• Use the state-management approach chosen by the scaffold consistently.
• Keep server data fetching and transformation at an API/store boundary, not scattered through presentation components.
• Represent loading, empty, success, validation-error, and unexpected-error states explicitly.
• Do not cast unchecked JSON directly to an application interface.
• Keep read and write payload types separate when their shapes differ.

Testing

Use layered tests once the frontend test setup exists:

• Unit tests cover pure transformations, composables, store logic, computed values, and formatting.
• Component tests cover rendering, events, form behavior, and conditional UI.
• Cypress tests cover routing, multi-page flows, and request wiring.
• Prefer the cheapest layer that proves the behavior.
• Import test functions explicitly rather than relying on globals unless the scaffold deliberately configures globals.
• Build test data with small typed builders instead of repeated bare object literals.

Frontend/backend test boundary

• Mock backend requests in frontend tests.
• A frontend test should verify how the UI consumes a response and which request it sends, not retest Laravel's business rules.
• Test backend persistence, validation, authentication, and mail behavior in PHPUnit.
• Keep mocked response bodies typed against the frontend's exported API or store types.
• When runtime schemas exist, parse mock-builder output through the same schema so drift fails at the test boundary.

Before completing frontend work

• Run the formatter, linter, type checker, unit tests, and Cypress scripts defined by the frontend's package.json.
• Do not substitute a hand-picked subset for the repository's eventual full frontend gate.
• If the frontend cannot run because the scaffold or a required service is absent, report the precise environmental or baseline failure.