🎉 Aerocall is now live! Start building →
E-commerceCore Concepts

E-commerce Core Concepts & Architecture

This document outlines the fundamental architectural concepts of the Aerocall E-commerce system. Understanding these concepts is crucial for both administrators managing the store and developers building storefronts.

1. High-Level Architecture

The E-commerce module is built on a Headless Architecture.

  • Backend (Aerocall API): Handles all logic, database, payment processing, and inventory management.
  • Frontend (Storefront): You build this! It communicates with the API to display products and process checkouts.

Key Entities

  • Project: The top-level container (your website or app).
  • Product: An item available for sale.
  • Product Type (Component): Defines the structure of a product (e.g., specific fields for “T-Shirts” vs “Laptops”).
  • Order: A record of a completed transaction.
  • Collection (Category): A way to group products.

2. The Power of “Product Types” (Components)

Unlike traditional e-commerce platforms with fixed fields, Aerocall uses a flexible schema system.

The Problem

A T-Shirt needs fields like Size, Color, Fabric. A Laptop needs CPU, RAM, Screen Size. Forcing both into a generic “Description” field is messy.

The Solution: Product Types

A Product Type is simply a Component in Aerocall.

  1. You create a Component called “Apparel” with fields for Size and Color.
  2. You create a Product and select “Apparel” as its Type.
  3. The Admin UI automatically generates a form with those specific fields.
  4. The API returns those specific fields in a data object.

(Diagram: Product Type (Component) defines schema for Products)

  • Component ‘Apparel’ defines schema for Product ‘Blue T-Shirt’ and Product ‘Red Hoodie’
  • Component ‘Laptop’ defines schema for Product ‘MacBook Pro’

3. Product Structure

A Product entity combines standard e-commerce fields with your custom schema data.

FieldTypePurpose
nameStringStandard name (e.g., “Blue T-Shirt”).
slugStringURL-friendly ID (e.g., “blue-t-shirt”).
priceNumberBase price in store currency.
inventoryIntegerStock count.
schema_component_idIDLinks to the Product Type (Component).
dataJSONDynamic fields defined by the Component (e.g., { "size": "M", "color": "Blue" }).

4. Collections (Categories)

Collections organize your content.

  • Hierarchy: Collections can have parents, allowing for nested trees (e.g., Men -> Clothing -> Shirts).
  • Flexibility: A product can belong to a primary collection, but you can also use Tags or custom relationships for more complex groupings.

5. The Checkout Flow

The checkout process is designed to be secure and atomic.

  1. Cart Creation: A visitor adds items to a specialized “Cart” object (stored server-side, referenced by ID).
  2. Checkout Initialization: The Cart is converted into a draft Order.
  3. Payment Processing: The system communicates with a Payment Provider (e.g., Stripe).
  4. Order Finalization: Upon successful payment, the Order is marked paid, inventory is deducted, and webhooks are fired.

6. Globalization (Settings)

Store-wide settings control how money and shipping work.

  • Currency: Defined globally for the project (e.g., USD, EUR).
  • Tax Rules: Configured to apply automatically at checkout.
  • Shipping: Flat rates or free shipping thresholds.

Terminology Glossary

  • SKU (Stock Keeping Unit): A unique identifier for each distinct product or variant.
  • Variant: A specific version of a product (e.g., “Size M” is a variant of “Blue T-Shirt”). Note: Currently managed via separate Products or custom schema arrays.
  • Slug: The part of a URL that identifies a page in a human-readable format.
  • Webhook: An automated message sent from apps when something happens (e.g., “Order Paid”).
Getting StartedAdmin Guide