Core Concepts

Platform Architecture & Concepts

Core domain models, system components, and architectural patterns powering the platform.
View as Markdown

The Plant Store Platform is a scalable, cloud-native API ecosystem designed to handle end-to-end plant inventory management, customer order fulfillment, and user authentication. It combines a RESTful OpenAPI 3.1 HTTP engine for synchronous CRUD operations with an AsyncAPI Event-Driven Broker for asynchronous state change streaming.

Core Domain Entities

The platform revolves around three primary domain entities:

Plants & Inventory

Represents biological plant items, metadata, taxonomy, tagging, photo media, and real-time inventory availability (available, pending, sold).

Orders & Fulfillment

Tracks purchasing lifecycle from initial order placement through payment validation, inventory allocation, shipment, and fulfillment.

Users & Access Control

Manages customer and administrator profiles, credentials, API tokens, session lifecycles, and role-based authorization scopes.

Architectural Principles

1. Dual Paradigm Integration (REST + Async)

  • Synchronous HTTP Operations: Used for direct state queries (e.g. searching plants by tag, fetching user details) and imperative command execution (e.g. creating a new plant, updating price).
  • Asynchronous Event-Driven Messaging: Used for decoupling long-running processes such as order status updates, stock notifications, and webhook delivery.

2. High-Availability Inventory Tracking

Inventory states transition deterministically:

[ Available ] ──(Order Placed)──> [ Pending ] ──(Order Approved)──> [ Sold ]
      │                                 │
      └───────(Order Cancelled)─────────┘

When an order is placed, plants are immediately reserved under pending status to prevent double-booking. If the payment or order is cancelled within the 15-minute checkout window, status automatically reverts to available.

3. Contract-First API Design

All endpoints, payload schemas, query parameters, and error types are strictly defined in standard OpenAPI 3.1 and AsyncAPI 2.x specifications. This ensures:

  • Type-safe auto-generated SDKs in TypeScript, Python, Go, and Java.
  • Interactive API Explorer sandbox testing.
  • Automated API contract verification on every pull request.

Next Steps

Explore the detailed conceptual guides and developer tutorials:

Authentication & Security

Learn how to secure API requests using API Keys and OAuth2 authorization flows.

Plant Management Guide

Learn how to create, search, tag, and manage plant inventory items.