orion/docs/getting-started/cms-quick-start.md

CMS Quick Start Guide

A quick reference for setting up and using the Content Management System.

What is the CMS?

The CMS allows you to manage static content pages (About, Contact, FAQ, etc.) with:

• Platform defaults - Base content for all stores
• Store overrides - Custom content per store
• Automatic fallback - Stores inherit platform defaults unless overridden

Quick Setup

1. Create Default Content Pages

After running migrations, create the default CMS pages:

make create-cms-defaults

This creates 7 platform default pages:

• About Us (/about)
• Contact Us (/contact)
• FAQ (/faq)
• Shipping Policy (/shipping)
• Return & Refund Policy (/returns)
• Privacy Policy (/privacy)
• Terms of Service (/terms)

2. Full Database Setup

For a complete setup including CMS:

make db-setup
# Runs: migrations → admin user → CMS pages → demo data

Accessing Pages

All CMS pages are accessible on your shop frontend:

# For domain/subdomain access
https://wizamart.shop/about
https://fashionhub.store/contact

# For path-based access
http://localhost:8000/store/wizamart/faq
http://localhost:8000/stores/fashionhub/shipping

Managing Content

Via Admin Panel

1. Log in to admin panel: /admin/login
2. Navigate to Content Pages section
3. Create/edit platform defaults (visible to all stores)

Via Store Dashboard

1. Log in to store dashboard: /store/{code}/login
2. Navigate to Content Pages section
3. View platform defaults
4. Create store-specific overrides

Via API

Admin - Create Platform Default:

POST /api/v1/admin/content-pages/platform
{
  "slug": "about",
  "title": "About Us",
  "content": "<p>...</p>",
  "is_published": true,
  "show_in_footer": true
}

Store - Create Override:

POST /api/v1/store/{store_code}/content-pages
{
  "slug": "about",
  "title": "About Our Store",
  "content": "<p>Custom content...</p>",
  "is_published": true
}

Public - Retrieve Page:

GET /api/v1/shop/content-pages/{slug}

How the Two-Tier System Works

Lookup Priority

When a customer visits /about:

1. Check store override - Does this store have a custom "about" page?
2. Fallback to platform - If not, use the platform default "about" page
3. 404 if neither - Return 404 if no page exists

Example Scenario

Platform Default:

• Slug: about
• Title: "About Our Platform"
• Content: Generic platform description

WizaMart Override:

• Slug: about
• Title: "About WizaMart"
• Content: WizaMart-specific content

Result:

• wizamart.shop/about → Shows WizaMart custom version
• fashionhub.store/about → Shows platform default (no override)

Footer Navigation

Pages marked with show_in_footer: true automatically appear in the shop footer:

<!-- Footer automatically loads from database -->
<footer>
  <div>Quick Links</div>
  <ul>
    <li><a href="/products">Products</a></li>
    <li><a href="/about">About Us</a></li>  <!-- From CMS -->
    <li><a href="/contact">Contact</a></li>  <!-- From CMS -->
  </ul>
</footer>

Common Tasks

Add a New Default Page

python -c "
from app.core.database import SessionLocal
from app.services.content_page_service import content_page_service

db = SessionLocal()
content_page_service.create_page(
    db,
    slug='careers',
    title='Careers',
    content='<h1>Join Our Team</h1>...',
    is_published=True,
    show_in_footer=True
)
db.close()
"

Create Store Override

Via store API or dashboard - stores can override any platform default by creating a page with the same slug.

Update Platform Default

Via admin panel or API - updates affect all stores who haven't created an override.

Re-running the Script

The script is idempotent - safe to run multiple times:

make create-cms-defaults
# Output: "Skipped: About Us (/about) - already exists"

Existing pages are never overwritten.

Documentation

For complete CMS documentation, see:

• CMS Feature Documentation
• CMS Implementation Guide
• Database Seeder Guide

Troubleshooting

Pages not showing in footer

Check show_in_footer flag:

SELECT slug, title, show_in_footer FROM content_pages WHERE store_id IS NULL;

Store override not working

Verify slug matches exactly:

SELECT store_id, slug, title FROM content_pages WHERE slug = 'about';

404 on content pages

1. Check page is published: is_published = true
2. Verify migration was applied: make migrate-status
3. Run CMS defaults: make create-cms-defaults

Next Steps

• Customize default content via admin panel
• Create store-specific overrides
• Add new custom pages as needed
• Update footer navigation preferences