Skip to content

Latest commit

 

History

History
324 lines (275 loc) · 14.6 KB

PROJECT_SPECIFICATION.md

File metadata and controls

324 lines (275 loc) · 14.6 KB

PhotoPilot Application Specification Document

This document defines all key areas required to design, build, test, and measure success for PhotoPilot—a modern, AI-assisted workflow platform for photographers. It covers project goals, functional and technical requirements, UI/UX design, data and storage, testing, deployment, and future enhancements.

1. Overview

  • Project Name: PhotoPilot
  • Purpose:
    PhotoPilot streamlines the photographer’s workflow by integrating multi-cloud storage, on-demand AI image analysis, and multi-channel social media publishing.
  • Vision and Goals:
    • Enable photographers to quickly sort, annotate, and publish their photos.
    • Automate content generation (captions, titles, hashtags) while providing manual override.
    • Support real-time collaboration and role-based access among teams.
  • Problem It Solves:
    • Eliminates the manual overhead of organizing large photo libraries across various cloud storage providers.
    • Reduces time spent on content creation and social media posting.
    • Simplifies collaboration by synchronizing real-time sorting and editing among team members.
  • Target Users and Personas:
    • Professional photographers managing large photo libraries.
    • Social media influencers and content creators who require timely and engaging captions.
    • Creative teams working collaboratively on visual content.
  • Key Differentiators / Value Proposition:
    • Integration of state-of-the-art AI (BLIP-2 and GPT-4 Turbo) for fast, cost-effective image captioning and content generation.
    • Multi-cloud support via OAuth2, ensuring seamless access to Dropbox, Google Drive, and OneDrive.
    • Direct multi-platform social media publishing with compliance to each platform’s API constraints.

2. Functional Requirements

A. Features and Capabilities

  1. Photo Management & Sorting

    • Functionality:
      • Retrieve photos from multiple cloud storage providers.
      • Categorize each photo as “Good,” “Change,” or “Delete.”
      • Create subfolders (good, change, delete, archive) automatically within the source directory.
    • User Stories / Use Cases:
      • As a photographer, I want to quickly review my images and classify them so that I can focus on the best ones for publication.
      • As a team member, I need to see real-time sorting decisions to collaborate efficiently.
    • Roles and Permissions:
      • Editors: Can sort and modify images (including reordering, commenting, and bulk actions).
      • Viewers: Can see sorting decisions in real time without editing permissions.
    • Flow / Interaction Diagram (Pseudocode Example): 
      def sort_photo(photo, decision):
    if decision == 'good':
        move_to(f"{project_path}/good/{photo}")
    elif decision == 'change':
        move_to(f"{project_path}/change/{photo}")
    else:
        flag_for_deletion(photo)

  2. AI-Powered Publication Preparation

    • Functionality:
      • On-demand image analysis using BLIP-2 to generate image descriptions.
      • Option for manual input or override of image descriptions.
      • Use AI (preferably GPT-4 Turbo) to generate social media post components (title, caption, hashtags).
    • User Stories / Use Cases:
      • As a photographer, I want to have high-quality captions generated for my images so I can post them quickly.
      • As a user, I can edit or regenerate AI-generated content if needed.
    • Metadata Structure Example: 
      {
  "post_content": {
    "title": "AI-generated title",
    "caption": "3-sentence description",
    "hashtags": ["#photography", "#nature"]
  }
}

  3. Social Media Publishing

    • Functionality:
      • Publish selected images to multiple platforms (Instagram, X/Twitter, Facebook).
      • Enforce platform-specific constraints (e.g., Instagram’s business account requirement, rate limits).
      • Archive published photos (e.g., /archive/{year}-{month}/published_photos/).
    • User Stories / Use Cases:
      • As a photographer, I want to select multiple platforms to post my content simultaneously.
      • As an admin, I want to be alerted if any platform’s rate limit is reached so that I can manage posting schedules.
    • Roles and Permissions:
      • Only authorized users can trigger posts; view-only users can monitor post status.

  4. Collaboration & Real-Time Updates

    • Functionality:
      • Support real-time collaboration on photo sorting and commenting.
      • Use WebSockets (or similar) with a pub/sub backplane (e.g., Redis) to broadcast changes.
    • User Stories / Use Cases:
      • As a collaborator, I want to see updates as other team members re-sort or annotate photos.
      • As a project manager, I want role-based controls ensuring that only authorized users can modify content.

