> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.definitely.live/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.definitely.live/_mcp/server.

# Platform Architecture & Concepts

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.

```mermaid
graph TD
    Client[Client Applications / SDKs] -->|HTTP / REST| API Gateway[API Gateway / Router]
    Client -->|WebSocket / Webhooks| EventBroker[Async Event Streaming]
    
    subgraph Core Platform
        API Gateway --> Auth[Auth & Session Service]
        API Gateway --> PlantSvc[Plant Inventory Service]
        API Gateway --> OrderSvc[Order Processing Engine]
        
        OrderSvc -->|Publish Order Events| EventBroker
        PlantSvc -->|Publish Inventory Updates| EventBroker
    end
    
    subgraph Data Stores
        Auth --> AuthDB[(User & Token DB)]
        PlantSvc --> PlantDB[(Plant & Catalog DB)]
        OrderSvc --> OrderDB[(Order & Reservation DB)]
    end
```

---

## 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](/concepts/authentication)

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

#### [Plant Management Guide](/guides/plant-management)

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