Guides & Tutorials
This section contains practical, step-by-step guides for customizing, extending, and operating your Ever Works directory website. Each guide is self-contained but may link to related architecture pages for deeper context.
How to Use This Section
Guides are organized by category. If you are setting up the template for the first time, start with the Customization and Theming guides to match the site to your brand. If you are operating a running site, the Admin and Client Dashboard guides will be most relevant. Developers extending the template should work through the Infrastructure and Testing guides.
Customization & Appearance
These guides cover how to make the template your own -- from colors and layouts to navigation and footer content.
| Guide | Description |
|---|---|
| Customization | Comprehensive guide to customizing your directory site -- branding, colors, layouts, and content |
| Theming | The theme system: pre-built themes, custom theme creation, and runtime theme switching |
| Dynamic Colors | How the dynamic color generation pipeline works and how to configure it |
| Layouts & Templates | Customize page layouts, listing templates, and detail page structures |
| Custom Navigation | Configure the navbar, sidebar, and breadcrumb navigation |
| Footer Customization | Modify footer content, links, and layout |
| UI Components | Available UI components and how to use them in your pages |
Admin & Dashboard
Guides for managing content, users, and site settings through the built-in dashboards.
| Guide | Description |
|---|---|
| Admin Dashboard | Overview of admin features: content management, user roles, analytics, and settings |
| Admin Deep Dive | Advanced admin topics: bulk operations, audit logs, and moderation workflows |
| Admin Components | Reusable admin UI components and how to extend the admin interface |
| Client Dashboard | The client-facing dashboard for item owners: submissions, analytics, and profile management |
Data & Content
Guides related to content management, data utilities, and URL handling.
| Guide | Description |
|---|---|
| Slug Utilities | URL slug generation, validation, and conflict resolution |
| URL Utilities | URL construction helpers, query parameter management, and canonical URLs |
| Filter Sync | How filter state is synchronized between URL parameters and the UI |
| Pagination Patterns | Server-side and client-side pagination implementations |
| Currency Formatting | Locale-aware currency display and detection |
Email & Notifications
| Guide | Description |
|---|---|
| Email Templates | Create and customize transactional email templates using Resend |
Monetization & Sponsorship
| Guide | Description |
|---|---|
| Sponsorship System | Set up and manage sponsored listings and advertisement slots |
| Survey System | Integrate user surveys for feedback collection |
Infrastructure & Operations
Guides for performance, reliability, security, and observability.
| Guide | Description |
|---|---|
| Performance Optimization | Caching strategies, bundle optimization, and rendering performance |
| Caching Strategy | The multi-layer caching architecture: in-memory, React Query, and HTTP cache headers |
| Error Handling | Error boundary patterns, API error responses, and user-facing error pages |
| Logging | Structured logging setup and log levels |
| Rate Limiting | API rate limiting configuration and implementation |
| Bot Detection | reCAPTCHA integration and bot protection strategies |
| Database Health Check | Monitoring database connectivity and performance |
| Accessibility | Accessibility standards, testing, and common patterns used in the template |
Testing & Development
| Guide | Description |
|---|---|
| Testing Patterns | Playwright E2E test structure, page objects, fixtures, and running tests |
| Scripts Reference | All CLI scripts in the scripts/ directory: what they do and when to use them |
Suggested Learning Paths
Path 1: Brand Customization (Designer / Product Owner)
- Customization -- understand what can be changed
- Theming -- pick or create a theme
- Dynamic Colors -- fine-tune the color palette
- Footer Customization -- update footer links and branding
- Custom Navigation -- configure menus
Path 2: Site Administration (Admin / Content Manager)
- Admin Dashboard -- learn the admin interface
- Admin Deep Dive -- advanced operations
- Client Dashboard -- understand the client-side experience
- Sponsorship System -- manage sponsored content
Path 3: Developer Extension (Full-Stack Developer)
- Architecture Overview -- understand the codebase structure
- Testing Patterns -- know how to verify changes
- Error Handling -- handle failures gracefully
- Caching Strategy -- understand the caching layers
- Performance Optimization -- keep the site fast
- Scripts Reference -- use the CLI tools effectively
Path 4: Infrastructure & DevOps
- Database Health Check -- monitor database health
- Logging -- set up structured logging
- Rate Limiting -- protect your API endpoints
- Bot Detection -- prevent abuse
- Performance Optimization -- optimize for production load
Cross-References
These guides are closely related to the architecture documentation. For deeper technical context, see:
- Architecture Overview -- system design and layer responsibilities
- Theme System -- architecture behind theming (pairs with the Theming guide)
- Guards System -- access control architecture (pairs with Admin guides)
- Repository Patterns -- data access patterns (context for data guides)
- API Layer -- API route conventions (context for rate limiting and error handling)
Getting Help
If you run into issues while following a guide:
- Check the Quick Reference for common commands and patterns.
- Review Getting Started if you have environment or setup problems.
- Open an issue on the GitHub repository for bugs or feature requests.
Pick the guide most relevant to your current task, or follow one of the learning paths above for a structured walkthrough.