01 Project Development Guidebook - MetaControl/Illoomination-Stack GitHub Wiki

Software Requirements Specification (SRS)

Table of Contents

  1. Introduction

    • 1.1 Purpose
    • 1.2 Scope
    • 1.3 Intended Audience
    • 1.4 Overview

  2. System Overview

    • 2.1 Functional Requirements
    • 2.2 Non-functional Requirements

  3. System Architecture

    • 3.1 Backend Services
    • 3.2 Frontend Services
    • 3.3 Cloud Services
    • 3.4 Object Storage & Image Processing

  4. Detailed Functional Requirements

    • 4.1 Backend Services
    • 4.2 Frontend Services
    • 4.3 Integration Services
    • 4.4 Cloudflare CDN/Edge Configuration
    • 4.5 AWS Lambda for SSR and Image Processing
    • 4.6 Amazon SES for Email Services
    • 4.7 Backblaze B2 Object Storage

  5. API Design and Integration

  6. Image Processing Requirements

  7. Scalability & High Availability

  8. Security and Data Management

  9. Testing & Monitoring Requirements

  10. Deployment and Maintenance

  11. Store Features

1. Introduction

1.1 Purpose

This document provides a comprehensive Software Requirements Specification (SRS) for developing a scalable e-commerce platform. It outlines the requirements, functionalities, integrations, and deployment strategies to achieve a robust solution capable of handling high traffic, dynamic content, and diverse image processing needs.

1.2 Scope

The intended solution integrates various backend and frontend technologies to create an optimized and scalable e-commerce platform. The system will consist of backend services (Medusa, VPN, Mautic), a Kubernetes setup for both frontend and backend, AWS for SSR and image processing, Cloudflare for CDN and edge services, and Backblaze for object storage.

1.3 Intended Audience

  • Development Team: Backend, Frontend, DevOps
  • Project Managers
  • Stakeholders
  • QA Engineers

1.4 Overview

The document provides a high-level and low-level overview of the platform architecture, requirements for each component, API integration specifications, scaling configurations, and security measures.

2. System Overview

2.1 Functional Requirements

  • Full e-commerce backend powered by Medusa for product management, order processing, and payment integration.
  • Nuxt.js for frontend rendering with support for dynamic SSR using AWS Lambda.
  • Cloudflare as an edge and CDN provider.
  • Image processing to generate multiple product variants from high-quality originals.
  • Mautic for marketing automation, VPN for secure backend operations, Amazon SES for transactional email, and Backblaze B2 for object storage.

2.2 Non-functional Requirements

  • Scalability: Use of Kubernetes with autoscaling for backend and frontend services.
  • Performance: Quick response time using Cloudflare CDN caching and parallelized SSR for dynamic data.
  • Security: Data encryption, secure API endpoints, and secure communication between microservices.
  • Reliability: High availability through managed cloud services and Kubernetes self-healing capabilities.

3. System Architecture

3.1 Backend Services

  • Medusa.js as the core backend e-commerce platform.
  • Node.js as the runtime environment for Medusa's API handling and backend services.
  • Mautic for email marketing automation.
  • VPN on a 2 vCPU Kubernetes node to securely connect different backend components.
  • Managed PostgreSQL as the primary database for storing relational data (e.g., products, variants, orders).
  • Redis serves as the primary cache for product variations, API requests, and data retrieval across all services.
  • Kubernetes to manage containerized services, ensuring high availability and auto-scaling based on load.
  • Docker for containerizing backend services like Medusa, PostgreSQL, and auxiliary tools.
  • Node Scaling: Scale up based on workload and request volume.

3.2 Frontend Services

  • Nuxt.js hosted on a 1 vCPU Kubernetes node with Nuxt UI Pro and Tailwind CSS + UI Pro for design and responsiveness.
  • GraphQL to facilitate efficient data communication between Nuxt.js (frontend) and Medusa (backend).
  • Sharp for image processing to dynamically generate web-optimized product images.
  • Redis as a caching layer to store transient data and API responses for faster product and page loads.
  • Frontend scaling managed by Kubernetes HPA (Horizontal Pod Autoscaler).

