Revise and expand Copilot instructions for Endurain

Major update to .github/copilot-instructions.md: adds explicit AI/Copilot behavior guidelines, clarifies frontend/backend/Docker workflows, introduces detailed code quality and accessibility standards, and provides a comprehensive code review checklist. The document now includes a 10-section Vue component structure, centralized utility usage, and updated architecture and refactoring priorities to guide consistent, high-quality development.
2026-01-09 15:57:59 -05:00 · 2025-10-10 14:13:15 +01:00
parent 72f379d33b
commit f92d19cef4
1 changed files with 217 additions and 80 deletions
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -2,134 +2,271 @@

 Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.

+---
+
+## AI / Copilot Behavior Guidelines
+
+- Always follow instructions in this file before inferring new patterns.
+- Do **not** suggest changes to Dockerfiles or CI/CD workflows unless they clearly violate instructions here.
+- For Vue components:
+  - Use `<script setup lang="ts">` syntax.
+  - Follow the 10-section component structure.
+  - Prefer utilities from `/utils` and constants from `/constants`.
+- Do not alter port numbers, environment variables, or framework versions unless explicitly instructed.
+- Prefer using existing validation, constants, and type files rather than creating new ones.
+- Use the timing benchmarks in this document to evaluate build success or performance anomalies.
+
+---
+
 ## Working Effectively

-Endurain is a self-hosted fitness tracking application built with Vue.js frontend, Python FastAPI backend, and supports PostgreSQL databases. The primary development approach uses Docker, but frontend-only development is supported.
+Endurain is a self-hosted fitness tracking application built with Vue.js frontend, Python FastAPI backend, and PostgreSQL database. The primary development workflow uses Docker, but frontend-only development is supported for faster UI iteration.

 ### Prerequisites and Environment Setup
- Requires Node.js (tested with v20.19.4) for frontend development
- Backend requires Python 3.13 (system may have 3.12, use Docker for backend)
- Docker required for full-stack development and building
- Poetry for Python dependency management (if developing backend locally)
+
+- **Node.js:** v20.19.4 (for frontend)
+- **Python:** v3.13 (backend)
+- **Docker:** required for full-stack development and CI/CD builds
+- **Poetry:** for backend dependency management (when not using Docker)

 ### Quick Start Development Setup
+
 1. Clone repository: `git clone https://github.com/joaovitoriasilva/endurain.git`
-2. Navigate to project root
+2. Navigate to the project root
 3. Choose development approach:
-   - **Frontend Only**: See Frontend Development section below
-   - **Full Stack**: Use Docker development setup
+   - **Frontend Only** – see _Frontend Development_
+   - **Full Stack** – use _Docker Development Setup_

 ### Frontend Development (Recommended for UI changes)
- Navigate to frontend directory: `cd frontend/app`
- Install dependencies: `npm install` -- takes 21 seconds
- Build frontend: `npm run build` -- takes 9 seconds
- Start dev server: `npm run dev` -- runs on port 5173 (or 5174 if occupied)
- Format code: `npm run format` -- takes 6 seconds, ALWAYS run before committing
- **Note**: ESLint configuration needs migration to flat config format, lint command currently fails
- **Note**: No unit tests exist yet (`npm run test:unit` exits with "No test files found")
+
+- Navigate: `cd frontend/app`
+- Install dependencies: `npm install` (≈20 seconds)
+- Start dev server: `npm run dev` (port 5173 or 5174 if occupied)
+- Build frontend: `npm run build` (≈9 seconds)
+- Format code: `npm run format` (≈5 seconds)
+- **Note:** ESLint configuration pending migration to flat config format (lint fails currently)
+- **Note:** Unit tests not yet implemented (`npm run test:unit` exits with “No test files found”)

 ### Docker Development (Full Stack)
+
 - Build unified image: `docker build -f docker/Dockerfile -t unified-image .`
- **CRITICAL WARNING**: Docker build may fail due to SSL certificate issues in CI environments
- **NEVER CANCEL**: Docker builds can take 15+ minutes. NEVER CANCEL. Set timeout to 60+ minutes.
- Create docker-compose.yml based on docker-compose.yml.example
+- **Caution:** Docker builds may take 15–20 minutes. Avoid canceling unless hung for 30+ minutes.
+- **CI Caveat:** SSL certificate errors can occur during CI builds; document but don’t bypass validation.
+- Create docker-compose.yml from the provided example.
 - Start services: `docker compose up -d`
 - Stop services: `docker compose down`

 ### Backend Development (Advanced)
- Backend uses Python 3.13 with Poetry for dependency management
- Located in `backend/` directory with `pyproject.toml`
- **Important**: Local backend development requires Python 3.13, use Docker if system has 3.12
- Install Poetry if needed: `pip install poetry`
+
+- Python 3.13 backend managed by Poetry
+- Codebase in `backend/` with `pyproject.toml`
+- Use Docker if system Python < 3.13
+- Install Poetry: `pip install poetry`
 - Install dependencies: `poetry install`

