AI Development Guidelines

This document provides guidelines for AI assistants working on this codebase. All AI assistants MUST follow these guidelines.

⚠️ CRITICAL: Always Test Builds Before Pushing

MANDATORY RULE: Before committing and pushing any changes, you MUST:

1. Test the frontend build:

   cd apps/frontend
   npm run build
   

   • The build MUST complete successfully with exit code 0
   • Fix any TypeScript errors, ESLint errors, or build failures
   • Warnings are acceptable, but errors will block deployment

2. Test the backend build:

   cd apps/backend
   npm run build
   

   • The build MUST complete successfully
   • Fix any TypeScript errors or compilation issues

3. Only push if both builds succeed

Why This Matters

• Vercel and Railway will fail deployments if builds fail
• Catching errors locally saves time and prevents broken deployments
• Build errors are easier to fix locally than debugging in CI/CD

Build Checklist

Before every commit/push:

• Frontend builds successfully (cd apps/frontend && npm run build)
• Backend builds successfully (cd apps/backend && npm run build)
• No TypeScript errors
• No ESLint errors (warnings OK)
• All pages can be pre-rendered (no Suspense boundary errors)

Code Quality Standards

TypeScript

• All code must be properly typed
• No any types unless absolutely necessary (with justification)
• Fix all TypeScript errors before committing

ESLint

• Fix all ESLint errors (they block builds)
• ESLint warnings are acceptable but should be addressed when possible
• Common issues:
  • Unescaped entities in JSX (use ', ", etc.)
  • Missing dependencies in useEffect hooks
  • Using <img> instead of Next.js <Image />

React/Next.js Best Practices

• Wrap useSearchParams() usage in Suspense boundaries
• Mark dynamic pages with export const dynamic = 'force-dynamic' when needed
• Use proper TypeScript types for all props and state

File Organization

• Frontend code: apps/frontend/src/
• Backend code: apps/backend/src/
• Documentation: Root level .md files or docs/ directory
• Migrations: supabase/migrations/

Testing Workflow

1. Make changes
2. Test locally:

   # Frontend
   cd apps/frontend && npm run build
   
   # Backend
   cd apps/backend && npm run build
   

3. Fix any errors
4. Re-test builds
5. Only then commit and push

Common Build Errors and Fixes

TypeScript Errors

• HeadersInit type issues: Cast to Record<string, string>
• querySelector type issues: Cast to specific element type (e.g., HTMLInputElement)
• Missing types: Add proper type annotations

Next.js Errors

• useSearchParams() without Suspense: Wrap component in Suspense boundary
• Pre-rendering errors: Add export const dynamic = 'force-dynamic' to page
• Missing dependencies: Add to useEffect dependency array or use useCallback

ESLint Errors

• Unescaped entities: Replace ' with ', " with "
• Missing img alt: Add alt text or use Next.js Image component

Commit Messages

Use clear, descriptive commit messages:

• Start with a verb (Fix, Add, Update, Remove)
• Describe what was changed and why
• Reference related issues if applicable

Example:

Fix build errors: TypeScript types and Suspense boundaries

- Fix TypeScript error in api.ts (HeadersInit type)
- Add Suspense boundaries for useSearchParams()
- Resolves Vercel build failures

Environment Variables

• Never commit .env files
• Document required environment variables in relevant docs
• Use .env.example files as templates

Documentation

• Update relevant documentation when making significant changes
• Add comments for complex logic
• Update TESTING_BUILDS.md if build process changes

Git and GitHub

• DO NOT auto-push to GitHub unless explicitly asked by the user
• Only commit changes locally unless the user requests a push
• When the user asks to "commit and push" or similar, then push
• Always test builds before pushing (see Build Checklist above)

Deployment

• Frontend auto-deploys to Vercel on push to main
• Backend auto-deploys to Railway on push to main
• Both platforms will fail if builds fail
• Always test builds locally first to prevent deployment failures

Questions?

If you encounter build errors you can't resolve:

1. Check TESTING_BUILDS.md for common solutions
2. Review recent commits for similar fixes
3. Check Next.js/TypeScript documentation
4. Ask for help rather than pushing broken builds

Remember: A successful local build = a successful deployment. Always test before pushing!