3.3 Cloud Services

  • Cloudflare: Used for CDN and edge computing to cache static assets and SSR results for improved performance.
  • AWS Lambda: Dynamic SSR rendering of pages and for generating static content.

3.4 Object Storage & Image Processing

  • Backblaze B2 as the primary object storage for high-quality print files and generated product variants.
  • Image processing using AWS Lambda for on-demand generation of multiple product sizes and variants.

4. Detailed Functional Requirements

4.1 Backend Services

  • Medusa.js E-Commerce Backend: Includes features like product management, inventory, order processing, and payments.

    • REST and GraphQL APIs to provide access to frontend.
    • Integration with Stripe and PayPal for payments.

  • VPN Setup: Establish a VPN to provide a secure channel between backend components.

    • Ensure encrypted communication between services like Mautic, Medusa, and databases.

  • Mautic: Marketing automation to send campaigns and follow-ups to users.

    • Automated email flows and segmentation.

4.2 Frontend Services

  • Nuxt.js Frontend: Serves dynamic content to users while using SSR for optimized SEO and faster initial page load.
    • Use Nuxt UI Pro and Tailwind CSS + UI Pro for design and responsiveness.
    • Dynamic SSR using AWS Lambda, caching output using Cloudflare for fast subsequent loads.
    • GraphQL integration to fetch product data from Medusa.
    • Sharp for dynamically processing product images for optimization.

4.3 Integration Services

  • API Gateway to route requests between the frontend and backend, ensuring secure API communication.
  • Load Balancers for managing traffic spikes and improving reliability.

4.4 Cloudflare CDN/Edge Configuration

  • Caching Policies: Cache SSR-generated pages and static assets.
  • Edge Rules: Implement rules for directing users to the nearest Cloudflare edge server to minimize latency.

4.5 AWS Lambda for SSR and Image Processing

  • Dynamic SSR: Handle initial requests using AWS Lambda to generate SSR pages, feeding Cloudflare for caching.
  • Image Processing: Convert high-quality images to multiple sizes using Lambda for responsive product representation.
    • High Quality to Print Conversion: Generate three print sizes and variations for each motif and product color.
    • API Trigger: Lambda is triggered by product uploads to Backblaze, with variants generated in response.

4.6 Amazon SES for Email Services

  • Transactional Emails: Order confirmation, shipping updates, and newsletters via Amazon SES.
    • DKIM and SPF setup for email deliverability.
    • Integrate with Mautic for marketing and transactional campaigns.

4.7 Backblaze B2 Object Storage

  • High-Quality Print Files: Store original product motifs in Backblaze.
  • URL Generation: Generate URLs for each print size variant to allow print-on-demand fulfillment.
  • Object Lifecycle Rules: Manage lifecycle policies for retention and deletion of outdated assets.

5. API Design and Integration

  • Medusa API: REST/GraphQL endpoints for product data, cart management, checkout, and customer profiles.
  • Nuxt.js API Integration: Consume Medusa API for dynamic product rendering and personalized user data.
  • Image Processing API: Triggered by product updates to generate resized images for various use cases.

6. Image Processing Requirements

  • Conversion Flow: High-quality images uploaded to Backblaze trigger AWS Lambda functions.
  • Motif Sizes: Generate three print sizes from each high-quality image, and prepare multiple product variants (e.g., different colors).
  • Caching: Store image variants in Backblaze for fast retrieval, with URLs available for the frontend.

7. Scalability & High Availability

  • Kubernetes HPA for backend and frontend nodes to ensure scaling in response to traffic spikes.
  • AWS Lambda for stateless SSR and image processing to allow concurrent execution and better scalability.
  • Cloudflare caching to reduce load on backend servers and improve performance.
  • Redis Caching System in Tiers:
    • Tier S (Transients): Frequently accessed products (e.g., during campaigns) are cached in Redis for immediate access.
    • Tier 1: Products with high user interaction are cached with a grace period.
    • Tier 2: Products with lower traffic have image data purged but core data retained.
    • Tier 3: Least-accessed products retain only default images and essential data, dynamically reassembled on request.
    • Temporary Transients: Special-case products (e.g., during marketing pushes) can be manually cached at a higher tier temporarily.

