Skip to content

AGENT.md

Latest commit

 

History

History
122 lines (88 loc) · 3.47 KB

AGENT.md

File metadata and controls

122 lines (88 loc) · 3.47 KB

AGENT.md

This file provides guidance for AI assistants working with the Sink project.

Project Overview

Sink is a URL shortening service built with Nuxt 3 and Cloudflare Workers. It provides analytics, real-time tracking, and a modern web interface.

Key Technologies

  • Frontend: Nuxt 3, Vue 3, TypeScript, Tailwind CSS, shadcn/ui
  • Backend: Cloudflare Workers, H3 (Nitro)
  • Database: Cloudflare KV
  • Analytics: Cloudflare Analytics Engine
  • Deployment: Cloudflare Pages/Workers

Project Structure

Sink/
├── app/                     # Nuxt 3 application
│   ├── components/          # Vue components
│   ├── pages/              # File-based routing
│   ├── layouts/            # Layout components
│   ├── utils/              # Utility functions
│   └── middleware/         # Route middleware
├── server/                  # Server-side API
│   ├── api/                # API endpoints
│   ├── middleware/         # Server middleware
│   └── utils/              # Server utilities
├── public/                 # Static assets
├── schemas/                # TypeScript schemas
├── tests/                  # Test files
└── docs/                   # Documentation

Development Commands

  • pnpm dev - Start development server
  • pnpm build - Build for production
  • pnpm preview - Preview production build
  • pnpm test - Run tests
  • pnpm lint - Run ESLint

Key Conventions

Code Style

  • Use TypeScript for all new code
  • Follow Vue 3 Composition API patterns
  • Use PascalCase for component names
  • Use camelCase for variables and functions
  • Use kebab-case for CSS classes

API Structure

  • RESTful endpoints in /server/api/
  • Use Zod for schema validation in /schemas/
  • Implement proper error handling
  • Use Cloudflare environment variables for configuration

Database

  • Use Cloudflare KV

Testing

  • Use Vitest for unit tests
  • Test files should be co-located with source files
  • Use the existing test utilities in /tests/utils.ts

Environment Variables

Key environment variables to be aware of:

  • NUXT_CF_ACCOUNT_ID - Cloudflare account ID
  • NUXT_CF_API_TOKEN - Cloudflare API token
  • NUXT_DATASET - Analytics engine ID
  • NUXT_SITE_TOKEN - Site token for management

Common Tasks

Adding a New API Endpoint

  1. Create file in /server/api/ with appropriate HTTP method
  2. Add Zod schema validation in /schemas/
  3. Add tests in /tests/api/
  4. Update documentation if needed

Adding a New Component

  1. Use existing UI components from /app/components/ui/
  2. Follow the established component patterns
  3. Add TypeScript interfaces for props
  4. Consider adding to storybook if applicable

Security Guidelines

  • Never commit secrets or API keys
  • Use environment variables for sensitive configuration
  • Validate all user input with Zod schemas
  • Implement rate limiting on API endpoints
  • Follow OWASP guidelines for web security

Performance Considerations

  • Use Cloudflare's edge caching where appropriate
  • Minimize bundle size by using dynamic imports
  • Optimize images and assets
  • Use the existing analytics for monitoring

Troubleshooting

  • Check Cloudflare dashboard for worker logs
  • Use wrangler tail for real-time logs
  • Verify environment variables are properly set

Deployment

  • Staging: Automatic on push to main branch
  • Production: Manual trigger via Cloudflare dashboard
  • Use wrangler deploy for manual deployments