Xeros Django E-commerce Agent

Expert AI assistant for the Xeros Django e-commerce platform - a modular monolithic application with multiple decoupled apps.

Overview

This skill provides deep knowledge of the Xeros Django architecture, enabling you to work efficiently with:

Project Architecture

Core Structure

Key Apps & Responsibilities

| App | Purpose |

|-----|---------|

| `core` | Base functionality, brand context processors |

| `catalog` | Product catalog management |

| `cart` | Session-based shopping cart |

| `orders` | Order processing and management |

| `userauths` | Custom user authentication |

| `payments` | Payment provider integrations |

| `integrations` | Third-party service integrations |

| `marketing` | Marketing features |

| `loyalty` | Customer loyalty programs |

| `reviews` | Product reviews |

| `returns` | Return management |

| `crm` | Customer relationship management |

| `api` | REST API (conditional, requires `ENABLE_REST_API=True`) |

Development Workflows

Initial Setup

```bash

Create virtual environment

python -m venv venv

Activate (Linux/Mac)

source venv/bin/activate

Activate (Windows)

venv\Scripts\activate

Install dependencies

pip install -r requirements.txt

Run migrations

python manage.py migrate

Create superuser

python manage.py createsuperuser

Collect static files

python manage.py collectstatic

Run development server

python manage.py runserver

```

Celery Worker

```bash

celery -A xeros_project worker -l info

```

Code Audit

```bash

Run static analysis from project root

python audit_xeros.py

Produces: audit_report.md and audit_findings.txt

```

Testing

```bash

Django test runner

python manage.py test

Or use pytest

pytest

```

Key Systems

Cart System (`cart/cart.py`)

Payment Integration (`payments/`)

**Providers**:

**Configuration**:

```python

Required environment variables

PAYPAL_CLIENT_ID

PAYPAL_SECRET

STRIPE_SECRET_KEY

STRIPE_PUBLISHABLE_KEY

```

**Public keys exposed via**: `payments.context_processors.payment_public_keys`

REST API (Conditional)

**Activation**:

1. Set `ENABLE_REST_API=True` in settings

2. Install: `pip install djangorestframework`

3. Add views in `api/` app

4. Register URLs in `xeros_project/urls.py`

Security (Production)

When `DEBUG=False`, the following are activated:

**Sensitive settings**: Store in `local_settings.py` or `.env`

Common Modification Patterns

Modify Cart Logic

**File**: `cart/cart.py`

**Example**: Add max quantity per product

```python

def add(self, product=None, product_id=None, qty=None, quantity=None, max_qty=None):

# Preserve session format

# Apply MIN_QTY, order_in_packs, and new max_qty constraint

# Update request.session[CART_SESSION_ID]

```

**Test**: Add unit test in `cart/tests.py`

Add New Route

**Example**: Checkout success page

1. **URL**: Add to `orders/urls.py`

```python

path('checkout/success/', views.checkout_success, name='checkout_success'),

```

2. **View**: Create in `orders/views.py`

```python

def checkout_success(request):

return render(request, 'orders/checkout_success.html')

```

3. **Template**: Create `orders/templates/orders/checkout_success.html`

Add Payment Provider

1. Create module: `payments/newprovider.py`

2. Add public keys to `payments/context_processors.py`

3. Store secrets in `local_settings.py`:

```python

NEWPROVIDER_CLIENT_ID = env('NEWPROVIDER_CLIENT_ID')

NEWPROVIDER_SECRET = env('NEWPROVIDER_SECRET')

```

Enable REST API

1. **Settings**: Add to `xeros_project/settings.py`

```python

ENABLE_REST_API = True

INSTALLED_APPS += ['rest_framework']

```

2. **Install**: `pip install djangorestframework`

3. **Create views**: `api/views.py`

4. **Register URLs**: `xeros_project/urls.py`

Code Conventions

Observed Patterns

Quality Tools

Example Prompts

Cart Modifications

"Modify `cart.Cart.add` to enforce a max_qty constraint per product. Update the session storage format and add a unit test in `cart/tests.py`."

Route Creation

"Add a route named `checkout_success` in `orders/urls.py` and create the corresponding template `orders/checkout_success.html` with order confirmation details."

Payment Integration

"Integrate a new payment provider 'Mollie'. Create `payments/mollie.py`, expose public keys via context processor, and add webhook handling."

API Development

"Enable the REST API, create an endpoint at `/api/products/featured/` that returns top 10 products by sales, and add pagination."

Testing

"Write integration tests for the cart system covering add, update, remove, and clear operations. Include edge cases for pack ordering."

Important Files Reference

| File/Directory | Purpose |

|----------------|---------|

| `xeros_project/settings.py` | Main configuration |

| `xeros_project/celery.py` | Async task configuration |

| `cart/cart.py` | Shopping cart class |

| `payments/paypal.py` | PayPal integration |

| `payments/stripe_api.py` | Stripe integration |

| `audit_xeros.py` | Static analysis tool |

| `requirements.txt` | Python dependencies |

| `local_settings.py` | Local/secret configuration (gitignored) |

| `*/tests.py` or `*/tests/` | Test modules |

Notes

This skill enables efficient navigation and modification of the Xeros Django e-commerce platform while maintaining architectural integrity and following established patterns.