B. Additional Clarification Requirements

  • Token Security and OAuth Verification:
    • Ensure secure storage of OAuth tokens with encryption at rest.
    • Handle multiple OAuth providers with dedicated callback endpoints and unified user experience.
  • Error Handling & Fallbacks:
    • If AI image description generation fails (BLIP-2 or GPT-4 Turbo), allow manual input.
    • Implement exponential backoff and retries for third-party API failures.

3. Technical Requirements

A. Architecture Overview

  • Client:
    • React Progressive Web App (PWA) designed with mobile-first responsive principles.
  • Backend:
    • API Gateway using Node.js/Express with microservices for authentication, cloud storage, AI orchestration, and social media dispatch.
  • Real-Time Collaboration:
    • WebSocket-based solution (e.g., Socket.io) with Redis as a pub/sub backplane.
  • Data Storage:
    • MongoDB for storing project and media asset data.
  • AI Integration:
    • BLIP-2 deployed as an on-demand microservice (potentially containerized on a GPU-enabled server or serverless GPU function).
    • GPT-4 Turbo for content generation, with fallback options to GPT-3.5 or alternative LLMs.

B. Technology Stack

Component Technology / Service
Frontend React, PWA, HTML5, CSS3, JavaScript
Backend Node.js, Express, FastAPI (for specific microservices)
Real-Time WebSockets (Socket.io), Redis for pub/sub
Database MongoDB (hosted on Atlas)
Cloud Integration OAuth2 for Dropbox, Google Drive, OneDrive
AI Services BLIP-2 (for image captioning), GPT-4 Turbo (for text generation)
Social APIs Instagram Graph API, Twitter API v2, Facebook Graph API
Deployment Heroku (initial), with alternatives such as Fly.io, Railway
CI/CD GitHub Actions or Heroku Pipelines

C. Third-Party Integrations

  • Cloud Storage:
    • OAuth2 for Dropbox, Google Drive, and OneDrive.
    • Secure token storage and refresh management.
  • Social Media:
    • Instagram (business account integration, content posting via Facebook Graph API).
    • Twitter (using OAuth1.1a or OAuth2 and media upload endpoints).
    • Facebook (posting to Facebook Pages via Graph API).
  • AI Services:
    • BLIP-2 for on-demand image description.
    • GPT-4 Turbo for generating titles, captions, and hashtags.
  • Others:
    • Use of Redis for caching, real-time messaging, and job queuing.

D. Performance and Scalability Goals

  • Scalability:
    • Horizontal scaling of web dynos and real-time services.
    • Caching strategies for cloud API calls (batch operations, incremental sync).
    • Asynchronous processing of AI tasks to avoid request timeouts.
  • Performance:
    • AI image analysis with BLIP-2 should complete in ~1 second per image.
    • Content generation latency should target under 3 seconds per image (including both BLIP-2 and GPT-4 Turbo).
  • Cost Management:
    • Monitor and potentially switch to lower-cost models (GPT-3.5, Claude) if volume increases.
    • Evaluate deployment alternatives if Heroku costs escalate.

E. Security and Compliance

  • Token Security:
    • Encrypt OAuth tokens and other sensitive data at rest.
    • Use least-privilege scopes for OAuth integrations.
  • Multi-Tenant Support:
    • Ensure data isolation via tenant IDs in JWTs and database schema design.
  • Compliance:
    • Adhere to GDPR and CCPA data handling policies.
    • Secure user data with AES-256 encryption and regular penetration testing.

4. UI/UX Design Considerations

  • Workflow Descriptions:
    • Landing dashboard with cloud account integration and project selection.
    • Photo management screen for sorting photos (Good, Change, Delete) with drag-and-drop interface.
    • AI content generation panel with editable fields for titles, captions, and hashtags.
    • Social media publishing screen with multi-select checkboxes for target platforms.
  • Navigation Flow:
    • Clear navigation from dashboard to project view, then to detailed photo view and AI content editing.
  • Accessibility Requirements:
    • WCAG 2.1 compliance with proper contrast, keyboard navigation, and screen reader support.
  • Device/Browser Compatibility:
    • Fully responsive design supporting modern browsers and mobile devices.
  • Real-Time Feedback:
    • Instant updates on collaboration actions (sorting, commenting) using WebSockets.

5. Data and Storage

