unchained icon indicating copy to clipboard operation
unchained copied to clipboard
verified publisher icon unchainedshop

DOCS !!!$!%! 😡🤬🤯

Open pozylon opened this issue 1 year ago • 4 comments

New Highlevel Structure:

  1. Introduction
    1. Core Values
    2. Cart Behavior
  2. Quick Start
    1. Create Project
    2. Example Storefront
    3. Admin UI
  3. Platform configuration
    1. Boot
    2. Core Module Options
    3. Extend your GraphQL API
  4. Catalog
    1. Directed Acyclic Graph (DAG)
    2. Product Types
    3. Filters
      1. Faceting
      2. Sorting
      3. Aggregation
  5. Pricing
    1. Product Pricing
    2. Order Pricing
    3. Discounting
    4. Currency Conversion Rates
  6. Order Fullfillment
    1. Order States
    2. Payment
    3. Delivery
    4. Warehousing
  7. Notifications
    1. Messaging
    2. Built-in Templates
    3. React to System Events
  8. Tutorials
    1. Weather Dependent Sausage Pricing
    2. IAM Integration (Keycloak OIDC)
    3. CMS Integration (GraphQL Schema Stitching)
    4. Enterprise Search Integration (Apache Solr)
  9. Advanced Techniques
    1. Extend Unchained Core
    2. Bulk Import
    3. Custom Roles / Permissions
    4. Custom Fields
    5. Custom Event Bus
    6. Quotation Workflow
    7. Event Ticketing
    8. Subscriptions
  10. Deployment
    1. Environment Variable Overview
    2. Deploy with Docker
    3. Deploy to Vercel
  11. Plugins
    1. …
  12. GraphQL API
  13. Changelog

pozylon avatar Dec 17 '24 18:12 pozylon

Notifications should answer:

  • How does Messaging work? (Explain that a message is a work item that then gets transformed to some messaging plugin-specific channel like twilio, email, ...)
  • How can I customize the default messages, adjust the order confirmation template as an example
  • What messaging plugins exist already? How do I write a new Messaging plugin? (= worker)
  • How can i send one, multiple or no e-mail for the various messaging types?
  • How can I register new custom template types and wire those up with some arbitrary unchained event?

pozylon avatar Jan 10 '25 14:01 pozylon

Prepared by AI, usable?

