# ZeroBS Agency - Website Template

> A modern, production-ready website platform built with Payload CMS, Next.js 16, React 19, and TypeScript. Optimized for performance, accessibility, and AI agent interaction.

## Overview

ZeroBS Agency is a full-stack web platform that combines a headless CMS with a powerful React frontend. It provides enterprise-grade features including multi-tenant support, internationalization, content versioning, and comprehensive SEO optimization.

## Key Features

- **Headless CMS**: Payload CMS 3.85 with form builder, redirects, and SEO plugins
- **Modern Framework Stack**: Next.js 16.2 with React 19 and TypeScript 5.9
- **Multi-language Support**: next-intl with automatic locale detection
- **Content Management**: Pages, posts, places with rich Lexical editor
- **E-commerce Ready**: Stripe integration via @payloadcms/plugin-stripe
- **Performance**: Image optimization (AVIF/WebP), ISR caching, responsive design
- **Accessibility**: WCAG 2.1 AA standards, semantic HTML, proper ARIA labels
- **Security**: Content Security Policy, HTTPS enforcement, secure authentication

## Primary Sections

### Frontend Pages
- **[Homepage](/)**: Featured content and service overview
- **[Blog](/blog)**: Article collection with filtering and search
- **[Places](/places)**: Location-based services directory
- **[Admin](/admin)**: Payload CMS dashboard

### Core Navigation
- Dynamic routing with locale support (en, bg, etc.)
- Breadcrumb navigation for content hierarchy
- Mobile-responsive menu system

## Technical Architecture

### Database & Storage
- PostgreSQL via Neon (primary data)
- Vercel Blob (media storage)
- Transaction-safe operations with Payload hooks

### Authentication & Authorization
- Next Auth 5.0 Beta with JWT sessions
- Role-based access control (admin, editor, user)
- Secure user session management

### Performance Optimizations
- Incremental Static Regeneration (ISR) at 1-hour intervals
- Dynamic parameter generation (only visited pages built)
- Server-side render optimization with React cache()
- Image optimization with blur placeholders

### Styling & Components
- Tailwind CSS 4.2 with custom theme system
- Radix UI primitives for accessible components
- GSAP 3.14 for smooth animations
- Dynamic theme colors via CSS variables

## Important Developer Information

### Accessibility
- All interactive elements have programmatic names
- Semantic HTML structure with proper heading hierarchy
- Focus management and keyboard navigation support
- Color contrast meets WCAG AA standards
- Accessibility tree verification enabled

### Content Types
- **Pages**: Core website pages with flexible block composition
- **Posts**: Blog articles with metadata and categorization
- **Places**: Location services with geographic data
- **Media**: Optimized image management with transformations

### API & Integration Points
- REST API with role-based access control
- Payload Local API for server-side operations
- Stripe for payment processing
- Google Maps integration for location services
- Notion embeds for external content

### Environment & Deployment
- Vercel deployment with automatic branch previews
- Docker containerization for local development
- Environment-based configuration (dev/staging/production)
- Automated type generation from CMS schema

## Documentation & Resources

- [Payload CMS Docs](https://payloadcms.com/docs): Full CMS documentation
- [Next.js Documentation](https://nextjs.org/docs): Framework reference
- [Accessibility Guide](@docs/accessibility.md): WCAG compliance details
- [Component Library](@docs/components.md): UI component reference
- [API Documentation](@docs/api.md): Backend integration guide

## Common Tasks

### Content Management
- Create and publish pages through Payload CMS admin
- Add blog posts with SEO metadata and featured images
- Manage user roles and permissions
- View versioning and drafts history

### Developer Workflow
- `pnpm dev` - Start development server with HMR
- `pnpm build` - Production build with optimization
- `pnpm generate:types` - Update TypeScript types from schema
- `pnpm test` - Run integration and E2E tests

### Maintenance
- Monitor Core Web Vitals in PageSpeed Insights
- Review Lighthouse audits monthly
- Update dependencies regularly via pnpm
- Check accessibility compliance with axe DevTools

## Support & Contact

For technical issues, feature requests, or accessibility concerns, contact the development team through the admin dashboard or support channels.