Photography Portfolio
The original prompt, shown in full as plain text.
Prompt
# Photography Portfolio — Project Specification
Version: 1.0
Last Updated: 2026-01-25
---
## 1. Project Overview
This project is a public-facing photography portfolio and project gallery built with:
- React
- TypeScript
- Next.js (App Router)
- Tailwind CSS
- TanStack Query
The website displays photography projects that are automatically synchronized from a private Google Drive folder. Clients upload images via Google Drive, and the website dynamically pulls and displays them without requiring manual updates.
The system uses a Google Drive Service Account for secure, server-side access.
---
## 2. Project Goals
### Primary Goals
- Provide a professional public portfolio website.
- Allow clients to upload and manage photos using Google Drive.
- Automatically reflect additions and deletions on the website.
- Display projects in clean, modern galleries.
- Support scalable expansion (videos, booking, payments).
### Secondary Goals
- Minimize manual content management.
- Maintain strong performance via caching.
- Provide a high-quality visual experience.
- Ensure long-term maintainability.
### Non-Goals (MVP)
- No admin dashboard.
- No client login system.
- No image downloads.
- No CMS integration.
- No payments (planned for future versions).
---
## 3. Target Users
### Primary Users
- Photography clients uploading project photos.
- Public visitors viewing the portfolio.
### Secondary Users
- Site owner/administrator managing the Drive folder.
- Developers maintaining the project.
---
## 4. Core User Flows
### Visitor Flow
1. Visitor opens homepage.
2. Views Hero and can scroll to featured projects.
3. Navigates to /projects.
4. Selects an album.
5. Browses images in grid.
6. Opens images in modal.
7. Navigates via arrows/swipe.
8. Optionally visits Hire page (future).
### Client Flow
1. Client opens shared Google Drive folder.
2. Creates new album folder.
3. Uploads JPG/PNG images.
4. Optionally renames files for ordering.
5. Website auto-updates.
---
## 5. Project Milestones
### MVP (Version 1)
- Google Drive integration
- Album listing page (/projects)
- Album detail page (/projects/[slug])
- Uniform gallery grid
- Modal image viewer
- Service account authentication
- Caching with TanStack Query
### Version 2
- Video support (separate section)
- Featured masonry sections
- Performance optimizations
- Enhanced metadata
- SEO improvements
### Version 3+
- Booking system
- Payments
- Admin dashboard
- CMS integration
- Internationalization
---
## 6. Storage Architecture
### Google Drive Setup
Parent Folder:
Photography Site Albums/
Album Folder Naming:
YYYY-MM-DD__Project-Title
Example:
2026-01-25__Winter-Portraits
Slug Generation:
Project-Title → lowercase → dash-separated
Example:
Winter-Portraits → winter-portraits
### File Naming
Ordering:
001__filename.jpg
002__filename.jpg
Allowed Formats:
- JPG
- PNG
Disallowed:
- RAW
- HEIC
- Unsupported formats
### Cover Image
Optional:
__cover.jpg
If missing, use first image by filename sort.
### Video Files (V2)
- MP4, MOV
- Stored in same album folder
- Displayed in separate section
---
## 7. Data Access Model
### Authentication
- Google Drive Service Account
- Private Drive access
- Folder shared with service account
- No public Drive sharing
### Access Pattern
Client Browser → Next.js API → Google Drive API → Service Account
All Drive access is server-side.
---
## 8. API Design
### GET /api/projects
Returns list of albums.
Response Shape:
[
{
"slug": "winter-portraits",
"title": "Winter Portraits",
"date": "2026-01-25",
"coverUrl": "string",
"updatedTime": "ISO8601"
}
]
---
### GET /api/projects/[slug]
Returns album content.
Response Shape:
{
"slug": "winter-portraits",
"title": "Winter Portraits",
"date": "2026-01-25",
"images": [
{
"id": "string",
"name": "001__image.jpg",
"url": "string",
"thumbUrl": "string"
}
],
"videos": []
}
---
### GET /api/media/[id]
Streams media files from Google Drive.
Used for private image proxying.
---
## 9. Frontend Architecture
### Routes
/ → Home
/projects → Album Grid
/projects/[slug] → Album Page
/about → About Page
/hire → Hire Page (future)
---
### Layout
Global Layout:
- Navbar
- Footer
- QueryClientProvider
---
### Gallery Display Modes
#### Featured Masonry (Home / Featured)
- CSS columns
- No cropping
- Natural aspect ratio
#### Project Gallery (Main Album)
- Uniform grid
- Fixed aspect ratio (portrait)
- object-fit: cover
- Cropped edges allowed
---
### Modal Viewer
Features:
- Left/right arrows
- Swipe gestures
- Keyboard navigation
- ESC close
- Looping navigation
---
## 10. Data Fetching Strategy
### TanStack Query
- useProjects()
- useProject(slug)
Default Settings:
- staleTime: 60–120 seconds
- cacheTime: 5 minutes
- refetchOnWindowFocus: false
Manual Refresh:
- Invalidate queries on demand
---
## 11. Performance Strategy
- Next.js Image Optimization
- Server-side prefetching
- Query caching
- Lazy loading
- Responsive images
---
## 12. Security Constraints
- Service account credentials stored in environment variables
- No secrets in repository
- No client-side Drive access
- No direct Drive URLs exposed
- Media proxied via API
---
## 13. Coding Standards
- Strict TypeScript
- ESLint + Prettier
- Modular components
- Feature-based folders
- Typed API responses
---
## 14. Documentation Requirements
Maintain the following:
- claude-docs/architecture.md
- claude-docs/changelog.md
- claude-docs/status.md
- claude-docs/frontend.md
Update after major changes.
---
## 15. Development Workflow (PSB Aligned)
### Plan Phase
- Update this spec before major changes
- Use Claude plan mode
- Clarify assumptions
- Define success criteria
### Setup Phase
- Initialize GitHub repo
- Configure environment variables
- Create CLAUDE.md
- Install plugins and MCPs
- Configure permissions
### Build Phase
Use three workflows:
1. Feature workflow: Research → Plan → Implement → Test
2. Issue-based workflow
3. Multi-agent workflow (git worktrees)
---
## 16. Regression Prevention
- Update CLAUDE.md when mistakes occur
- Document new rules
- Add automated tests
- Maintain changelog
---
## 17. Testing Strategy
- Unit tests for utilities
- Integration tests for API routes
- Playwright E2E tests for galleries
- Manual mobile testing for swipe gestures
---
## 18. Deployment
- GitHub → Vercel integration
- Preview deployments per branch
- Environment secrets via Vercel dashboard
---
## 19. Success Criteria (MVP)
The MVP is considered complete when:
- Albums auto-sync from Drive
- /projects loads correctly
- /projects/[slug] renders gallery
- Modal navigation works
- Images are private in Drive
- No manual content updates required
- Performance meets Lighthouse “Good” standards
---
## 20. Known Risks
- Google API quota limits
- Large album performance
- Image bandwidth usage
- Mobile layout bugs
- OAuth credential misconfiguration
---
## 21. Future Considerations
- Stripe integration
- Booking calendar
- CMS
- Admin panel
- CDN-backed media cache
- AI-assisted tagging
---
End of Specification