`# Concept for Unchained Engine Getting Started Guide

Based on my analysis of the Unchained Engine codebase, I've created a comprehensive concept for a developer-focused Getting Started guide that targets intermediate developers with some e-commerce experience and uses a general-purpose shop with physical products as the primary example.

Guide Structure

graph TD
    A[Introduction to Unchained Engine] --> B[Setting Up Your Development Environment]
    B --> C[Understanding Unchained Architecture]
    C --> D[Creating Your First Shop]
    D --> E[Extending Unchained Engine]
    E --> F[Deployment and Production Considerations]
    F --> G[Troubleshooting and Resources]

Detailed Outline

1. Introduction to Unchained Engine

1.1 What is Unchained Engine?

  • Overview of Unchained Engine as a modular, API-first e-commerce platform
  • Key features and benefits
  • Comparison with other e-commerce platforms
  • Use cases and examples

1.2 Core Concepts

  • Modular architecture
  • API-first approach
  • Plugin system
  • Event-driven design

1.3 Technology Stack

  • Node.js and TypeScript
  • MongoDB
  • GraphQL
  • Fastify/Express

2. Setting Up Your Development Environment

2.1 Prerequisites

  • Node.js (v22+) and npm (v10+)
  • MongoDB
  • Git
  • Code editor recommendations

2.2 Installation Options

  • Using the minimal example
  • Using the kitchensink example
  • Creating a project from scratch

2.3 Step-by-Step Setup

  • Cloning the repository
  • Installing dependencies
  • Environment configuration
  • Starting the development server

2.4 Verifying Your Setup

  • Accessing the GraphQL API
  • Using GraphQL playground
  • Running basic queries

3. Understanding Unchained Architecture

graph TD
    A[Platform] --> B[Core]
    A --> C[API]
    B --> D[Core Modules]
    D --> E[Products]
    D --> F[Assortments]
    D --> G[Orders]
    D --> H[Users]
    D --> I[Payment]
    D --> J[Delivery]
    D --> K[Other Core Modules]
    A --> L[Plugins]
    L --> M[Payment Plugins]
    L --> N[Delivery Plugins]
    L --> O[Pricing Plugins]
    L --> P[Other Plugins]

3.1 Platform Structure

  • Monorepo organization
  • Package dependencies
  • Module system

3.2 Core Modules

  • Products and variations
  • Assortments (categories)
  • Orders and cart
  • Users and authentication
  • Payment processing
  • Delivery methods
  • Other core modules

3.3 Plugin System

  • Plugin architecture
  • Available plugin types
  • Plugin registration and configuration

3.4 API Layer

  • GraphQL schema
  • Query and mutation patterns
  • Authentication and authorization

3.5 Event System

  • Event-driven architecture
  • Event types and handlers
  • Custom event creation

4. Creating Your First Shop

4.1 Project Structure

  • Recommended file organization
  • Configuration files
  • Environment variables

4.2 Basic Shop Setup

  • Initializing the platform
  • Setting up languages, currencies, and countries
  • Creating an admin user

4.3 Product Management

  • Creating product types
  • Adding products and variations
  • Managing product media and texts
  • Setting up pricing

4.4 Assortment Management

  • Creating assortments (categories)
  • Organizing products in assortments
  • Building navigation structures

4.5 Payment and Delivery

  • Configuring payment methods
  • Setting up delivery options
  • Testing the checkout process

4.6 User Management

  • User registration and authentication
  • User roles and permissions
  • Guest checkout vs. registered users

5. Extending Unchained Engine

5.1 Creating Custom Plugins

  • Plugin development patterns
  • Plugin types and interfaces
  • Testing and debugging plugins

5.2 Custom Payment Providers

  • Payment provider interface
  • Implementing payment flows
  • Testing payment integrations

5.3 Custom Delivery Providers

  • Delivery provider interface
  • Implementing shipping calculations
  • Tracking and fulfillment

5.4 Custom Pricing Logic

  • Pricing plugin interface
  • Implementing discounts and promotions
  • Tax calculation

5.5 Extending the GraphQL API

  • Adding custom queries and mutations
  • Extending existing types
  • API versioning considerations

5.6 Custom Event Handlers

  • Creating event listeners
  • Processing events asynchronously
  • Event-driven workflows

6. Deployment and Production Considerations

6.1 Deployment Options

  • Docker-based deployment
  • Cloud hosting recommendations
  • Scaling considerations

6.2 Performance Optimization

  • Database indexing
  • Caching strategies
  • Query optimization

6.3 Security Best Practices

  • Authentication security
  • API security
  • Payment security

6.4 Monitoring and Logging

  • Logging configuration
  • Error handling
  • Performance monitoring

7. Troubleshooting and Resources

7.1 Common Issues and Solutions

  • Startup problems
  • Database connection issues
  • Plugin configuration problems

7.2 Debugging Techniques

  • Debugging the API
  • Debugging plugins
  • Troubleshooting events

7.3 Community and Support

  • GitHub repository
  • Community forums
  • Commercial support options

7.4 Further Learning

  • Advanced topics
  • Related resources
  • Keeping up with updates

Sample Code Examples

Throughout the guide, we'll include practical code examples for key tasks:

Example 1: Initializing the Platform

import Fastify from 'fastify';
import { startPlatform } from '@unchainedshop/platform';
import baseModules from '@unchainedshop/plugins/presets/base.js';
import connectBasePluginsToFastify from '@unchainedshop/plugins/presets/base-fastify.js';
import { connect, unchainedLogger } from '@unchainedshop/api/lib/fastify/index.js';

const fastify = Fastify({
  loggerInstance: unchainedLogger('fastify'),
  disableRequestLogging: true,
  trustProxy: process.env.NODE_ENV !== 'production',
});

try {
  const platform = await startPlatform({
    modules: baseModules,
  });

  connect(fastify, platform, {
    allowRemoteToLocalhostSecureCookies: process.env.NODE_ENV !== 'production',
  });

  connectBasePluginsToFastify(fastify);

  await fastify.listen({ port: process.env.PORT ? parseInt(process.env.PORT) : 3000 });
} catch (err) {
  fastify.log.error(err);
  process.exit(1);
}

Example 2: Creating a Product

// Creating a simple product
const productId = await modules.products.create({
  type: 'SimpleProduct',
  title: 'My First Product',
  slugs: ['my-first-product'],
});

// Adding product texts
await modules.products.texts.updateTexts(
  { productId },
  {
    title: 'My First Product',
    subtitle: 'An amazing product',
    description: 'This is a detailed description of my first product.',
    slug: 'my-first-product',
  },
  { languageId: 'en' }
);

// Setting the price
await modules.products.prices.updatePrice(
  { productId },
  {
    amount: 2990, // $29.90
    currencyCode: 'USD',
  }
);

Example 3: Creating a Custom Payment Plugin

import { PaymentAdapter, PaymentContext, PaymentCredentials } from '@unchainedshop/core-payment';

class MyCustomPaymentAdapter extends PaymentAdapter {
  static key = 'shop.my-custom-payment';
  static version = '1.0';
  static label = 'My Custom Payment';
  static type = 'INVOICE';

  async configurationError(): Promise<string | null> {
    // Validate configuration
    return null;
  }

  async isActive(): Promise<boolean> {
    // Check if this payment method is active
    return true;
  }

  async validate(payment: any, context: PaymentContext): Promise<boolean> {
    // Validate payment data
    return true;
  }

  async charge(payment: any, context: PaymentContext): Promise<PaymentCredentials> {
    // Process payment
    return {
      token: 'payment-token',
    };
  }
}

// Register the adapter
PaymentAdapter.registerAdapter(MyCustomPaymentAdapter);

Interactive Elements

The guide will include interactive elements to enhance the learning experience:

  1. Step-by-Step Tutorials: Guided walkthroughs for setting up key components
  2. Code Snippets: Ready-to-use code examples with explanations
  3. Architecture Diagrams: Visual representations of the system components
  4. Troubleshooting Tips: Common issues and their solutions
  5. Best Practices: Recommendations for efficient development

Conclusion

This Getting Started guide will provide intermediate developers with a comprehensive introduction to Unchained Engine, focusing on setup, architecture, and extension. By using a general-purpose shop with physical products as the primary example, developers will gain practical knowledge that they can apply to their own e-commerce projects.

The guide will emphasize the modular and extensible nature of Unchained Engine, showing developers how to leverage its architecture to create custom e-commerce solutions that meet their specific requirements. No newline at end of file `

pozylon avatar Mar 27 '25 05:03 pozylon

Add https://github.com/unchainedshop/unchained/issues/633

pozylon avatar Apr 25 '25 13:04 pozylon

Add https://github.com/unchainedshop/unchained/issues/554

pozylon avatar May 02 '25 20:05 pozylon