# 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