# AMSOIL DLP Documentation

> **[Back to Project README](../README.md)**

This is the central documentation index for the AMSOIL Dealer Landing Pages platform. Use the sections below to find documentation for specific topics.

---

## Documentation by Topic

| Section                               | Description                                           | Start Here                                     |
| ------------------------------------- | ----------------------------------------------------- | ---------------------------------------------- |
| [Authentication](./auth/)             | OAuth providers, JWT tokens, registration flow        | [auth/README.md](./auth/README.md)             |
| [Subdomains & Domains](./subdomains/) | Subdomain routing, custom domains, Cloudflare DNS     | [subdomains/README.md](./subdomains/README.md) |
| [Email](./email/)                     | Email service providers, normalization, notifications | [email/README.md](./email/README.md)           |
| [Admin](./admin/)                     | Admin dashboard, dealer management, status changes    | [admin/README.md](./admin/README.md)           |
| [Analytics](./analytics/)             | Stats API, page views, link tracking                  | [analytics/README.md](./analytics/README.md)   |
| [Database](./db/)                     | Prisma schema, JSON fields, data models               | [db/README.md](./db/README.md)                 |
| [Billing](./billing/)                 | Stripe subscriptions, webhooks, customer portal       | [billing/README.md](./billing/README.md)       |
| [Editors](./editors/)                 | CMS, Puck editor, dashboard features                  | [editors/README.md](./editors/README.md)       |

---

## Quick Start Guides

**New developer? Start here:** **[DEVELOPER_OVERVIEW.md](./DEVELOPER_OVERVIEW.md)** - the curated developer onboarding runbook (setup, system map, conventions, and pointers into every deep-dive doc). The developer-facing sibling of [SUPPORT_OVERVIEW.md](./SUPPORT_OVERVIEW.md).

**More starting points:**

1. **[STYLING_QUICK_REFERENCE.md](./STYLING_QUICK_REFERENCE.md)** - 1-page cheat sheet of common styling patterns
2. **[ARCHITECTURE.md](./ARCHITECTURE.md)** - System architecture with Mermaid diagrams
3. **[LOCAL_DEVELOPMENT.md](./LOCAL_DEVELOPMENT.md)** - Local dev setup with Stripe webhooks

**Setting up a feature?**

- Authentication: Start with [auth/README.md](./auth/README.md)
- Billing integration: Start with [billing/README.md](./billing/README.md)
- CMS/Editor work: Start with [editors/README.md](./editors/README.md)

---

## Building Features

Step-by-step walkthroughs for common contributor tasks. Each covers a single end-to-end change from source to test.

