122 lines
3.5 KiB
Markdown
122 lines
3.5 KiB
Markdown
# 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
|
|
|
|
```txt
|
|
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
|