A. Data Models / Schema

  • Projects Collection:
    • Fields: name, cloud_path, owner, collaborators (with roles), etc.
    • Example: 
      {
  "name": "Wedding Shoot 2024",
  "cloud_path": "/wedding_shoot_2024",
  "owner": "user123",
  "collaborators": [
      { "userId": "user456", "role": "editor" },
      { "userId": "user789", "role": "viewer" }
  ]
}
  • MediaAssets Collection:
    • Fields: projectId, filename, status (good, change, delete), metadata (AI description, custom text, social post details), orderIndex, etc.
    • Example: 
      {
  "projectId": "project123",
  "filename": "IMG_001.jpg",
  "status": "good",
  "metadata": {
      "ai_description": "A sunset over a calm lake",
      "custom_text": "User edited caption",
      "social_posts": [
          { "platform": "Instagram", "post_id": "ig123", "timestamp": "2024-04-01T12:00:00Z" }
      ]
  },
  "orderIndex": 1
}

B. Storage and Access Strategies

  • Cloud File Handling:
    • Store image files in user-designated cloud storage.
    • Maintain file metadata and links in MongoDB.
  • Backup and Data Recovery:
    • Use MongoDB Atlas backup features.
    • Implement periodic snapshots for configuration and critical data.
  • Caching:
    • Use Redis for caching API responses and real-time data.

6. Testing Strategy

  • Unit Testing:
    • Test individual functions (e.g., sorting logic, API integrations).
  • Integration Testing:
    • Verify interactions between microservices (cloud API, AI services, social media APIs).
  • End-to-End Testing:
    • Use tools like Cypress or Selenium to simulate user workflows from login through publishing.
  • Usability Testing:
    • Conduct sessions with target users to assess UI/UX and workflow efficiency.
  • Load/Performance Testing:
    • Stress-test API endpoints, real-time messaging, and AI processing under expected load.
  • Manual vs. Automated:
    • Combine automated test suites (unit, integration, end-to-end) with periodic manual exploratory testing.

7. Success Criteria

  • Functional Success:
    • All features (photo sorting, AI captioning, social publishing) are fully implemented and work as intended.
  • Technical Success:
    • System meets performance benchmarks (e.g., sub-3-second AI processing per image).
    • Scalability targets met without significant latency or failures.
  • Business Success:
    • High user adoption, positive feedback on workflow efficiency, and measurable increases in published content.
  • Metrics and KPIs:
    • User engagement (daily/weekly active users).
    • Average time from photo upload to published post.
    • API response times and system uptime.
    • Cost per AI call and overall operational costs.

8. Deployment & Environment Setup

  • Environments:
    • Development, staging, and production environments with separate configurations.
  • CI/CD Pipeline:
    • Use GitHub Actions or Heroku Pipelines for automated testing and deployments.
  • Hosting Configuration:
    • Initial deployment on Heroku with autoscaling dynos, with potential migration to cost-effective platforms (Fly.io, Railway) as scale increases.
  • OAuth Provider Setup:
    • Register and configure OAuth applications for Dropbox, Google Drive, OneDrive, Instagram, Twitter, and Facebook.
    • Securely store client IDs, secrets, and tokens in environment variables.

9. Collaboration & Access

  • Project-Based User Access:
    • Each project includes an owner and a list of collaborators with roles (editor, viewer, commenter).
  • Multi-Tenant Support:
    • Isolate data via tenant IDs; enforce permissions at the API and database query levels.
  • Team Collaboration Features:
    • Real-time sorting updates via WebSockets.
    • In-app commenting and activity feeds.
    • Presence indicators and role-based controls.

10. Future Enhancements / Roadmap

  • MVP vs. v2+ Features:
    • MVP: Basic photo sorting, on-demand AI content generation, and direct social media publishing.
    • Future Enhancements:
      • Scheduled publishing and content calendars.
      • Advanced image editing and enhancement features.
      • Additional social platform integrations (e.g., LinkedIn, Pinterest).
      • Enhanced real-time collaboration with conflict resolution mechanisms.
      • Offline mode or progressive web app caching improvements.
  • Known Constraints / Technical Debt:
    • Potential latency with sequential AI operations.
    • Cost scaling for AI services and cloud infrastructure.
    • Need for ongoing monitoring of third-party API changes and rate limits.
  • Ideas for Future Optimization:
    • Introduce caching and batch processing for cloud API calls.
    • Evaluate lower-cost AI models (e.g., GPT-3.5 Turbo or Anthropic’s Claude) for routine tasks.
    • Containerize the application for easier migration to alternative hosting providers.
    • Explore integrating a dedicated real-time framework (e.g., Supabase Realtime) if collaboration demands increase.