Skip to content

AI Development Rules

Canonical rules are maintained in /.github/AI_RULES.md.

This file is kept for the public documentation site; to change behavior for automation and agents, edit /.github/AI_RULES.md instead.

For convenience you can open the canonical file directly (Status bar macro / scripts/open-ai-rules.ps1).

Yann's rules, before anyhting else, follow those:

  • Keep your comment to the minimum
  • Do not show me your code
  • Do not explain your code or you solution
  • do not show me the detailsbig of the cause of the problem.
  • Do not provide details on the fixc you apply.
  • Always remember I might be running multiple ai chat at the same time and that when you're using to many words in your response, I will not read them because I'm switching fast between each ai chat.
  • Do not try to fix the issues that you see on build if there are NOT caused by what you are currently working on. because it probably mean that it is already handled by another ai chat.
  • Always verify your code after a modification
  • If a fix is required, do it. Do not ask if you need to fix
  • When db change is required, create the .sql file in migrations and run the db push or other cli required. If it fails, fix it wihtout asking if you want it to be fixed.
  • if a db modification is required, validate if you need other db modification. You need to think ahead and not progress one small element at a time.
  • Anticipae reading and fixing the errors coming in the PROBLEMS tab
  • Access all the log infomration you can find to understand the errors.
  • When you get an error in a file, ix the error but also inspect the whole file for errors before ending you work.
  • if I put a ?, that mean I have a question, so do not execute anything yet
  • when you need to build or start next server, beware that server might be running already, so you would need to kill port 3000 before.
  • Keep documentations up to date.
  • Do not put documentation outside of /docs.
  • My first name is Yann and I speak french
  • unless it does not make sense or it could cause more bugs, use only french slug name, filenames etc. in your coding.

Tech Stack Overview

The application is built using the following core technologies:

  • Framework: Next.js (App Router)
  • Language: TypeScript
  • UI Components: Shadcn/UI - A collection of re-usable UI components built with Radix UI and Tailwind CSS.
  • Styling: Tailwind CSS - A utility-first CSS framework for rapid UI development.
  • Icons: Lucide React - A comprehensive library of simply beautiful SVG icons.
  • Forms: React Hook Form for managing form state and validation, typically with Zod for schema validation.
  • State Management: Primarily React Context API and built-in React hooks (useState, useReducer).
  • Notifications/Toasts: Sonner for displaying non-intrusive notifications.
  • Charts: Recharts for data visualization.
  • Animation: tailwindcss-animate and animation capabilities built into Radix UI components.

Library Usage Guidelines

To ensure consistency and leverage the chosen stack effectively, please follow these rules:

  1. UI Components:

    • Primary Choice: Always prioritize using components from the src/components/ui/ directory (Shadcn/UI components).
    • Custom Components: If a required component is not available in Shadcn/UI, create a new component in src/components/ following Shadcn/UI's composition patterns (i.e., building on Radix UI primitives and styled with Tailwind CSS).
    • Avoid: Introducing new, third-party UI component libraries without discussion.

  2. Styling:

    • Primary Choice: Exclusively use Tailwind CSS utility classes for all styling.
    • Global Styles: Reserve src/app/globals.css for base Tailwind directives, global CSS variable definitions, and minimal base styling. Avoid adding component-specific styles here.
    • CSS-in-JS: Do not use CSS-in-JS libraries (e.g., Styled Components, Emotion).

  3. Icons:

    • Primary Choice: Use icons from the lucide-react library.

  4. Forms:

    • Management: Use react-hook-form for all form logic (state, validation, submission).
    • Validation: Use zod for schema-based validation with react-hook-form via @hookform/resolvers.

  5. State Management:

    • Local State: Use React's useState and useReducer hooks for component-level state.
    • Shared/Global State: For state shared between multiple components, prefer React Context API.
    • Complex Global State: If application state becomes significantly complex, discuss the potential introduction of a dedicated state management library (e.g., Zustand, Jotai) before implementing.

  6. Routing:

    • Utilize the Next.js App Router (file-system based routing in the src/app/ directory).

  7. API Calls & Data Fetching:

    • Client-Side: Use the native fetch API or a simple wrapper around it.
    • Server-Side (Next.js): Leverage Next.js Route Handlers (in src/app/api/) or Server Actions for server-side logic and data fetching.

  8. Animations:

    • Use tailwindcss-animate plugin and the animation utilities provided by Radix UI components.

  9. Notifications/Toasts:

    • Use the Sonner component (from src/components/ui/sonner.tsx) for all toast notifications.

  10. Charts & Data Visualization:

    • Use recharts and its associated components (e.g., src/components/ui/chart.tsx) for displaying charts.

  11. Utility Functions:

    • General-purpose helper functions should be placed in src/lib/utils.ts.
    • Ensure functions are well-typed and serve a clear, reusable purpose.

  12. Custom Hooks:

    • Custom React hooks should be placed in the src/hooks/ directory (e.g., src/hooks/use-mobile.tsx).

  13. TypeScript:

    • Write all new code in TypeScript.
    • Strive for strong typing and leverage TypeScript's features to improve code quality and maintainability. Avoid using any where possible.

  14. Android (Capacitor) – Repo Safety

    • The android/ project is versioned in Git. Prefer fixing Gradle/manifest issues in-repo so builds are reproducible.
    • Never add/commit machine-specific or secret files:
    • android/local.properties
    • keystores: *.jks, *.keystore, becik-release-key.keystore
    • any service-account keys or secret JSON files
    • It is OK to commit stable Android build config: Gradle files, manifests, resources, wrapper, and scripts.
    • When asked to fix Android build errors, prefer ./gradlew :app:assembleDebug --stacktrace and keep changes minimal.

