DOCSEARCHbyAlgolia
Submit Docs

Flamingo Commerce

repository·master·Indexed 20 days ago

https://github.com/i-love-flamingo/flamingo-commerce

An e-commerce framework featuring a standard one-page checkout flow, a robust GraphQL-based state machine for order placement, and a comprehensive Cart module. It supports custom payment providers, multidelivery workflows, and complex tax calculation algorithms (Vertical and Horizontal). The system utilizes an immutable Cart aggregate and a Decorated Cart for product information, providing detailed pricing invariants for items, deliveries, and total cart calculations.

Tokens
21.2K
Snippets
39
Records
80
Agent score
70%

What's inside flamingo-commerce

  1. Overview of the Search Module

    master
    The Search Module provides a common search domain for rendering search results and autosuggestion. It is designed to be generic, allowing searches to return various types of documents (such as Products, Categories, Content, or Brands) by using a Document interface. The module also includes a pagination utility to facilitate passing pagination data to different interfaces.

  2. Overview of the Category Module

    master

    The Category Module manages the domain model for product categories, including category data (name, media, etc.) and category trees. It provides:

    • Interface Layer: Controllers for rendering category pages using different templates based on category type, and data controllers for template access.
    • Product Search Integration: It defines a CategoryFilter (implementing the search filter interface) which is passed to the productSearchService. Any implementation of the product search service must be able to handle this filter to show products within a category.

    Dependencies:

    • product package (for productSearchService)
    • search package (for pagination)

  3. Overview of Flamingo Commerce

    master

    Flamingo Commerce is a toolkit for building fast, flexible, and headless commerce applications. It is designed around modern architectural principles like Domain-Driven Design (DDD) and the 'Ports and Adapters' pattern to ensure maintainability and scalability.

    Key features include:

    • Decoupled Frontend: The backend (Backend for Frontend) is decoupled from the frontend, allowing any technology to be used.
    • Microservices Ready: Uses adapters to connect easily to external APIs or microservices.
    • High Performance: Designed to provide personalized experiences without relying on frontend page caching.
    • Testability: Provides 'Fake Adapters' to allow testing application logic without external dependencies.
    • GraphQL Support: Most modules provide built-in GraphQL support for easy data querying.

  5. What is Sourcing in Flamingo Commerce?

    master

    Sourcing is the logic used to determine the best possible location(s) from which a product or an ordered item should be fulfilled. It is used to allocate ordered items to source locations based on factors such as:

    • Available stock: Using current or replenished stock levels.
    • Cost of delivery: Selecting warehouses closer to the delivery location to minimize costs.
    • Order synergies: Sourcing an entire order from a single warehouse where most items are available.
    • Delivery time: Prioritizing speed over cost by selecting the fastest source location.

    Common integration points include:

    • Product Detail Pages (PDP): Restricting available quantity based on source stock or displaying estimated delivery times.
    • Checkout/Place Order: Validating that a cart can be fully sourced, showing potential shipping packages, or attaching source locations to backend systems via a PlaceOrder adapter.

  8. Understand the Payment Gateway and Payment Method concepts

    master

    The package distinguishes between two core concepts to manage payment processing:

    • PaymentGateway: A digital tool used to process online payment requests (e.g., credit card processing). It accepts a PaymentRequest.
    • PaymentMethod: Represents the specific way a customer pays, such as cash, checks, credit/debit cards, bank transfers, or online services like PayPal.

    The primary abstraction for implementing payment flows is the WebCartPaymentGateway interface.

  9. Ensure modules are runnable with FakeAdapters

    master

    To ensure a module is "runnable by default," it must provide FakeAdapters for its required secondary ports (interfaces used to communicate with external systems or infrastructure).

    • FakeAdapters: These are in-memory or simplified implementations of interfaces used for demonstration and development.
    • Activation: The binding of real Adapters (as opposed to FakeAdapters) should be controlled via a Feature Flag in the module's configuration.

  10. Implement product restrictions with RestrictionService

    master

    The RestrictionService allows you to enforce product limits (e.g., maximum quantities). You can add custom restrictions by using Dingo multibinding to the cart.MaxQuantityRestrictor interface.

    The service is triggered during cart add or update operations. It consolidates all bound restrictors and returns the most restrictive RestrictionResult, which includes:

    • Whether the restriction applies.
    • The maximum allowed quantity.
    • The remaining difference relative to the current cart.

  11. Understand Price, Charge, and Charges types

    master

    The Price module uses three primary value objects to handle monetary values and payments:

    • Price: A simple representation of a money value (e.g., 5€). Internally, it uses big.Float for high-precision calculations.
    • Charge: Combines a Price with a specific Type. This is used to add semantic meaning to a value or to describe payments in different currencies (e.g., paying a 5€ value using 500 Loyaltypoints).
    • Charges: A collection (list) of Charge objects. This allows representing a single total value through multiple payment methods (e.g., paying 5€ via two charges: 2€ cash and 300 Loyaltypoints).

  12. Understand the Checkout Controller flow

    master

    The Checkout Controller manages the end-customer journey through several sequential actions:

    1. StartAction (Optional): Checks authentication. If not logged in, shows the start template for login.
    2. Checkout Action: The main step where the checkout form is rendered. On valid submission, it updates the cart (billing, delivery info, payment gateway/method, vouchers, etc.).
      • If skipReviewAction is true: Proceeds to EarlyPlaceOrder and redirects to Payment Action.
      • If skipReviewAction is false: Redirects to Review Action.
    3. Review Action (Optional): Renders a review template. Upon confirmation, starts payment and EarlyPlaceOrder.
    4. Payment Action: Communicates with the Payment Gateway.
      • Error/Abort: Regenerates Idempotency Key and redirects back to checkout.
      • Success/Approved: Redirects to Place Order Action.
      • Unapproved: Renders payment template for frontend handling.
    5. Place Order Action: Checks if the order was already placed via EarlyPlaceOrder. If not, checks flow status and places the order, then redirects to Success Action.
    6. Success Action: Renders the order success template.