+#### Backend Code Quality Standards
+
+- Use type hints (`def foo(x: int) -> str:`)
+- Standard FastAPI project layout: `routers/`, `schemas/`, `services/`, `models/`
+- Public functions/classes must have docstrings
+- Core logic should live in `services/`, not routers
+- Format with `black` and `isort`
+- Include at least one unit test per router or service
+
+---
+
 ## Validation

 ### Manual Testing Validation
- **CRITICAL**: Always test login page loads correctly at `http://localhost:5173/login` or `http://localhost:5174/login`
- Verify that the Endurain logo, username/password fields, and "Sign in" button appear correctly
- Check that the footer displays version information and integration badges
- **Screenshot validation**: The application should look like a clean, modern fitness tracking login page with blue "Sign in" button and Strava/Garmin Connect compatibility badges
+
+- Visit login page at `http://localhost:5173/login` or `:5174`
+- Verify: logo, username/password fields, “Sign in” button
+- Footer must display version and integration badges
+- Screenshot validation: clean, modern UI with blue sign-in button and Strava/Garmin compatibility

 ### Docker Validation
- If Docker builds fail with SSL errors, document the limitation but do not skip validation
- Test that built image starts correctly (even if SSL prevents building in CI)
+
+- Document SSL issues but complete functional validation
+- Ensure built container runs successfully (even if CI SSL fails)

 ### Pre-commit Validation
- ALWAYS run `npm run format` in frontend/app before committing
- Verify frontend builds successfully with `npm run build`
- Check that development server starts without errors
+
+- Run `npm run format` before commits
+- Confirm successful `npm run build`
+- Ensure `npm run dev` runs without warnings/errors
+
+---

 ## Common Tasks

 ### File Locations and Structure
-```
+
+```plaintext
 Repository root:
 ├── frontend/app/          # Vue.js frontend application
 │   ├── package.json       # Frontend dependencies and scripts
 │   ├── src/               # Vue.js source code
-│   ├── dist/              # Built frontend (after npm run build)
-│   └── vite.config.js     # Vite build configuration
+│   ├── dist/              # Built frontend output
+│   └── vite.config.js     # Vite configuration
 ├── backend/               # Python FastAPI backend
-│   ├── pyproject.toml     # Python dependencies (Poetry)
-│   └── app/               # FastAPI application code
+│   ├── pyproject.toml     # Poetry dependencies
+│   └── app/               # FastAPI application source
 ├── docker/
-│   ├── Dockerfile         # Multi-stage Docker build
-│   └── start.sh           # Container entrypoint script
+│   ├── Dockerfile         # Multi-stage build definition
+│   └── start.sh           # Entrypoint script
 ├── docs/                  # Documentation
 ├── .github/workflows/     # CI/CD pipelines
 ├── docker-compose.yml.example
 └── .env.example
 ```

-### Key Commands and Timing (VALIDATED)
- `npm install` (frontend): 5-21 seconds (depends on cache)
- `npm run build` (frontend): 9 seconds 
- `npm run format` (frontend): 2-6 seconds (formats all source files)
- `npm run dev` (frontend): starts in ~1 second, runs on port 5173/5174
- Docker builds: **15+ minutes, NEVER CANCEL, set 60+ minute timeouts**
+### Key Commands and Timing

-### Frequently Modified Files
- Frontend components: `frontend/app/src/components/`
- Vue.js views: `frontend/app/src/views/`
- Frontend services: `frontend/app/src/services/`
- Frontend utilities: `frontend/app/src/utils/`
- API backend: `backend/app/`
+| Command          | Description             | Typical Duration |
+| ---------------- | ----------------------- | ---------------- |
+| `npm install`    | Installs frontend deps  | 5–21 s           |
+| `npm run build`  | Builds frontend         | 9 s              |
+| `npm run format` | Formats code            | 2–6 s            |
+| `npm run dev`    | Starts dev server       | \~1 s            |
+| `docker build`   | Builds full stack image | 15–20 min        |

-### Known Issues and Limitations
- ESLint requires migration to flat config format (currently fails)
- Docker builds may fail with SSL certificate errors in CI environments
- Backend requires Python 3.13 (may not match system Python 3.12)
- No unit tests currently exist for frontend
- Frontend lint command fails, use format command instead
+---

-### Environment Variables and Configuration
- Frontend uses VITE_ENDURAIN_HOST environment variable
- Create `.env.local` in frontend/app with: `VITE_ENDURAIN_HOST=http://localhost:8080`
- Backend configuration via environment variables (see .env.example)
- Default credentials: admin/admin
+## Known Issues

