dakkah-cityos-commerce

System: Medusa (Headless Commerce) Layer: 6 - Commerce, Services & Economy Mission: The "Digital Marketplace" of CityOS. It handles product catalogs, shopping carts, checkout flows, and payment processing for all city services.

🏗️ Architecture

This repository hosts the Headless Commerce Engine. Unlike traditional e-commerce, it is designed to sell anything: physical goods, digital permits, or service bookings.

• Core: Node.js (Medusa Server)
• Database: PostgreSQL (Orders/Products) + Redis (Events)
• Storefront: Decoupled (Consumed by dakkah-cityos-experience and payload-full-code)
• Admin: Medusa Admin (bundled)

CityOS Role

• Unified Cart: A single shopping cart for paying a parking ticket, buying a museum pass, and ordering coffee.
• Payment Orchestrator: Routes payments to the correct provider (Stripe, Fawry, Local Bank) via Plugin Architecture.
• Tax & Compliance: Auto-calculates VAT and municipal fees.

🌟 Super App Integration

This system is the "Cash Register" of the Super App.

1. Service Discovery

• Domain Slug: commerce
• Announcement Topic: system.announce
• Routing Topic: workflow.request.commerce

2. Dynamic Tools (AI Capabilities)

The following tools are exposed to Cortex for transactional assistance:

Tool Name	Description	Input Schema
search_products	Finds purchasable items/services.	{ "query": "parking permit", "category": "civic" }
get_order_status	Checks delivery/completion status of an order.	{ "orderId": "ord_12345" }
create_cart	Initializes a transaction session.	{ "items": [{ "variantId": "123", "qty": 1 }] }

🚀 Quick Start

1. Prerequisites

• Node.js 18+
• PostgreSQL
• Redis

2. Setup

# Install dependencies
npm install

# Configure Environment
cp .env.template .env
# Set DATABASE_URL and REDIS_URL

# Run Migrations & Seed
npm run seed

3. Run (Local)

# Start Server (API + Admin)
npm run dev
# API: http://localhost:9000
# Admin: http://localhost:7001

🏗️ DevOps Infrastructure

CI/CD

• GitHub Workflow: .github/workflows/deploy.yml
• Strategy: Builds a single Docker container containing the Medusa core and all installed plugins.

Directory Structure

dakkah-cityos-commerce/
├── src/
│   ├── api/              # Custom Endpoints (e.g., CityBus Webhooks)
│   ├── services/         # Business Logic (Tax calculation override)
│   ├── subscribers/      # Event Listeners (Order Placed -> Notify CityBus)
│   └── loaders/          # Startup logic
├── data/                 # Seed data (Default products/regions)
└── medusa-config.js      # Main Configuration

🤝 Integration

• Inputs: Consumes user.created (IAM) to create Customer profiles.
• Outputs: Emits order.placed to dakkah-cityos-fulfillment and dakkah-cityos-erp.
• Dependency: Relies on dakkah-cityos-storage for product images.