8. Security and Data Management

  • Secure VPN between backend services for encrypted communication.
  • Role-Based Access Control (RBAC) within Kubernetes for managing access.
  • TLS/SSL Encryption for all public-facing services to protect data in transit.
  • AWS IAM Policies for controlling access to Lambda, SES, and Backblaze.

9. Testing & Monitoring Requirements

  • Unit and Integration Tests for both backend (Medusa) and frontend (Nuxt.js).
  • Load Testing: Simulate high traffic to evaluate Kubernetes autoscaling and AWS Lambda execution.
  • Monitoring Tools: Use Prometheus and Grafana to monitor Kubernetes, while using AWS CloudWatch for Lambda monitoring.

10. Deployment and Maintenance

10.1 Deployment Strategy

  • Kubernetes Deployment: Deploy both backend and frontend services using Kubernetes clusters.

    • Backend Deployment: Use Kubernetes StatefulSets for the backend services to ensure data persistence and reliability.
    • Frontend Deployment: Use Kubernetes Deployments for Nuxt.js, ensuring replicas are managed effectively for scaling and fault tolerance.
    • AWS Lambda Deployment: Deploy server-side rendering (SSR) services and image processing logic using AWS Lambda functions.

  • CI/CD Pipeline

    • Continuous Integration: Utilize GitHub Actions or Jenkins to automate building, testing, and packaging of application code.
    • Continuous Deployment: Implement automated deployment using Helm charts to update Kubernetes clusters seamlessly.
    • Version Control: Use Git branching strategy (e.g., GitFlow) for managing feature releases and hotfixes.

10.2 Infrastructure as Code (IaC)

  • Terraform: Define and manage cloud infrastructure resources for Kubernetes, AWS Lambda, and Backblaze using Terraform.
  • Kubernetes Manifests: Use YAML files to define deployment configurations, services, and ingress rules.

10.3 Backup and Recovery

  • Database Backups: Schedule regular backups of the Managed PostgreSQL database using AWS Backup or a similar cloud backup solution.
  • Object Storage Backups: Configure lifecycle rules in Backblaze B2 to maintain backup copies of image assets for redundancy.
  • Application Backups: Implement backup policies for Kubernetes persistent volumes to ensure data is not lost.

10.4 Monitoring and Logging

  • Prometheus & Grafana: Monitor Kubernetes clusters, including resource utilization, request rates, and errors.
  • AWS CloudWatch: Use CloudWatch for AWS Lambda and other AWS services to track execution metrics and error rates.
  • ELK Stack (Elasticsearch, Logstash, Kibana): Aggregate logs from backend and frontend services for real-time analytics and troubleshooting.

10.5 Maintenance Jobs

  • Cron Jobs: Schedule Kubernetes CronJobs for periodic tasks such as database clean-up, re-indexing search data, and clearing expired cache entries.
  • Rolling Updates: Perform rolling updates in Kubernetes to ensure application updates do not impact availability.
  • Health Checks: Use Kubernetes liveness and readiness probes to detect unhealthy containers and replace them automatically.

10.6 Security Maintenance

  • Security Patching: Regularly update container images for backend, frontend, and supporting services to ensure the latest security patches are applied.
  • Role-Based Access Control (RBAC): Use Kubernetes RBAC to control who can view or edit deployments and access secrets.
  • SSL/TLS Renewal: Automate the renewal of SSL/TLS certificates using tools like Certbot or AWS Certificate Manager.

11. Store Features

11.1 Dynamic Product Assembly

  • Product Variants: Medusa will handle dynamic product variants, such as motifs, colors, and sizes.
    • Frontend Integration: The frontend will query product data from Medusa using GraphQL, dynamically displaying product variants without duplicating database records.
    • Image Generation: Product images are generated and compressed using Sharp for different motif sizes and placements.

