Guidance for Codex Contributors

This repository contains a Next.js 15 application written in TypeScript with Tailwind CSS and shadcn/ui components. The documents inside .cursor/rules describe how code should be structured and styled. Below is a summary for quick reference.

General Principles

• TypeScript First – keep strict mode and never use any.
• Server Components By Default – only use client components when necessary.
• Tailwind Only – avoid custom CSS, rely on utility classes.
• Mobile First – design responsive layouts starting from mobile breakpoints.
• Accessibility – ensure keyboard navigation and screen‑reader support.

Repository Structure

• Use the app/ directory for all routes and components.
• Place shared UI elements in app/components/ui/.
• Static assets go in public/ and fonts in app/assets/font/.
• Data files live in the data/ folder.
• API routes go in app/api/ following App Router conventions.

Key Features

AI Chat Assistant

The site includes an AI-powered chat assistant that can answer questions about Andrew's background:

• Chat interface at /chat
• API endpoint at /api/chat
• Uses OpenAI's GPT-4 via Vercel AI SDK
• Custom system prompt with Andrew's professional information
• Tools for providing links to resume and social profiles

Testing Infrastructure

Comprehensive testing with Vitest and React Testing Library:

• Component tests for UI elements
• API route tests with proper error handling
• Data validation tests
• Test coverage reporting with Codecov

Components

• Follow functional component patterns using the FC type.
• Define props with TypeScript interfaces and include a className prop.
• Use the cn() utility for conditional classes.
• Export components as named exports.

API Routes

• Use Next.js 15 App Router API conventions
• Implement proper error handling and validation
• Return appropriate HTTP status codes
• Use TypeScript for request/response typing
• Validate environment variables on startup

Styling

• Organize Tailwind classes logically (layout → spacing → sizing → typography → colors → borders → transitions → states).
• Always provide dark‑mode variants and test light/dark themes.

TypeScript

• Prefer interface for object shapes and type for unions or aliases.
• Type event handlers precisely, e.g. React.MouseEvent.
• Use generics and type guards where appropriate.

Next.js

• Use the App Router and follow file‑based routing conventions.
• Fetch data in server components and leverage caching.
• Optimize images with the Next.js Image component.
• Use next/font for custom fonts and include metadata for SEO.

Development Workflow

1. Review the rule files under .cursor/rules before implementing new features.
2. Reuse existing UI components whenever possible.
3. Test in both light and dark modes.
4. Write and run tests for new features and bug fixes.
5. Ensure TypeScript, ESLint, and tests have no errors before committing.

Programmatic Checks

Run the linter and tests after making changes:

pnpm lint
pnpm test:run

If the lint command or tests fail, resolve the issues before committing.

Continuous Integration

The project uses GitHub Actions for automated testing:

• CI Pipeline: Type checking, linting, testing, building, and performance testing
• Matrix Testing: Node.js 18.x and 20.x versions
• Coverage Reporting: Automatic coverage tracking with Codecov
• Lighthouse CI: Performance testing on pull requests

All checks must pass before merging to main branch.

Required GitHub Secrets:

• OPENAI_API_KEY: Required for API route tests and build process

Testing

This project uses Vitest with React Testing Library for comprehensive testing. The testing framework covers:

• Unit Tests: Utility functions and individual components
• Component Tests: React components with user interactions
• API Tests: API routes and error handling
• Data Tests: Data structure validation
• Integration Tests: Component interactions

Test Structure

Tests are organized in the app/test/ directory:

app/test/
├── setup.ts                    # Global test setup and mocks
├── components/                 # Component tests
├── api/                        # API route tests
├── data/                       # Data validation tests
└── utils.test.ts               # Utility function tests

Running Tests

# Run all tests once
pnpm test:run

# Run tests in watch mode
pnpm test:watch

# Run tests with UI
pnpm test:ui

# Run tests with coverage
pnpm test:coverage

Writing Tests

Follow these patterns when writing tests:

1. Test user-visible behavior, not implementation details
2. Use descriptive test names that explain what is being tested
3. Test both positive and negative cases
4. Mock external dependencies in the setup file
5. Focus on accessibility using screen.getByRole() queries

Test Coverage Goals

Prioritize testing for:

• Critical components (WorkRow, SocialLink, AnimateIn)
• All API routes with error handling
• Utility functions and data validation
• User interactions and form submissions
• AI chat functionality and API integration

For detailed testing guidelines, see .cursor/rules/testing.mdc.