| Walkthrough                                                  | Use when                                                        |
| ------------------------------------------------------------ | --------------------------------------------------------------- |
| [Add a Puck component](./editors/ADDING_A_PUCK_COMPONENT.md) | Adding a new draggable block to the CMS page editor             |
| [Add an email template](./email/ADDING_AN_EMAIL_TEMPLATE.md) | Adding or modifying a transactional email                       |
| [Add a page type](./ADDING_A_PAGE_TYPE.md)                   | Extending the CMS with a new page kind beyond `page` and `blog` |
| [Add an API route](./CONTRIBUTING.md#common-recipes)         | Wiring a new authenticated or admin API endpoint                |

---

## System Overview

```mermaid
flowchart TB
    subgraph Frontend
        LANDING[Marketing Landing]
        DASHBOARD[Dealer Dashboard]
        ADMIN[Admin Panel]
        PUBLIC[Public Dealer Sites]
    end

    subgraph Backend
        AUTH[NextAuth.js]
        API[API Routes]
        STRIPE[Stripe Webhooks]
        EMAIL[Email Service]
    end

    subgraph Infrastructure
        CF[Cloudflare DNS]
        R2[Cloudflare R2]
        DB[(PostgreSQL)]
    end

    LANDING --> AUTH
    DASHBOARD --> API
    ADMIN --> API
    PUBLIC --> API
    AUTH --> DB
    API --> DB
    STRIPE --> DB
    API --> EMAIL
    API --> CF
    API --> R2
```

---

## All Documentation Files

### Architecture & Overview

| File                                                       | Description                               |
| ---------------------------------------------------------- | ----------------------------------------- |
| [DEVELOPER_OVERVIEW.md](./DEVELOPER_OVERVIEW.md)           | Developer onboarding runbook (start here) |
| [ARCHITECTURE.md](./ARCHITECTURE.md)                       | System architecture with Mermaid diagrams |
| [STYLING_QUICK_REFERENCE.md](./STYLING_QUICK_REFERENCE.md) | One-page styling cheat sheet              |

### Authentication & Registration

| File                                                           | Description                                   |
| -------------------------------------------------------------- | --------------------------------------------- |
| [APPLE_OAUTH_MAINTENANCE.md](./APPLE_OAUTH_MAINTENANCE.md)     | Apple OAuth JWT key rotation                  |
| [AUTH_EMAIL_NORMALIZATION.md](./AUTH_EMAIL_NORMALIZATION.md)   | Email normalization + OAuth identity recovery |
| [REGISTRATION_SUMMARY.md](./REGISTRATION_SUMMARY.md)           | Registration flow overview                    |
| [REGISTRATION_ARCHITECTURE.md](./REGISTRATION_ARCHITECTURE.md) | Registration visual diagrams                  |
| [REGISTRATION_FLOW_MAP.md](./REGISTRATION_FLOW_MAP.md)         | Complete registration reference               |

### Domain Management

| File                                                                         | Description                      |
| ---------------------------------------------------------------------------- | -------------------------------- |
| [CLOUDFLARE_SETUP.md](./CLOUDFLARE_SETUP.md)                                 | Cloudflare DNS setup             |
| [CLOUDFLARE_PRODUCTION_DEPLOYMENT.md](./CLOUDFLARE_PRODUCTION_DEPLOYMENT.md) | Production Cloudflare deployment |

### Email

| File                                               | Description                  |
| -------------------------------------------------- | ---------------------------- |
| [EMAIL_SERVICE.md](./EMAIL_SERVICE.md)             | Email provider configuration |
| [EMAIL_NORMALIZATION.md](./EMAIL_NORMALIZATION.md) | Email handling details       |

### Administration

| File                                                       | Description                                               |
| ---------------------------------------------------------- | --------------------------------------------------------- |
| [ADMIN_STATUS_MANAGEMENT.md](./ADMIN_STATUS_MANAGEMENT.md) | Admin status change workflows                             |
| [ZO_NUMBER_COMPLIANCE.md](./ZO_NUMBER_COMPLIANCE.md)       | ZO-number regime: at-risk report, publish gate, intake    |
| [ADMIN_IMPERSONATION.md](./ADMIN_IMPERSONATION.md)         | Admin-as-dealer impersonation: rules, expiry, audit       |
| [TIER_TRANSITIONS.md](./TIER_TRANSITIONS.md)               | Dealer status + tier state machines and cascading effects |
| [CRON_JOBS.md](./CRON_JOBS.md)                             | Scheduled job inventory, runbook, failure alerting        |
| [OPERATIONS_CHECKLIST.md](./OPERATIONS_CHECKLIST.md)       | Ops maintenance tasks                                     |

### Analytics

| File                                         | Description                                   |
| -------------------------------------------- | --------------------------------------------- |
| [analytics/README.md](./analytics/README.md) | Analytics overview + event ingestion pipeline |
| [STATS_API.md](./STATS_API.md)               | Analytics API endpoints                       |

### Database

| File                                               | Description               |
| -------------------------------------------------- | ------------------------- |
| [PRISMA_JSON_SCHEMAS.md](./PRISMA_JSON_SCHEMAS.md) | Prisma JSON field schemas |

### Billing & Payments

| File                                                     | Description                                           |
| -------------------------------------------------------- | ----------------------------------------------------- |
| [STRIPE_CUSTOMER_PORTAL.md](./STRIPE_CUSTOMER_PORTAL.md) | Stripe integration                                    |
| [LOCAL_DEVELOPMENT.md](./LOCAL_DEVELOPMENT.md)           | Local Stripe webhook setup                            |
| [PLAN_FEATURES_MATRIX.md](./PLAN_FEATURES_MATRIX.md)     | Tier → feature mapping, Stripe price IDs, gating code |

### CMS & Editors

| File                                           | Description                                          |
| ---------------------------------------------- | ---------------------------------------------------- |
| [DEALER_DASHBOARD.md](./DEALER_DASHBOARD.md)   | Dashboard features (non-editor)                      |
| [DEALER_EDITORS.md](./DEALER_EDITORS.md)       | CMS editor interfaces                                |
| [LEAD_FORMS.md](./LEAD_FORMS.md)               | Dealer contact/lead forms: config, routing, pipeline |
| [MEDIA_LIBRARY.md](./MEDIA_LIBRARY.md)         | Uploads (chunked + direct), PDF serving, tier limits |
| [STYLING_GUIDE.md](./STYLING_GUIDE.md)         | Font and breakpoints                                 |
| [CMS_DESIGN_SYSTEM.md](./CMS_DESIGN_SYSTEM.md) | CMS/dashboard design system                          |

### Infrastructure & Security

| File                                                       | Description                                |
| ---------------------------------------------------------- | ------------------------------------------ |
| [SPAM_PROTECTION.md](./SPAM_PROTECTION.md)                 | Defense-in-depth on the contact endpoint   |
| [RATE_LIMITING.md](./RATE_LIMITING.md)                     | Cloudflare rate limiting monitoring        |
| [PRODUCTION_SERVER_SETUP.md](./PRODUCTION_SERVER_SETUP.md) | Server deployment                          |
| [TURNSTILE_SETUP.md](./TURNSTILE_SETUP.md)                 | Turnstile bot protection in forms          |
| [TURNSTILE_POOL.md](./TURNSTILE_POOL.md)                   | Turnstile widget pool management           |
| [OG_IMAGE_CACHING.md](./OG_IMAGE_CACHING.md)               | OG image generation and atomic cache layer |

### Testing & Integrations

| File                                                               | Description                                      |
| ------------------------------------------------------------------ | ------------------------------------------------ |
| [PROPERTY_BASED_TESTING.md](./PROPERTY_BASED_TESTING.md)           | When and how to use `fast-check` PBT             |
| [CLICKUP_SUPPORT_INTEGRATION.md](./CLICKUP_SUPPORT_INTEGRATION.md) | Support form → ClickUp task endpoint             |
| [MCP_SERVER.md](./MCP_SERVER.md)                                   | Dealer-lookup MCP server: deploy, security, ops  |
| [MCP_DEVELOPMENT.md](./MCP_DEVELOPMENT.md)                         | MCP server code layout and how to add a tool     |
| [MCP_CONFIGURATION.md](./MCP_CONFIGURATION.md)                     | Repo-level `.mcp.json` and Claude Code MCP setup |

### Meta

| File                                               | Description                  |
| -------------------------------------------------- | ---------------------------- |
| [DOCUMENTATION_AUDIT.md](./DOCUMENTATION_AUDIT.md) | Documentation accuracy audit |

---

## Cross-Reference Map

```mermaid
flowchart LR
    subgraph AUTH[Authentication]
        A1[APPLE_OAUTH_MAINTENANCE]
        A2[REGISTRATION_*]
    end

    subgraph EMAIL[Email]
        E1[EMAIL_SERVICE]
        E2[EMAIL_NORMALIZATION]
    end

    subgraph BILLING[Billing]
        B1[STRIPE_CUSTOMER_PORTAL]
        B2[LOCAL_DEVELOPMENT]
    end

    subgraph ADMIN[Admin]
        AD1[ADMIN_STATUS_MANAGEMENT]
        AD2[OPERATIONS_CHECKLIST]
    end

    AUTH <--> EMAIL
    AUTH <--> BILLING
    BILLING <--> ADMIN
    EMAIL <--> ADMIN
```

**Key relationships:**

- **Auth ↔ Email**: Registration sends welcome emails
- **Auth ↔ Billing**: OAuth triggers subscription creation
- **Billing ↔ Admin**: Admins can manage subscriptions
- **Email ↔ Admin**: Admins trigger notification emails

---

## Documentation Maintenance

When modifying documentation:

1. Update the relevant section README if adding new files
2. Update this overview if adding new sections
3. Check cross-links remain valid
4. Run documentation audit periodically (see [DOCUMENTATION_AUDIT.md](./DOCUMENTATION_AUDIT.md))

## Pre-signup FAQ (for support)

Brand-new or prospective dealers contact support before/during signup. Stock answers:

**"How long does setup take?"**
Most dealers complete it in about 5 minutes. The site is live within minutes after registration.

**"Do you build the site for me?"**
Yes - the system creates the site automatically using AMSOIL-provided base content (products, categories, basic pages). Dealers customize the site themselves via the dashboard editors.

**"How does it work? What do I get?"**
A subscription gives the dealer a hosted website at `<their-subdomain>.<suffix>` (one of four suffixes - see [subdomains/README.md](./subdomains/README.md)). The site has product information, contact details, and AMSOIL branding. Higher tiers add features like custom domain, slider editing, social integration, and full CMS - see [PLAN_FEATURES_MATRIX.md](./PLAN_FEATURES_MATRIX.md).

**"Where do I sign up?"**
`amsoil.aimclear.com` - pick a tier, enter business info, complete checkout.

**"I inherited an account from another dealer - what do I do?"**
This is sensitive territory. Get the existing account's email and dealer number, then escalate to a real person - you'll need to verify ownership and likely transfer the subscription.