# AMSOIL Dealer Landing Pages - Architecture

This document provides comprehensive architecture diagrams for the AMSOIL DLP platform, covering data models, tech stack, data pipelines, user journeys, sitemap, and subscription tiers.

## Table of Contents

- [Data Model](#data-model)
- [Tech Stack](#tech-stack)
- [Data Pipeline](#data-pipeline)
- [User Journeys](#user-journeys)
- [Sitemap](#sitemap)
- [Subscription Tiers](#subscription-tiers)
- [Editor Access](#editor-access)

---

## Data Model

The platform uses PostgreSQL with Prisma ORM. Below is the entity relationship diagram showing all database models and their relationships.

### Core Entities

```mermaid
erDiagram
    User ||--o{ Account : "has many"
    User ||--o| Dealer : "has one"
    User ||--o{ AdminAction : "performs"
    User ||--o{ DealerNote : "writes"

    Dealer ||--o{ Page : "has many"
    Dealer ||--o{ NavigationItem : "has many"
    Dealer ||--o{ DealerLink : "has many"
    Dealer ||--o{ MediaAsset : "has many"
    Dealer ||--o{ PageView : "tracks"
    Dealer ||--o{ LinkClick : "tracks"
    Dealer ||--o{ Lead : "receives"
    Dealer ||--o{ DealerNote : "has many"

    Page ||--o{ NavigationItem : "linked from"
    Page ||--o{ DealerLink : "linked from"

    NavigationItem ||--o{ NavigationItem : "parent-child"

    User {
        string id PK
        string email UK
        datetime emailVerified
        string password
        string name
        string image
        string role "dealer|admin"
        string impersonatedById FK
        datetime impersonatedAt
        datetime impersonationExpiry
        datetime createdAt
        datetime updatedAt
    }

    Account {
        string id PK
        string userId FK
        string type
        string provider
        string providerAccountId
        string refresh_token
        string access_token
        int expires_at
        string token_type
        string scope
        string id_token
        string session_state
    }

    Dealer {
        string id PK
        string userId FK UK
        string subdomain UK
        string domain
        string domainPrefix
        string customDomain UK
        string customDomainStatus
        string subscriptionTier
        string stripeCustomerId UK
        string stripeSubscriptionId UK
        string dealerNumber
        string businessName
        string phone
        string address
        string city
        string state
        string zip
        string country
        json contactData
        json socialLinks
        json pageContent
        json settings
        json heroSlider
        boolean hasLeadForm
        string status "pending|active|suspended"
        datetime lastPublishedAt
        datetime createdAt
        datetime updatedAt
    }

    Page {
        string id PK
        string dealerId FK
        string slug
        string title
        string type "page|blog"
        json puckData
        string rawHtml
        boolean isMigrated
        string metaTitle
        string metaDescription
        string featuredImage
        string excerpt
        string author
        string status "draft|published"
        datetime publishedAt
        datetime publishScheduledFor
        datetime createdAt
        datetime updatedAt
    }

    NavigationItem {
        string id PK
        string dealerId FK
        string label
        string pageId FK
        string externalUrl
        string parentId FK
        int sortOrder
        boolean isDefault
        string defaultKey
        int defaultSortOrder
        boolean openInNewTab
        boolean isVisible
        datetime createdAt
        datetime updatedAt
    }

    DealerLink {
        string id PK
        string dealerId FK
        string label
        string linkType "page|external"
        string pageId FK
        string externalUrl
        boolean openInNewTab
        int sortOrder
        datetime createdAt
        datetime updatedAt
    }
```

### Media and Analytics Entities

```mermaid
erDiagram
    Dealer ||--o{ MediaAsset : "uploads"
    Dealer ||--o{ PageView : "tracks"
    Dealer ||--o{ LinkClick : "tracks"
    Dealer ||--o{ Lead : "captures"

    MediaAsset {
        string id PK
        string dealerId FK
        string cloudflareId UK
        string url
        string filename
        string mimeType
        int size
        int width
        int height
        string alt
        string context
        datetime createdAt
        datetime updatedAt
    }

    AmsoilImage {
        string id PK
        string cloudflareId UK
        string url
        string filename
        string mimeType
        int size
        int width
        int height
        string name
        string category
        string description
        string[] tags
        int sortOrder
        boolean isActive
        string createdBy
        datetime createdAt
        datetime updatedAt
    }

    PageView {
        string id PK
        string dealerId FK
        string path
        string referrer
        string userAgent
        datetime timestamp
    }

    LinkClick {
        string id PK
        string dealerId FK
        string sourcePath
        string targetHref
        string clickType
        datetime timestamp
    }

    Lead {
        string id PK
        string dealerId FK
        string name
        string email
        string message
        string phone
        datetime timestamp
    }
```

### Admin and System Entities

```mermaid
erDiagram
    User ||--o{ AdminAction : "performs"
    User ||--o{ DealerNote : "writes"
    Dealer ||--o{ DealerNote : "receives"

    AdminAction {
        string id PK
        string adminUserId FK
        string action
        string targetType
        string targetId
        json details
        string reason
        string ipAddress
        string userAgent
        string impersonatedUserId FK
        datetime createdAt
    }

    DealerNote {
        string id PK
        string dealerId FK
        string adminId FK
        string content
        string noteType "manual|support_call|email_sent|internal"
        boolean isAutomatic
        json metadata
        string updatedBy
        datetime createdAt
        datetime updatedAt
    }

    StripeWebhookEvent {
        string id PK
        string stripeEventId UK
        string eventType
        boolean processed
        datetime createdAt
    }

    PendingRegistration {
        string id PK
        string email UK
        string passwordHash
        string tokenHash UK
        datetime expiresAt
        datetime lastSentAt
        int sendCount
        string callbackUrl
        datetime createdAt
        datetime updatedAt
    }

    PasswordResetToken {
        string id PK
        string email UK
        string tokenHash UK
        datetime expiresAt
        datetime lastSentAt
        int sendCount
        datetime createdAt
        datetime updatedAt
    }
```

---

## Tech Stack

The application is built on a modern full-stack architecture with Next.js at its core.

```mermaid
block-beta
    columns 3

    block:frontend["Frontend"]:3
        columns 3
        nextjs["Next.js 16\nApp Router"]
        react["React 19"]
        tailwind["Tailwind CSS 4"]
        typescript["TypeScript 5"]
        lucide["Lucide Icons"]
        swiper["Swiper\nCarousel"]
    end

    block:cms["CMS & Editing"]:3
        columns 3
        puck["Puck Editor\nVisual Page Builder"]
        lexical["Lexical\nRich Text Editor"]
        dndkit["dnd-kit\nDrag & Drop"]
        dompurify["DOMPurify\nHTML Sanitization"]
        cropper["Cropper.js\nImage Cropping"]
        space1[" "]
    end

    block:backend["Backend"]:3
        columns 3
        prisma["Prisma 7\nORM"]
        postgres["PostgreSQL\nDatabase"]
        nextauth["NextAuth.js\nAuthentication"]
        zod["Zod\nValidation"]
        pino["Pino\nLogging"]
        bcrypt["bcrypt\nPassword Hashing"]
    end

    block:services["External Services"]:3
        columns 3
        stripe["Stripe\nPayments & Billing"]
        cloudflare["Cloudflare\nCDN & Images"]
        resend["Resend\nTransactional Email"]
        google["Google OAuth"]
        apple["Apple OAuth"]
        space2[" "]
    end

    block:infra["Infrastructure & DevOps"]:3
        columns 3
        deployhq["DeployHQ\nCI/CD"]
        pm2["PM2\nProcess Manager"]
        cpanel["cPanel\nServer Management"]
        jest["Jest\nTesting"]
        eslint["ESLint & Prettier\nCode Quality"]
        husky["Husky\nGit Hooks"]
    end
```

### Technology Stack Summary

| Layer              | Technologies                                                                  |
| ------------------ | ----------------------------------------------------------------------------- |
| **Frontend**       | Next.js 16 (App Router), React 19, Tailwind CSS 4, TypeScript 5, Lucide Icons |
| **CMS**            | Puck Editor, Lexical WYSIWYG, dnd-kit, DOMPurify, Cropper.js                  |
| **Backend**        | Prisma 7, PostgreSQL, NextAuth.js, Zod, Pino, bcrypt                          |
| **Services**       | Stripe, Cloudflare (CDN + Images), Resend, Google OAuth, Apple OAuth          |
| **Infrastructure** | DeployHQ, PM2, cPanel, Jest, ESLint, Prettier, Husky                          |

---

## Data Pipeline

The platform handles multiple data flows for authentication, billing, content management, and analytics.

### Authentication Flow

```mermaid
flowchart LR
    subgraph OAuth["OAuth Providers"]
        google["Google OAuth"]
        apple["Apple OAuth"]
    end

    subgraph Email["Email Auth"]
        register["Register Form"]
        verify["Email Verification"]
        reset["Password Reset"]
    end

    subgraph Auth["NextAuth.js"]
        nextauth["Auth Handler"]
        session["Session Manager"]
        jwt["JWT Token"]
    end

    subgraph DB["Database"]
        user["User"]
        account["Account"]
        pending["PendingRegistration"]
    end

    google --> nextauth
    apple --> nextauth
    register --> pending
    pending --> verify
    verify --> nextauth
    reset --> user
    nextauth --> session
    session --> jwt
    nextauth --> user
    nextauth --> account
```

### Billing Flow

```mermaid
flowchart LR
    subgraph Checkout["Checkout"]
        plans["Plan Selection"]
        stripe_checkout["Stripe Checkout"]
    end

    subgraph Webhooks["Stripe Webhooks"]
        created["checkout.session.completed"]
        sub_created["customer.subscription.created"]
        updated["customer.subscription.updated"]
        deleted["customer.subscription.deleted"]
    end

    subgraph Handlers["Webhook Handlers"]
        process["Process Event"]
        dedupe["Deduplicate"]
        tier_change["Tier Change Handler"]
    end

    subgraph DB["Database"]
        dealer["Dealer"]
        nav["NavigationItem"]
        webhook_log["StripeWebhookEvent"]
    end

    plans --> stripe_checkout
    stripe_checkout --> created
    created --> process
    sub_created --> process
    updated --> process
    deleted --> process
    process --> dedupe
    dedupe --> webhook_log
    dedupe --> dealer
    dealer --> tier_change
    tier_change --> nav
```

### CMS Pipeline

```mermaid
flowchart LR
    subgraph Editors["CMS Editors"]
        puck["Puck Editor"]
        lexical["Lexical Editor"]
        nav_editor["Nav Editor"]
        slider["Slider Editor"]
        links["Link Editor"]
    end

    subgraph API["API Routes"]
        cms_api["CMS API\n/api/cms/*"]
        dealer_api["Dealer API\n/api/dealer/*"]
        zo_guard["requireZo\n(lib/zo-guard)"]
    end

    subgraph DB["Database"]
        pages["Page"]
        navigation["NavigationItem"]
        dealer["Dealer"]
        dealer_links["DealerLink"]
    end

    subgraph Cache["ISR Cache"]
        revalidate["Revalidation Trigger"]
        cache["Static Pages"]
    end

    puck --> cms_api
    lexical --> cms_api
    nav_editor --> cms_api
    slider --> dealer_api
    links --> cms_api
    cms_api --> zo_guard
    dealer_api --> zo_guard
    zo_guard --> pages
    zo_guard --> dealer
    cms_api --> navigation
    cms_api --> dealer_links
    pages --> revalidate
    navigation --> revalidate
    dealer --> revalidate
    revalidate --> cache
```

> **ZO guard:** Dealer-initiated (re)publish on `/api/dealers/[id]/publish`, `/api/cms/publish`, and `/api/cms/pages/[id]` is gated by `lib/zo-guard.ts` - a missing/blank `dealerNumber` returns `422 ZO_REQUIRED` before any DB write. System revalidation (`/api/admin/dealers/[id]/revalidate`) is intentionally exempt. See [ZO Number Compliance](./ZO_NUMBER_COMPLIANCE.md).

### Public Site Render

**Proxy routing overview (`proxy.ts`):**

- **Internal dealer-site routes** live at `/sites/[subdomain]/[domainSlug]/*` (renamed from `/dealers/*`). The proxy rewrites dealer subdomains and active custom domains there; direct `/sites/*` hits on production 301 to the dealer's canonical host (method-guard + bot-probe protection moved here too).
- **Apex stub homepages:** an unauthenticated `/` on the 4 production apex domains rewrites to `/home/{slug}` (`app/home/[domainSlug]`, config in `lib/apex-config.ts`). `amsoil.aimclear.com` and non-production hosts keep `public/index.html`. Authenticated `/` still redirects to `/dashboard`; `/landing` still redirects to `/`.
- **Public dealer directory:** `/dealers` → `/directory/{slug}` and `/dealers/{region}` → `/directory/{slug}/{region}` on apex hosts (`app/directory/[domainSlug]`). Direct `/directory/*` hits on production 308 to the public URL.
- **robots.txt** disallows the three internal rewrite targets `/sites/`, `/home/`, `/directory/` (the public `/dealers` directory is intentionally crawlable).

```mermaid
flowchart LR
    subgraph Request["Incoming Request"]
        route["Route\n/sites/[subdomain]/[domainSlug]/*"]
    end

    subgraph Lookup["Data Lookup"]
        find_dealer["Find Dealer"]
        find_page["Find Page"]
        find_nav["Get Navigation"]
    end

    subgraph Render["Puck Render"]
        components["Puck Components"]
        layout["Layout Template"]
    end

    subgraph Output["Response"]
        html["HTML Output"]
        isr["ISR Cache"]
    end

    route --> find_dealer
    find_dealer --> find_page
    find_dealer --> find_nav
    find_page --> components
    find_nav --> layout
    components --> html
    layout --> html
    html --> isr
```

### Analytics Pipeline

```mermaid
flowchart LR
    subgraph Trackers["Client-Side Trackers"]
        pageview["Page View Tracker"]
        linkclick["Link Click Tracker"]
    end

    subgraph API["Stats API"]
        events["POST /api/stats/events"]
        dashboard["GET /api/stats/dashboard"]
    end

    subgraph DB["Database"]
        pv["PageView"]
        lc["LinkClick"]
    end

    subgraph Dashboard["Analytics Dashboard"]
        charts["Charts & Metrics"]
        reports["Reports"]
    end

    pageview --> events
    linkclick --> events
    events --> pv
    events --> lc
    pv --> dashboard
    lc --> dashboard
    dashboard --> charts
    dashboard --> reports
```

### Lead Capture Flow

```mermaid
flowchart LR
    subgraph Form["Lead Form"]
        visitor["Visitor"]
        form["Contact Form"]
    end

    subgraph API["Contact API"]
        contact["POST /api/contact"]
        validate["Validate & Sanitize"]
    end

    subgraph Services["Services"]
        resend["Resend Email"]
        db["Database"]
    end

    subgraph Notification["Notifications"]
        dealer_email["Email to Dealer"]
        lead_record["Lead Record"]
    end

    visitor --> form
    form --> contact
    contact --> validate
    validate --> resend
    validate --> db
    resend --> dealer_email
    db --> lead_record
```

---

## User Journeys

### New Dealer Registration

```mermaid
flowchart TD
    start["Landing Page\n/"]

    subgraph Auth["Authentication"]
        oauth["Choose OAuth\nGoogle/Apple"]
        email["Email Signup"]
        verify["Email Verification"]
    end

    subgraph Onboarding["Onboarding"]
        terms["Accept Terms\n/registration/terms"]
        info["Dealer Information\n/registration/onboarding"]
    end

    subgraph Checkout["Checkout"]
        plans["Choose Plan"]
        stripe["Stripe Checkout"]
        success["Payment Success"]
    end

    subgraph Welcome["Welcome"]
        welcome_page["Welcome Page\n/registration/welcome"]
        publish["First Publish"]
    end

    subgraph Dashboard["Dashboard"]
        main["Dashboard Home\n/dashboard"]
        customize["Customize Site"]
    end

    start --> oauth
    start --> email
    email --> verify
    oauth --> terms
    verify --> terms
    terms --> info
    info --> plans
    plans --> stripe
    stripe --> success
    success --> welcome_page
    welcome_page --> publish
    publish --> main
    main --> customize
```

### Dashboard Navigation

```mermaid
flowchart TD
    dashboard["Dashboard Home\n/dashboard"]

    subgraph Core["Core Features"]
        editor["Dealer Editor\n/dashboard/editor"]
        preview["Live Preview\n/dashboard/preview"]
        settings["Settings\n/dashboard/settings"]
    end

    subgraph CMS["CMS (Professional)"]
        cms_home["CMS Overview\n/dashboard/cms"]
        pages["Pages\n/dashboard/cms/pages"]
        navigation["Navigation\n/dashboard/cms/navigation"]
        links["Quick Links\n/dashboard/cms/links"]
    end

    subgraph Media["Media"]
        library["Media Library\n/dashboard/media"]
        slider["Slider Editor\n/dashboard/slider-editor"]
    end

    subgraph Analytics["Analytics"]
        stats["Statistics\n/dashboard/stats"]
        leads["Leads\n/dashboard/leads"]
    end

    subgraph Account["Account"]
        subscription["Subscription\n/dashboard/subscription"]
        domains["Domains\n/dashboard/settings/domains"]
    end

    dashboard --> editor
    dashboard --> preview
    dashboard --> settings
    dashboard --> cms_home
    cms_home --> pages
    cms_home --> navigation
    cms_home --> links
    dashboard --> library
    dashboard --> slider
    dashboard --> stats
    dashboard --> leads
    dashboard --> subscription
    settings --> domains
```

### Admin/Support Flow

```mermaid
flowchart TD
    login["Admin Login"]
    panel["Admin Panel\n/admin"]

    subgraph Compliance["Compliance Surface"]
        at_risk["At-Risk Panel\n(missing ZO/subdomain)"]
        inspect["Inspect → Dealer Search"]
    end

    subgraph Search["Dealer Search"]
        search["Search by Name/Email"]
        results["Search Results"]
        detail["Dealer Detail"]
    end

    subgraph Actions["Admin Actions"]
        impersonate["Start Impersonation"]
        status["Change Status"]
        notes["Add Notes"]
        revalidate["Trigger Revalidation\n(ZO-exempt)"]
        subdomain["Edit Subdomain"]
    end

    subgraph Support["Support Mode"]
        dealer_view["View as Dealer"]
        troubleshoot["Troubleshoot Issues"]
        end_session["End Session"]
    end

    subgraph Audit["Audit Trail"]
        log_action["Log Admin Action"]
        history["View Activity History"]
    end

    login --> panel
    panel --> at_risk
    at_risk --> inspect
    inspect --> search
    panel --> search
    search --> results
    results --> detail
    detail --> impersonate
    detail --> status
    detail --> notes
    detail --> revalidate
    detail --> subdomain
    impersonate --> dealer_view
    dealer_view --> troubleshoot
    troubleshoot --> end_session
    status --> log_action
    notes --> log_action
    log_action --> history
```

### Visitor Journey

```mermaid
flowchart TD
    land["Land on Dealer Site\n[subdomain].myamsoil.com"]

    subgraph Browse["Browse Content"]
        home["Home Page"]
        pages["Custom Pages"]
        blog["Blog Posts"]
        nav["Navigation"]
    end

    subgraph Engage["Engagement"]
        shop["Shop Now\n(AMSOIL Link)"]
        contact["Contact Form"]
        social["Social Links"]
    end

    subgraph Convert["Conversion"]
        lead["Lead Submission"]
        store["AMSOIL Store"]
    end

    subgraph Track["Analytics"]
        pageview["Page View Tracked"]
        click["Link Click Tracked"]
        lead_record["Lead Recorded"]
    end

    land --> home
    home --> nav
    nav --> pages
    nav --> blog
    pages --> shop
    pages --> contact
    pages --> social
    contact --> lead
    shop --> store
    social --> store
    home --> pageview
    pages --> pageview
    shop --> click
    lead --> lead_record
```

---

## Sitemap

### Route Structure

```mermaid
flowchart TD
    root["/"]

    subgraph Auth["Auth Routes"]
        auth["/auth"]
        signin["/auth/signin"]
        error["/auth/error"]
        forgot["/auth/forgot-password"]
        reset["/auth/reset-password"]
        verify_success["/auth/verification-success"]
        verify_error["/auth/verification-error"]
    end

    subgraph Registration["Registration Routes"]
        reg["/registration"]
        terms["/registration/terms"]
        onboarding["/registration/onboarding"]
        welcome["/registration/welcome"]
    end

    subgraph Dashboard["Dashboard Routes"]
        dash["/dashboard"]
        editor["/dashboard/editor"]
        preview["/dashboard/preview"]
        stats["/dashboard/stats"]
        leads["/dashboard/leads"]
        media["/dashboard/media"]
        slider["/dashboard/slider-editor"]
        subscription["/dashboard/subscription"]
        settings["/dashboard/settings"]
        domains["/dashboard/settings/domains"]
    end

    subgraph CMS["CMS Routes"]
        cms["/dashboard/cms"]
        pages["/dashboard/cms/pages"]
        pages_new["/dashboard/cms/pages/new"]
        pages_edit["/dashboard/cms/pages/[id]/edit"]
        navigation["/dashboard/cms/navigation"]
        links["/dashboard/cms/links"]
    end

    subgraph Admin["Admin Routes"]
        admin["/admin"]
        amsoil_images["/admin/amsoil-images"]
    end

    subgraph Public["Public Dealer Routes (internal rewrite targets)"]
        apex_stub["/home/[domainSlug] (apex stub, public /)"]
        directory_hub["/directory/[domainSlug] (public /dealers)"]
        directory_region["/directory/[domainSlug]/[region] (public /dealers/[region])"]
        dealer_home["/sites/[subdomain]/[domainSlug]"]
        dealer_page["/sites/[subdomain]/[domainSlug]/[...slug]"]
        dealer_og["/sites/[subdomain]/[domainSlug]/og"]
    end

    root --> auth
    auth --> signin
    auth --> error
    auth --> forgot
    auth --> reset
    auth --> verify_success
    auth --> verify_error

    root --> reg
    reg --> terms
    reg --> onboarding
    reg --> welcome

    root --> dash
    dash --> editor
    dash --> preview
    dash --> stats
    dash --> leads
    dash --> media
    dash --> slider
    dash --> subscription
    dash --> settings
    settings --> domains

    dash --> cms
    cms --> pages
    pages --> pages_new
    pages --> pages_edit
    cms --> navigation
    cms --> links

    root --> admin
    admin --> amsoil_images

    root --> apex_stub
    root --> directory_hub
    directory_hub --> directory_region
    root --> dealer_home
    dealer_home --> dealer_page
    dealer_home --> dealer_og
```

### API Routes

```mermaid
flowchart TD
    api["/api"]

    subgraph AuthAPI["Auth"]
        auth_nextauth["/api/auth/[...nextauth]"]
        register["/api/auth/register"]
        verify_email["/api/auth/verify-email"]
        resend["/api/auth/resend-verification"]
        forgot_pw["/api/auth/forgot-password"]
        reset_pw["/api/auth/reset-password"]
    end

    subgraph DealerAPI["Dealer"]
        dealer["/api/dealer"]
        dealer_update["/api/dealer/update"]
        dealer_settings["/api/dealer/settings"]
        dealer_leads["/api/dealer/leads"]
        custom_domain["/api/dealer/custom-domain"]
    end

    subgraph CMSAPI["CMS"]
        pages["/api/cms/pages"]
        pages_id["/api/cms/pages/[id]"]
        navigation["/api/cms/navigation"]
        navigation_id["/api/cms/navigation/[id]"]
        nav_seed["/api/cms/navigation/seed"]
        cms_links["/api/cms/links"]
        publish["/api/cms/publish"]
    end

    subgraph AdminAPI["Admin"]
        admin_dealers["/api/admin/dealers"]
        admin_dealer_id["/api/admin/dealers/[id]/*"]
        impersonate["/api/admin/impersonate/*"]
        admin_stats["/api/admin/stats"]
        amsoil_images["/api/admin/amsoil-images"]
    end

    subgraph PaymentAPI["Payments"]
        checkout["/api/checkout/*"]
        subscription["/api/subscription/*"]
        webhooks["/api/webhooks/stripe"]
    end

    subgraph MediaAPI["Media"]
        media["/api/media"]
        media_id["/api/media/[id]"]
        upload["/api/upload/*"]
    end

    subgraph StatsAPI["Stats"]
        events["/api/stats/events"]
        dashboard["/api/stats/dashboard"]
        cms_stats["/api/stats/cms"]
    end

    api --> AuthAPI
    api --> DealerAPI
    api --> CMSAPI
    api --> AdminAPI
    api --> PaymentAPI
    api --> MediaAPI
    api --> StatsAPI
```

---

## Subscription Tiers

### Feature Matrix

| Feature                     |  Starter   |      Growth       |     Enhanced      |     Professional     |
| --------------------------- | :--------: | :---------------: | :---------------: | :------------------: |
| **Pricing**                 |   $48/yr   | $25/mo or $300/yr | $50/mo or $600/yr | $200/mo or $2,400/yr |
| **Set-up & Hosting**        |    Yes     |        Yes        |        Yes        |         Yes          |
| **AMSOIL Content Updates**  |    Yes     |        Yes        |        Yes        |         Yes          |
| **Dealer Info Editor**      |    Yes     |        Yes        |        Yes        |         Yes          |
| **Auto Transfer Links**     |    Yes     |        Yes        |        Yes        |         Yes          |
| **Core SEO & AI**           |    Yes     |        Yes        |        Yes        |         Yes          |
| **Lead Generation Form**    |     -      |        Yes        |        Yes        |         Yes          |
| **Social Profile Linking**  |     -      |        Yes        |        Yes        |         Yes          |
| **Custom Domain Option**    |     -      |        Yes        |        Yes        |         Yes          |
| **Media Library**           | 100 images |    100 images     |    500 images     |     1000 images      |
| **Quick Links Editor**      |     -      |        Yes        |        Yes        |         Yes          |
| **Slider Editor**           |     -      |         -         |        Yes        |         Yes          |
| **Navigation Editor**       |     -      |         -         |        Yes        |         Yes          |
| **Featured Content Editor** |     -      |         -         |        Yes        |         Yes          |
| **Advanced SEO & AI**       |     -      |         -         |        Yes        |         Yes          |
| **Performance Dashboard**   |     -      |         -         |        Yes        |         Yes          |
| **Page Editor**             |     -      |         -         |     Edit only     |     Full access      |
| **Blog Posts**              |     -      |         -         |         -         |         Yes          |
| **Content Publishing**      |     -      |         -         |         -         |         Yes          |
| **Optimized Local Content** |     -      |         -         |         -         |         Yes          |

### Tier Progression

```mermaid
flowchart LR
    subgraph Starter["Starter\n$48/year"]
        s1["Basic Landing Page"]
        s2["Dealer Info"]
        s3["AMSOIL Links"]
    end

    subgraph Growth["Growth\n$25/month"]
        g1["+ Lead Form"]
        g2["+ Custom Domain"]
        g3["+ Social Links"]
        g4["+ Quick Links"]
        g5["+ Media Library (25)"]
    end

    subgraph Enhanced["Enhanced\n$50/month"]
        e1["+ Slider Editor"]
        e2["+ Navigation Editor"]
        e3["+ Page Editor"]
        e4["+ Analytics Dashboard"]
        e5["+ Media Library (50)"]
    end

    subgraph Professional["Professional\n$200/month"]
        p1["+ Full CMS"]
        p2["+ Blog Posts"]
        p3["+ Create New Pages"]
        p4["+ Local Content"]
        p5["+ Media Library (100)"]
    end

    Starter --> Growth
    Growth --> Enhanced
    Enhanced --> Professional
```

---

## Editor Access

Access to various editors is controlled by subscription tier. Below is a diagram showing which editors are available at each tier level.

### Editor Access by Tier

```mermaid
flowchart TD
    subgraph All["All Tiers"]
        dealer_editor["Dealer Info Editor\nContact, Address, Description"]
        preview["Live Preview"]
    end

    subgraph Growth["Growth+ Tiers"]
        lead_form["Lead Form Settings"]
        link_editor["Quick Links Editor\n(up to 10 links)"]
        media_lib["Media Library\n(tier-based limits)"]
        social["Social Links Editor"]
    end

    subgraph Enhanced["Enhanced+ Tiers"]
        slider_editor["Slider Editor\n(Hero carousel)"]
        nav_editor["Navigation Editor\n(Menu customization)"]
        page_editor["Page Content Editor\n(Edit existing pages)"]
        analytics["Analytics Dashboard"]
    end

    subgraph Professional["Professional Only"]
        full_cms["Full CMS Access"]
        create_pages["Create New Pages"]
        blog_editor["Blog Post Editor"]
        content_pub["Content Publishing"]
    end

    All --> Growth
    Growth --> Enhanced
    Enhanced --> Professional
```

### Access Control Implementation

The tier-based access control is implemented in `lib/cms/types.ts`:

```
Editor Type          | Access Tiers          | Code Reference
---------------------|----------------------|-------------------------
CMS (Full)           | professional         | CMS_TIERS
Navigation Editor    | enhanced+            | NAV_EDITOR_TIERS
Slider Editor        | enhanced+            | SLIDER_EDITOR_TIERS
Page Edit            | professional         | PAGE_EDIT_TIERS
Page Create          | professional         | PAGE_CREATE_TIERS
Page View            | all tiers            | PAGE_VIEW_TIERS
Lead Form            | growth+              | LEAD_FORM_TIERS
Link Editor          | growth+              | LINK_EDITOR_TIERS
Custom Domain        | growth+              | CUSTOM_DOMAIN_TIERS
Media Library        | starter+             | MEDIA_LIBRARY_TIERS
```

### Media Library Limits

| Tier         | Image Limit |
| ------------ | ----------- |
| Starter      | 100 images  |
| Growth       | 100 images  |
| Enhanced     | 500 images  |
| Professional | 1000 images |

---

## Related Documentation

- [Dealer Dashboard](DEALER_DASHBOARD.md) - Dashboard features and navigation
- [Dealer Editors](DEALER_EDITORS.md) - Editor components and access control
- [Registration Architecture](REGISTRATION_ARCHITECTURE.md) - Authentication and onboarding flow
- [Stats API](STATS_API.md) - Analytics and tracking implementation
- [Stripe Customer Portal](STRIPE_CUSTOMER_PORTAL.md) - Billing and subscription management
- [Admin Status Management](ADMIN_STATUS_MANAGEMENT.md) - Admin panel features

---

_Last Updated: 2026-06-15_