@modyo/mcp 0.1.0

package/docs/channels/site-architecture.md

@@ -0,0 +1,246 @@
+# Modyo Site Architecture Guide
+
+**Version**: 1.0.0
+**Last Updated**: 2025-01-09
+**Module**: Channels
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Core Architecture Diagram](#core-architecture-diagram)
+3. [Component Relationships](#component-relationships)
+
+**Related Documents:**
+- [Component Deep Dive](./site-components.md) - Detailed reference for each component type (Sites, Pages, Templates, Widgets, Navigation, Settings)
+- [Content Flow, Patterns & Best Practices](./site-patterns.md) - Rendering flow, architecture patterns, best practices, and troubleshooting
+
+---
+
+## Overview
+
+A Modyo site is a complete web application built on a **component-based architecture** designed for enterprise digital experiences. At its core, Modyo uses a **separation of concerns** approach where:
+
+- **Sites** are containers with domain configuration
+- **Pages** define routes and URL structure
+- **Templates** provide reusable code organization
+- **Widgets** are micro frontend components
+- **Navigation** structures site hierarchy
+- **Settings** control behavior and configuration
+
+### Key Architectural Principles
+
+1. **Component Reusability**: Snippets and widgets enable DRY (Don't Repeat Yourself) principles
+2. **Separation of Concerns**: Content, presentation, and logic are isolated
+3. **Micro Frontend Architecture**: Widgets function as independent, deployable units
+4. **Version Control**: All components support versioning and rollback
+5. **Team Collaboration**: Built-in workflows for review and approval
+
+---
+
+## Core Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                          MODYO SITE                              │
+│  (Domain: www.mycompany.com)                                    │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────┐   │
+│  │                    SITE SETTINGS                        │   │
+│  │  - Language, Timezone, Theme                           │   │
+│  │  - PWA Configuration                                    │   │
+│  │  - Security Headers                                     │   │
+│  │  - Custom Variables                                     │   │
+│  └────────────────────────────────────────────────────────┘   │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────┐   │
+│  │                     NAVIGATION                          │   │
+│  │  Main Menu (3 levels depth)                           │   │
+│  │  ├─ Home                                               │   │
+│  │  ├─ Products                                           │   │
+│  │  │  ├─ Category A                                      │   │
+│  │  │  └─ Category B                                      │   │
+│  │  └─ Contact                                            │   │
+│  └────────────────────────────────────────────────────────┘   │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────┐   │
+│  │                      TEMPLATES                          │   │
+│  │  ┌──────────────────────────────────────────────────┐ │   │
+│  │  │         LAYOUTS (Page Structure)                 │ │   │
+│  │  │  - Base Layout (site-wide structure)            │ │   │
+│  │  │  - Home Layout (homepage template)              │ │   │
+│  │  │  - Error Layout (404, 500, etc.)                │ │   │
+│  │  └──────────────────────────────────────────────────┘ │   │
+│  │                                                         │   │
+│  │  ┌──────────────────────────────────────────────────┐ │   │
+│  │  │      SNIPPETS (Reusable Code Blocks)            │ │   │
+│  │  │  {% snippet 'site-header' %}                    │ │   │
+│  │  │  {% snippet 'site-footer' %}                    │ │   │
+│  │  │  {% snippet 'analytics' %}                      │ │   │
+│  │  └──────────────────────────────────────────────────┘ │   │
+│  │                                                         │   │
+│  │  ┌──────────────────────────────────────────────────┐ │   │
+│  │  │    CUSTOM SNIPPETS (User-Defined)               │ │   │
+│  │  │  {% snippet 'product-card' %}                   │ │   │
+│  │  │  {% snippet 'testimonial-section' %}            │ │   │
+│  │  └──────────────────────────────────────────────────┘ │   │
+│  │                                                         │   │
+│  │  ┌──────────────────────────────────────────────────┐ │   │
+│  │  │         CSS & JS TEMPLATES                       │ │   │
+│  │  │  - Global Styles                                 │ │   │
+│  │  │  - Global Scripts                                │ │   │
+│  │  │  - Library Imports                               │ │   │
+│  │  └──────────────────────────────────────────────────┘ │   │
+│  └────────────────────────────────────────────────────────┘   │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────┐   │
+│  │                        PAGES                            │   │
+│  │  (Routes/URLs)                                         │   │
+│  │                                                         │   │
+│  │  ┌──────────────────────────────────────────────────┐ │   │
+│  │  │  PAGE: /  (Home)                                 │ │   │
+│  │  │  Type: Widget Page                               │ │   │
+│  │  │  Layout: Home Layout                             │ │   │
+│  │  │  ┌────────────────────────────────────────────┐ │ │   │
+│  │  │  │  WIDGET: Hero Banner                       │ │ │   │
+│  │  │  │  - HTML/CSS/JS                             │ │ │   │
+│  │  │  │  - Variables: title, image, CTA            │ │ │   │
+│  │  │  └────────────────────────────────────────────┘ │ │   │
+│  │  │  ┌────────────────────────────────────────────┐ │ │   │
+│  │  │  │  WIDGET: Featured Products                 │ │ │   │
+│  │  │  │  - HTML/CSS/JS                             │ │ │   │
+│  │  │  │  - Variables: category, limit              │ │ │   │
+│  │  │  └────────────────────────────────────────────┘ │ │   │
+│  │  └──────────────────────────────────────────────────┘ │   │
+│  │                                                         │   │
+│  │  ┌──────────────────────────────────────────────────┐ │   │
+│  │  │  PAGE: /products  (Product List)                │ │   │
+│  │  │  Type: Content Page                             │ │   │
+│  │  │  Layout: Base Layout                            │ │   │
+│  │  │  Linked to Content Type: "Products"            │ │   │
+│  │  └──────────────────────────────────────────────────┘ │   │
+│  │                                                         │   │
+│  │  ┌──────────────────────────────────────────────────┐ │   │
+│  │  │  PAGE: /products/:slug  (Product Detail)        │ │   │
+│  │  │  Type: Content Page (Dynamic)                   │ │   │
+│  │  │  Layout: Base Layout                            │ │   │
+│  │  │  has_router: true                               │ │   │
+│  │  │  Displays: Individual product entries           │ │   │
+│  │  └──────────────────────────────────────────────────┘ │   │
+│  │                                                         │   │
+│  │  ┌──────────────────────────────────────────────────┐ │   │
+│  │  │  PAGE: /contact  (Contact)                      │ │   │
+│  │  │  Type: Widget Page                              │ │   │
+│  │  │  Layout: Base Layout                            │ │   │
+│  │  │  ┌────────────────────────────────────────────┐ │ │   │
+│  │  │  │  WIDGET: Contact Form                      │ │ │   │
+│  │  │  └────────────────────────────────────────────┘ │ │   │
+│  │  └──────────────────────────────────────────────────┘ │   │
+│  └────────────────────────────────────────────────────────┘   │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Component Relationships
+
+### How Components Work Together
+
+```
+1. SITE CREATED
+   └─> Site Settings Configured
+       └─> Domain: www.example.com
+       └─> Theme: 208
+       └─> Language: en
+
+2. TEMPLATES CREATED
+   ├─> Base Layout
+   │   └─> Contains: {% snippet 'site-header' %}, {% snippet 'site-footer' %}
+   │
+   ├─> Snippets
+   │   ├─> site-header (with navigation)
+   │   ├─> site-footer
+   │   └─> analytics
+   │
+   └─> CSS & JS Templates
+       ├─> Global styles
+       └─> Global scripts
+
+3. NAVIGATION CREATED
+   └─> Main Menu
+       ├─> Home (/)
+       ├─> Products (/products)
+       │   ├─> Electronics (/products/electronics)
+       │   └─> Clothing (/products/clothing)
+       └─> Contact (/contact)
+
+4. WIDGETS CREATED
+   ├─> Hero Banner Widget
+   ├─> Product Showcase Widget
+   └─> Contact Form Widget
+
+5. PAGES CREATED
+   ├─> Home Page (/)
+   │   ├─> Layout: Home Layout
+   │   ├─> Type: Widget Page (page_type: "home")
+   │   ├─> Grid: full_three_cols_grid
+   │   ├─> ✅ Accepts: Custom widgets
+   │   └─> Widgets: [Hero Banner, Product Showcase]
+   │
+   ├─> Product List Page (/products)
+   │   ├─> Layout: Base Layout
+   │   ├─> Type: Content Page (page_type: "content")
+   │   ├─> Content Type ID: 5756 (Products from Banking Space)
+   │   ├─> ❌ No custom widgets
+   │   ├─> ✅ Automatic: {{ entries }} drop (list view)
+   │   └─> Uses: Liquid template for index view
+   │
+   ├─> Product Detail Page (/products/:slug)
+   │   ├─> Layout: Base Layout
+   │   ├─> Type: Content Page (page_type: "entry")
+   │   ├─> has_router: true (dynamic routing)
+   │   ├─> Content Type ID: 5756 (Products)
+   │   ├─> ❌ No custom widgets
+   │   ├─> ✅ Automatic: {{ entry }} drop (detail view)
+   │   └─> Uses: Liquid template for show view
+   │
+   ├─> Contact Page (/contact)
+   │   ├─> Layout: Base Layout
+   │   ├─> Type: Widget Page (page_type: "default")
+   │   ├─> Grid: full_grid
+   │   ├─> ✅ Accepts: Custom widgets
+   │   └─> Widgets: [Contact Form Widget]
+   │
+   └─> Loan Application (/apply)
+       ├─> Layout: Base Layout
+       ├─> Type: Origination Page (page_type: "origination")
+       ├─> ❌ No custom widgets
+       ├─> ✅ Multi-step form workflow
+       └─> Uses: Task-based navigation
+
+6. RENDERING FLOW
+   User visits: www.example.com/products/laptop-x
+
+   ├─> Site resolves domain
+   ├─> Matches route: /products/:slug
+   ├─> Loads Page: "Product Detail"
+   ├─> Applies Layout: Base Layout
+   │   ├─> Renders {% snippet 'site-header' %}
+   │   │   └─> Renders {% menu 'main-navigation' %}
+   │   ├─> Renders content_for_layout (product data)
+   │   └─> Renders {% snippet 'site-footer' %}
+   ├─> Loads CSS Templates
+   ├─> Loads JS Templates
+   └─> Returns HTML to browser
+```
+
+---
+
+**Document Version**: 2.0.0
+**Last Updated**: 2025-01-09
+**Maintained By**: Modyo MCP Development Team
+
+**Changelog**:
+- v2.0.0 (2025-01-09): Updated with comprehensive 3-page-type architecture (Widget, Content, Origination)
+- v1.0.0: Initial version