Files

Tom Trappmann b3685e2048 bug fixing

2026-02-02 23:00:18 +01:00

6.4 KiB

Raw Blame History

Agent Instructions — Codex (Nuxt 3 + FastAPI, Greenfield, Mock-First)

This repository contains a Nuxt 3 frontend. A FastAPI backend will be developed in parallel (may be in a separate repo/service).

You are an automated coding agent (Codex).

Your job is to make precise, minimal, correct changes while strictly following these rules. Do not guess. If required information is missing, stop and ask one clear question.

This is an early-stage project. Prefer simple, explicit patterns.

Repository Structure

Root directory:
- Deployment artifacts: Dockerfile, deploy/docker-compose.yml
- Nuxt application lives in NautilusDeskTimeFrontend/
NautilusDeskTimeFrontend/app/
- Nuxt application source (pages, layouts, components, composables)
NautilusDeskTimeFrontend/server/
- Nuxt/Nitro server code may exist
- Backend business logic belongs in FastAPI, not here
NautilusDeskTimeFrontend/public/
- Static assets served as-is
Generated output (DO NOT EDIT):
- NautilusDeskTimeFrontend/.nuxt/
- NautilusDeskTimeFrontend/.output/

Commands (Frontend)

Run all frontend commands from NautilusDeskTimeFrontend/.

npm install
npm run dev (http://localhost:3000)
npm run build
npm run preview
npm run generate (if used)

Do not modify build scripts unless explicitly instructed.

Tech Stack

Frontend:

Nuxt 3
Vue 3 (Composition API only)
TypeScript
Vite
Tailwind CSS
Plain CSS is allowed when needed

Backend (separate service):

FastAPI
JWT authentication

Do not introduce new dependencies unless explicitly requested.

Global Coding Rules (Strict)

Prefer clarity over abstraction
Keep diffs small and scoped
Do not refactor unless asked
Do not change behavior unless asked
Do not remove code unless instructed
Avoid speculative features
Do not add comments explaining obvious code

When no established pattern exists yet:

introduce a simple, conventional pattern
apply it consistently
do not over-engineer

Vue & Nuxt Conventions

Components

Use <script setup lang="ts">
No Options API
No class-based components
Props and emits must be typed
Avoid any and unsafe casts
Components must do one job

Pages & Routing

Use Nuxt file-based routing
Page files in app/pages/ use lowercase filenames
Use definePageMeta for layout, middleware, SEO
Do not manually configure routes

Composables

Prefix composables with use
No side effects at import time
Return only what is required
Keep UI concerns out of composables

Backend Integration (FastAPI)

Source of Truth

Backend business logic will live in FastAPI
Do not create new /server/api/* endpoints in Nuxt unless explicitly instructed
Nuxt server code is infrastructure only (optional proxy/SSR helpers)

API Contract & Mocking (IMPORTANT)

The FastAPI API may not exist yet.
If OpenAPI schema is not available, use mock data to build the frontend.

Rules for mock data:

Mock data must be centralized in a single place (e.g. app/mocks/).
Mocks should match likely real shapes (typed interfaces).
Switching from mock to real API must be easy:
- Use a single API layer (e.g. app/composables/useApi.ts or app/services/api/).
- Pages/components must not directly embed mock fixtures.
Prefer feature flags via runtime config (e.g. useMockApi) only if needed.
Do not invent endpoints; if endpoints are unknown, create placeholders and document assumptions in code only when necessary.

API Access

Use $fetch for HTTP calls from composables/stores.
Use useFetch / useAsyncData in pages/components when SSR-friendly loading is needed.
Do not hardcode hostnames/ports.

Configuration

FastAPI base URL must come from runtime config or environment variables.
If config keys do not exist yet, create them in nuxt.config using conventional names:
- runtimeConfig.public.apiBaseUrl
Keep client-only values in runtimeConfig.public.

Authentication (JWT)

JWT will be used for authentication.

Rules:

Do not assume token storage strategy unless specified.
Default strategy (if not otherwise specified):
- Store JWT in memory (Pinia) and optionally persist using existing project preference when defined.
Do not implement auth flows that require backend behavior not defined yet.
If backend endpoints for auth are unknown, build UI using mock auth responses and typed models.

When adding auth:

Centralize token attach logic in the API layer (single place).
Do not sprinkle Authorization header logic across components.
Use Authorization: Bearer <token> when making authenticated requests.

If any auth detail is unclear (login endpoint, refresh tokens, expiry behavior):

Stop and ask one question.

State Management

Use Pinia only if needed and keep it minimal
One store per domain
Setup-style stores only
Handle async errors explicitly
Stores must not manipulate the DOM

Styling

Use Tailwind by default
Plain CSS is allowed when needed
Avoid inline styles unless unavoidable
Keep .vue indentation at 4 spaces

TypeScript Rules

Be explicit with types
Prefer narrowing over casting
Avoid any
Avoid as unknown as

Testing & Validation

No test framework is configured yet
Validate changes by running npm run dev
Manually exercise affected routes/features
If tests are added, document how to run them

Git Rules (MANDATORY)

For every logical change:

Make the change
git status must be clean after commit
Commit with a concise imperative message