By following these guidelines, we can build a more robust, maintainable, and consistent application.

Long‑Running Features & Current Status (2026‑01‑08)

This section is for the AI to remember multi‑step features that span several sessions.

1. Maintenance Notifications (email + push)

Goal: Remind users when bike maintenance is due, via email and web push.

Database / Backend (DONE)

  • Migration 20260111_notifications_and_maintenance_reminders.sql adds:
  • user_profiles extensions: contact_email, notify_email_enabled, notify_push_enabled, timezone.
  • push_subscriptions (per-device web push subscriptions).
  • notification_preferences (per-user email/push/quiet-hours, categories).
  • maintenance_reminders (rules per user/bike/task, keyed by task_key).
  • notification_events (queue/audit of notifications to send).
  • API routes:
  • /api/notifications/push-subscribe → saves web push subscriptions for current user.
  • /api/notifications/preferences → GET/POST notification preferences for current user.
  • /api/maintenance/reminders → GET/POST/DELETE reminders for current user.
  • Cron endpoint:
  • /api/cron/maintenance-notifications:
    • Secured with optional CRON_SECRET env.
    • Scans active maintenance_reminders with task_key like maintenance_item:<id>.
    • Preloads maintenance_items, latest maintenance_logs, bikes, notification_preferences.
    • Computes when a reminder is due based on distance (distance_threshold_km) and/or time (time_threshold_days, lead_time_hours).
    • Enqueues notification_events for channel = 'email' and/or channel = 'push'.
  • Helper:
  • src/lib/notifications.ts → processQueuedNotificationEvents(limit) marks queued events as sent (placeholder for real senders).
  • Service worker:
  • public/notifications-sw.js handles push events and shows a simple notification.

Frontend / UI (PARTIALLY DONE)

  • Maintenance page client: src/components/maintenance/MaintenancePageClient.tsx.
  • New “Notifications d'entretien” card with two toggles:
    • Email toggle → uses /api/notifications/preferences (notify_email_enabled).
    • Push toggle → registers /notifications-sw.js, subscribes to push (requires NEXT_PUBLIC_WEB_PUSH_PUBLIC_KEY), posts to /api/notifications/push-subscribe, and updates notify_push_enabled via /api/notifications/preferences.
  • Per‑item reminder toggle in the maintenance item details card:
    • Uses task_key = "maintenance_item:<maintenance_item_id>".
    • On open: GET /api/maintenance/reminders?bikeId=<bike_id>&taskKey=<task_key> and sets local reminderEnabled based on active.
    • On toggle: POST /api/maintenance/reminders with { bike_id, task_key, rule_type, lead_time_hours: 24, active }.
    • rule_type is inferred from the maintenance item thresholds:
    • Distance only → "distance".
    • Time only → "date".
    • Both present → "both".

Remaining Work (FUTURE)

  • Wire real email sending for notification_events with channel = 'email' (e.g., Resend, SendGrid) and integrate it into a cron/handler that calls processQueuedNotificationEvents.
  • Wire real web-push sending for channel = 'push' using a VAPID-backed library.
  • Add a small “Notification settings” UI (likely under /dashboard/settings or /dashboard/maintenance) to:
  • Edit contact_email vs login email (auth email stays stable for OAuth).
  • Manage quiet hours (quiet_hours_start, quiet_hours_end, timezone).
  • Possibly surface a list of active maintenance reminders.

2. PWA / Installable App (PLANNED, NOT STARTED)

Goal: Allow Android users to “Install app” and provide a better standalone experience; iOS will use “Add to Home Screen”.

Planned Steps

  • Add public/manifest.json with app name, icons, theme/background colors, and start URL.
  • Reference manifest and meta tags in src/app/head.tsx.
  • Add a service worker for basic offline caching (could later reuse/extend notifications-sw.js or introduce next-pwa).
  • Ensure icons and theme color match the brand.
  • Optionally add a small “Install app” prompt component that listens for beforeinstallprompt and offers an install CTA on supported devices.

When continuing work later, the AI should:

  • Reuse this section as the source of truth for what is DONE vs PLANNED.
  • Avoid redesigning the schema for notifications/maintenance; build on the existing tables and task_key convention.
  • Prefer adding new cron/API handlers or UI pieces rather than changing the ones already wired, unless a bug or constraint requires it.