11.2 Geolocation-Based Pricing

  • GeoIP Detection: Pricing is adjusted based on user location using GeoIP detection integrated with the frontend.
    • Currency Display: Prices are shown in either EUR or USD, with real-time currency conversion based on the user’s location.
    • Medusa Integration: Medusa provides localized pricing information through its API.

11.3 Custom Discount Structure

  • Dynamic Discounts: Discounts are dynamic and stackable, offering the following types:
    • Timed Discounts: Limited-time reductions on specific products.
    • Membership Discounts: Discounts based on membership tier, configured in Medusa.
    • Campaign-Specific Discounts: Automatically applied based on campaign rules.
  • Medusa Configuration: Discounts are configured and managed through Medusa’s admin interface, applied dynamically based on user profiles.

11.4 Membership and Gamification

  • Membership Levels:
    • Tier I (Free): Users gain access to exclusive offers, Cotton Credits, and receive one giveaway ticket monthly.
    • Tier II (Paid, €28/year): Users receive a free tee, more credits, discounts, and two giveaway tickets monthly.
    • Tier III (Subscription, €28/month): Users receive a free tee each month, the highest discounts, maximum credits, and three giveaway tickets monthly.
  • Monthly Giveaway: Each membership tier provides a specific number of giveaway tickets.
  • Cotton Credits: Credits earned from purchases can be redeemed for discounts or free products.
  • Gamification: Achievements are awarded for milestones, and loyalty tiers provide additional perks.

11.5 Caching System in Tiers

Caching Strategy:

  • Tier S (Transients): Frequently accessed products are cached in Redis for immediate access during campaigns.
  • Tier 1: Products with high user interaction are cached with a grace period to ensure smooth access.
  • Tier 2: Products with moderate traffic have image data purged but core data retained for efficiency.
  • Tier 3: Least-accessed products retain only default images and core data, dynamically reassembled upon request.
  • Temporary Transients: Special-case products, such as those during marketing pushes, can be manually cached at a higher tier temporarily.

11.6 User Experience Features

  • Personalized Content: Display personalized product recommendations based on user behavior, powered by Medusa's API.
  • Login and Registration: Provide pop-up login and registration options to keep users on the same page, utilizing AJAX for a seamless experience.
  • Mobile Optimization: Optimize the user interface for mobile devices using Tailwind CSS, including a bottom navigation bar for quick access to essential features.

11.7 SEO and Marketing

  • SEO Best Practices: Implement SEO best practices using Nuxt.js features for meta tags, schema, and improved page load times.
  • Social Sharing: Integrate social sharing buttons and Open Graph meta tags to enhance visibility on social media.
  • Mautic Integration: Utilize Mautic for drip campaigns, abandoned cart recovery, and personalized marketing emails.

11.8 Payment and Checkout

  • Multiple Payment Options: Integrate Stripe, PayPal, and Apple Pay for seamless payments.
  • Express Checkout: Provide an express checkout button for returning users to simplify the purchase process.
  • Order Summary and Discounts: Display order summaries with applied discounts, taxes, and shipping fees clearly.

11.9 Shipping and Tax Management

  • Geolocation-Based Shipping Rates: Calculate shipping rates based on user location, with Medusa providing shipping options.
  • Tax Calculation: Automatically calculate taxes based on the user's location using tax APIs integrated with Medusa.
  • Free Shipping Threshold: Implement free shipping for orders over a configured threshold (e.g., €75).

11.10 Customer Support

  • Live Chat Integration: Integrate a live chat widget for real-time support.
  • FAQ Section: Provide an FAQ section for quick answers to common questions.
  • Support Ticket System: Allow users to raise support tickets via an integrated form, handled through Mautic workflows.

Summary

This SRS document outlines a full-stack, scalable e-commerce platform that combines a dynamic SSR-powered frontend, a reliable Medusa.js backend, seamless integration with AWS, Cloudflare, and Backblaze, and automated email services with Amazon SES. The architecture ensures scalability, reliability, and performance, while maintaining a cost-efficient setup.

Next Steps:

  • Review and refine the system requirements with stakeholders.
  • Define the development milestones for backend and frontend services.
  • Set up Kubernetes clusters and begin implementing backend services.