-### CI/CD Information
- GitHub Actions workflows in `.github/workflows/`
- Docker image builds on release and manual trigger
- Multi-architecture builds (linux/amd64, linux/arm64)
- Published to GitHub Container Registry
+- ESLint migration to flat config pending
+- Docker builds may fail with SSL issues in CI
+- Backend Python 3.13 required
+- No frontend test coverage yet
+
+---
+
+## CI/CD Workflows
+
+- Located in `.github/workflows/`
+- Common workflows:
+  - `frontend.yml`: builds and lints frontend
+  - `docker-build.yml`: builds multi-arch Docker images (amd64, arm64)
+  - `release.yml`: publishes Docker images to GitHub Container Registry
+- Use workflow dispatch for manual triggers
+
+---
+
+## Code Quality Standards (10/10 Quality)
+
+### Frontend Component Standards
+
+#### TypeScript
+
+- Always use `<script setup lang="ts">`
+- Explicit typing for all `ref`, `computed`, and function params
+- Type imports: `Ref<T>`, `ComputedRef<T>`, `Router`, `RouteLocationNormalizedLoaded`
+- No implicit `any` types
+- Centralized imports from `/types/index.ts`
+
+#### Documentation
+
+- Each component must include a clear, purposeful JSDoc overview
+- Document complex logic; skip redundant auto-generated comments
+
+#### Component Structure (10 Sections)
+
+1. Fileoverview JSDoc
+2. Imports
+3. Composables & Stores
+4. Reactive State
+5. Computed Properties
+6. UI Interaction Handlers
+7. Validation Logic
+8. Main Logic
+9. Lifecycle Hooks
+10. Component Definition
+
+#### Centralized Architecture
+
+- **Validation utilities:** `/utils/validationUtils.ts`
+  - `isValidPassword()`, `passwordsMatch()`, `isValidEmail()`, `sanitizeInput()`
+  - Password strength analysis functions
+- **Constants:** `/constants/httpConstants.ts`
+  - `HTTP_STATUS` enum for status codes
+  - `extractStatusCode()` for error response parsing
+  - `QUERY_PARAM_TRUE` for URL parameters
+- **Type definitions:** `/types/index.ts`
+  - `ErrorWithResponse`, `NotificationType`, `ActionButtonType`
+- **Bootstrap modals:** `/composables/useBootstrapModal.ts`
+  - Modal lifecycle management
+
+#### UI/UX Standards
+
+- Use Bootstrap 5 `form-floating` classes
+- Accessibility:
+  - All interactive elements must have `aria-label`
+  - Use `aria-live="polite"` for validation messages
+  - Ensure full keyboard navigation
+- Responsive across mobile, tablet, desktop
+- Always include loading states and graceful error handling
+
+#### Accessibility Testing Checklist
+
+- Verify tab navigation for all forms
+- Check color contrast meets WCAG AA
+- Validate `aria-label` coverage
+- Confirm focus outlines visible and consistent
+- Test screen reader compatibility (NVDA/VoiceOver)
+
+#### Reference Implementations (10/10 Quality)
+
+Study these files as templates when creating/refactoring components:
+
+- **LoginView.vue** (437 lines) - Authentication with MFA support
+- **SignUpView.vue** (611 lines) - Registration with optional fields
+- **ResetPasswordView.vue** (~320 lines) - Password reset with token validation
+- **ModalComponentEmailInput.vue** - RFC 5322 email validation
+
+---
+
+## Code Review Checklist
+
+- ✅ TypeScript with explicit types
+- ✅ Meaningful JSDoc documentation
+- ✅ 10-section component structure
+- ✅ Centralized use of validation/constants/types
+- ✅ Bootstrap 5 form-floating usage
+- ✅ Accessibility attributes verified
+- ✅ Code formatted successfully (`npm run format`)
+- ✅ Build passes (`npm run build`)
+- ✅ Manual browser validation complete
+- ✅ No console warnings/errors
+
+---

 ## Development Workflow
-1. Make changes to frontend files in `frontend/app/src/`
-2. Test with `npm run dev` to verify changes work
-3. Run `npm run format` to format code
-4. Build with `npm run build` to ensure production build works
-5. For backend changes, use Docker development setup
-6. Always test manually by accessing the application in browser
+
+1. Edit code in `frontend/app/src/`
+2. Run `npm run dev` to test locally
+3. Run `npm run format` before commit
+4. Build production output with `npm run build`
+5. For backend changes, use Docker setup
+6. Validate full UI flow manually
+
+---

 ## Architecture Notes
- **Frontend**: Vue.js 3 with Vite, Bootstrap CSS, Chart.js, Leaflet maps
- **Backend**: Python FastAPI with SQLAlchemy, Alembic migrations
- **Database**: PostgreSQL support
- **Integrations**: Strava and Garmin Connect APIs
- **File Support**: .gpx, .tcx, .fit file imports
- **Authentication**: JWT tokens with 15-minute access tokens
- **Deployment**: Docker containers with multi-stage builds

-Always prioritize frontend development workflow for UI changes and use Docker for full-stack development.
+- **Frontend:** Vue.js 3, Vite, Bootstrap 5, Chart.js, Leaflet
+- **Backend:** FastAPI, SQLAlchemy, Alembic
+- **Database:** PostgreSQL
+- **Integrations:** Strava, Garmin Connect
+- **File Imports:** .gpx, .tcx, .fit
+- **Auth:** JWT with 15-minute access tokens
+- **Deployment:** Docker multi-stage builds, multi-architecture images
+
+---
+
+## Refactoring Priority
+
+1. Authentication flows (login/signup/reset)
+2. Settings (profile/security/integrations)
+3. Activity views (list/detail/edit)
+4. Reusable modals
+5. Utility and validation logic