@silexlabs/silex-dashboard 1.5.0-canary.0 → 1.5.0-canary.2

package/DASHBOARD-ARCHITECTURE.md

@@ -0,0 +1,1410 @@
+# Silex Dashboard Architecture - Complete Analysis
+
+> **Last Updated**: December 27, 2025
+> **Silex Version**: 3.6.0-canary.1
+> **Purpose**: Reference documentation for understanding and extending the dashboard
+
+---
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Running Services](#running-services)
+- [Project Structure](#project-structure)
+- [Complete Data Flow](#complete-data-flow)
+- [Key Integration Points](#key-integration-points)
+- [Template System](#template-system)
+- [Special Techniques](#special-techniques)
+- [Implementation Guide](#implementation-guide)
+- [Template/Fork Feature Design](#templatefork-feature-design)
+
+---
+
+## Quick Start
+
+### Starting the Dashboard
+
+```bash
+cd /home/lexoyo/_/Silex/packages/silex-dashboard
+
+# Start all services (TinaCMS, Silex, 11ty)
+npm start
+
+# OR start individually:
+npm run tina:dev    # TinaCMS on :4001
+npm run silex:dev   # Silex on :6805
+npm run 11ty:dev    # 11ty on :8080
+```
+
+### Accessing Services
+
+- **Silex Editor**: http://localhost:6805/?id=dashboard
+- **TinaCMS Admin**: http://localhost:4001/admin
+- **11ty Preview**: http://localhost:8080/en/
+- **GraphQL Playground**: http://localhost:4001/graphql
+
+---
+
+## Running Services
+
+### Service Architecture
+
+```
+┌─────────────────┐
+│   TinaCMS       │  Port 4001
+│   GraphQL API   │  (Content Management)
+└────────┬────────┘
+         │
+         ├─────────────────────────────────┐
+         │                                 │
+         ▼                                 ▼
+┌─────────────────┐              ┌─────────────────┐
+│   11ty          │  Port 8080   │   Silex         │  Port 6805
+│   Static Gen    │  (Preview)   │   Editor        │  (Design)
+└─────────────────┘              └─────────────────┘
+         │                                 │
+         │                                 │
+         ▼                                 ▼
+┌─────────────────────────────────────────────────┐
+│              _site/ (Static Output)              │
+│  - /en/index.html    - /fr/index.html           │
+│  - /en/connectors/   - /fr/connectors/          │
+└─────────────────────────────────────────────────┘
+```
+
+### Service Responsibilities
+
+| Service | Port | Purpose | Technologies |
+|---------|------|---------|-------------|
+| **TinaCMS** | 4001 | Content management, GraphQL API | TinaCMS, GraphQL |
+| **Silex** | 6805 | Visual editor, design, page settings | GrapesJS, Express |
+| **11ty** | 8080 | Static site generation, templating | Eleventy, Liquid |
+
+---
+
+## Project Structure
+
+### File Organization
+
+```
+silex-dashboard/
+├── silex/                          # Silex editor data
+│   ├── websites/
+│   │   └── dashboard/
+│   │       ├── website.json        # ★ Pages, components, styles (2 pages, 133 styles)
+│   │       └── meta.json           # Site metadata {"name":"Dashboard"}
+│   ├── server-config.js            # Express middleware (locale, routing)
+│   └── client-config.js            # CMS datasource config
+│
+├── templates/                      # 11ty input (Silex output)
+│   ├── websites.html               # Base template (Silex-generated)
+│   ├── websites-en.html            # ★ 11ty template with frontmatter (EN)
+│   ├── websites-fr.html            # ★ 11ty template with frontmatter (FR)
+│   ├── connectors.html             # Base template
+│   ├── connectors-en.html          # ★ 11ty template (EN)
+│   ├── connectors-fr.html          # ★ 11ty template (FR)
+│   ├── css/                        # Silex-generated CSS
+│   └── assets/                     # Images, fonts, favicon
+│
+├── 11ty/                           # 11ty configuration
+│   ├── eleventy.config.mjs         # Main config (i18n, passthroughs)
+│   ├── _data/
+│   │   ├── api-translations.json   # Error messages, UI strings
+│   │   └── site.js                 # Global site data
+│   └── _includes/
+│       └── alternate.liquid        # Hreflang tags for SEO
+│
+├── collections/                    # ★ TinaCMS content
+│   ├── home/
+│   │   ├── en.md                   # English UI labels (title, buttons, etc.)
+│   │   └── fr.md                   # French UI labels
+│   ├── connectors/
+│   │   ├── en.md                   # Connectors page labels
+│   │   └── fr.md
+│   ├── languages/
+│   │   ├── en.json                 # Language config {"code":"en","label":"English"}
+│   │   └── fr.json
+│   └── settings/
+│       ├── en.json                 # Nav, footer links
+│       └── fr.json
+│
+├── tina/                           # TinaCMS config
+│   ├── config.ts                   # ★ Schema definition (4 collections)
+│   └── __generated__/              # Auto-generated GraphQL schema
+│
+└── _site/                          # 11ty output (gitignored)
+    ├── en/
+    │   ├── index.html              # Final websites page (EN)
+    │   └── connectors/
+    │       └── index.html          # Final connectors page (EN)
+    ├── fr/
+    │   ├── index.html              # Final websites page (FR)
+    │   └── connectors/
+    │       └── index.html          # Final connectors page (FR)
+    ├── css/                        # Copied CSS
+    ├── js/                         # Vue.js runtime
+    └── assets/                     # Copied assets
+```
+
+### Page Structure
+
+**2 Pages in Silex** (defined in `website.json`):
+
+| Page ID | Name | Purpose | Permalink |
+|---------|------|---------|-----------|
+| `mk3OKgfr4A9V7Dww` | Websites | Main dashboard (list user's websites) | `/{{lang}}/` |
+| `BOCWuSXKn6FRo8x5L` | Connectors | Login/authentication page | `/{{lang}}/connectors/` |
+
+**Page Multiplication for i18n**:
+- Each Silex page → 2 language versions (EN, FR)
+- Total: **4 final HTML files**
+
+---
+
+## Complete Data Flow
+
+### 1. Design Phase (Silex)
+
+```
+Designer opens: http://localhost:6805/?id=dashboard
+    ↓
+Designs pages visually:
+    - Drag & drop components
+    - Apply CSS styles
+    - Add Vue.js directives (v-if, v-for, v-on:click)
+    ↓
+Configures page settings:
+    - General: Page name = "Websites"
+    - CMS: Permalink = /{{lang}}/
+    - CMS: Language list = "en,fr"
+    - Code: <head> content = Vue.js app
+    - SEO: Title expression (GraphQL query)
+    ↓
+Clicks "Publish"
+    ↓
+Silex generates templates/websites.html
+    ↓
+Saves to silex/websites/dashboard/website.json
+```
+
+**website.json structure**:
+```json
+{
+  "pages": [
+    {
+      "id": "mk3OKgfr4A9V7Dww",
+      "name": "Websites",
+      "settings": {
+        "silexLanguagesList": "en,fr",
+        "eleventyPermalink": "[{...}]",
+        "head": "/* Vue.js code */"
+      }
+    }
+  ],
+  "styles": [ /* 133 CSS rules */ ],
+  "components": [],
+  "assets": [ /* images, fonts */ ]
+}
+```
+
+### 2. Content Phase (TinaCMS)
+
+```
+Content editor opens: http://localhost:4001/admin
+    ↓
+Edits collections:
+    - home/en.md: title, subtitle, button labels
+    - home/fr.md: titre, sous-titre, étiquettes
+    - settings/en.json: navigation, footer links
+    ↓
+Saves changes
+    ↓
+TinaCMS writes to collections/ directory
+    ↓
+TinaCMS GraphQL API auto-updates
+```
+
+**TinaCMS Schema** (`tina/config.ts`):
+```typescript
+{
+  collections: [
+    {
+      name: "home",
+      path: "collections/home",
+      fields: [
+        { label: 'Title', name: 'title', type: 'string' },
+        { label: 'Subtitle', name: 'subtitle', type: 'string' },
+        { label: 'Add Button', name: 'add_button', type: 'string' },
+        // ... 20+ fields
+      ]
+    },
+    // ... 3 more collections (connectors, languages, settings)
+  ]
+}
+```
+
+### 3. Build Phase (11ty)
+
+```
+11ty watches templates/ directory
+    ↓
+Detects websites.html changed
+    ↓
+For each language (en, fr):
+    ↓
+    1. Creates template file: websites-en.html
+       - Adds frontmatter (permalink, lang, collection)
+       - Keeps all HTML/CSS/JS from Silex
+    ↓
+    2. Executes websites-en.11tydata.mjs:
+       - Fetches TinaCMS GraphQL (homeConnection, settingsConnection)
+       - Returns { tina: { ... } }
+    ↓
+    3. Processes Liquid tags in HTML:
+       {% assign var = tina.homeConnection.edges
+          | where: "node.lang", "en"
+          | first %}
+       {{ var.node.title }}
+    ↓
+    4. Outputs _site/en/index.html
+    ↓
+Done! Static HTML ready
+```
+
+**11tydata.mjs example**:
+```javascript
+export default async function (configData) {
+  const response = await fetch('http://localhost:4001/graphql', {
+    method: 'POST',
+    body: JSON.stringify({
+      query: `{
+        homeConnection {
+          edges {
+            node {
+              title
+              subtitle
+              add_button
+              lang
+            }
+          }
+        }
+        settingsConnection {
+          edges {
+            node {
+              nav { label, url, target }
+              lang
+            }
+          }
+        }
+      }`
+    })
+  })
+
+  const json = await response.json()
+  return {
+    tina: json.data,
+    lang: 'en'
+  }
+}
+```
+
+### 4. Runtime Phase (Vue.js)
+
+```
+User visits: http://localhost:8080/en/
+    ↓
+Browser loads HTML with embedded Vue.js in <head>
+    ↓
+Vue app initializes on window.load:
+    ↓
+    1. const { api } = silex
+    2. const user = await api.getUser()
+    3. if (user) {
+         this.websites = await api.websiteList()
+       } else {
+         redirect to /en/connectors/
+       }
+    ↓
+Vue reactivity kicks in:
+    - v-if="!empty" shows/hides sections
+    - v-for="website in websites" renders list
+    - v-on:click="createWebsite" handles clicks
+    ↓
+User sees fully interactive dashboard!
+```
+
+**Vue.js app structure** (in page settings `head`):
+```javascript
+const App = {
+  data() {
+    return {
+      websites: [],           // From Silex API
+      user: null,             // From Silex API
+      loading: true,          // UI state
+      error: null,            // Error messages
+      showCreationForm: false // UI state
+    }
+  },
+
+  async mounted() {
+    const user = await getUser({ type: ConnectorType.STORAGE })
+    if (user) {
+      this.user = user
+      this.websites = await websiteList({
+        connectorId: user.storage.connectorId
+      })
+    }
+  },
+
+  methods: {
+    async createWebsite() {
+      await websiteCreate({
+        websiteId: toSafeId(this.newWebsiteName),
+        data: { name: this.newWebsiteName }
+      })
+      this.websites = await websiteList()
+    },
+
+    async deleteWebsite(websiteId) {
+      if (confirm('Are you sure?')) {
+        await websiteDelete({ websiteId })
+        this.websites = await websiteList()
+      }
+    }
+  }
+}
+
+createApp(App).mount('.app')
+```
+
+---
+
+## Key Integration Points
+
+### A. Silex Page Settings → 11ty Template
+
+**How Language Multiplication Works**:
+
+1. **Silex Page Settings**:
+   ```javascript
+   {
+     name: 'Websites',
+     silexLanguagesList: 'en,fr',  // ← Triggers multiplication
+     eleventyPermalink: '[{
+       "type":"property",
+       "fieldId":"fixed",
+       "options":{"value":"/{{lang}}/"}
+     }]'
+   }
+   ```
+
+2. **Silex Publishes** → `templates/websites.html` (base template, no frontmatter)
+
+3. **11ty Detects** `silexLanguagesList` and creates:
+   - `templates/websites-en.html`
+   - `templates/websites-fr.html`
+
+4. **Each Gets Frontmatter**:
+   ```yaml
+   ---
+   permalink: "/{{lang}}/"  # From eleventyPermalink expression
+   lang: "en"               # Added by language multiplication
+   collection: "Websites"   # From page name
+   ---
+   ```
+
+5. **11ty Processes** each template independently with its own language context
+
+### B. TinaCMS → Liquid Templates
+
+**Expression System**:
+
+Silex uses a JSON-based expression builder that converts to Liquid syntax.
+
+**Example Expression** (in page settings SEO Title):
+```json
+[
+  {"type":"property","fieldId":"homeConnection"},
+  {"type":"property","fieldId":"edges"},
+  {"type":"filter","id":"where","options":{"key":"node.lang","value":"en"}},
+  {"type":"filter","id":"first"},
+  {"type":"property","fieldId":"node"},
+  {"type":"property","fieldId":"title"}
+]
+```
+
+**Converts to Liquid**:
+```liquid
+{% assign var_title = tina.homeConnection.edges
+   | where: "node.lang", page.lang
+   | first %}
+{{ var_title.node.title }}
+```
+
+**Used in HTML**:
+```html
+<h1>
+  {% assign var = tina.homeConnection.edges
+     | where: "node.lang", page.lang
+     | first %}
+  {{ var.node.title }}
+</h1>
+<!-- Outputs: <h1>Silex Dashboard</h1> -->
+```
+
+### C. Vue.js Directives in Silex HTML
+
+**How Vue.js is Embedded**:
+
+1. **In Page Settings** (Code tab):
+   ```html
+   <script src="/js/vue.global.prod.js"></script>
+   <script src="/js/main.js"></script>
+   <script type="module">
+     const App = { /* Vue app definition */ }
+     createApp(App).mount('.app')
+   </script>
+   ```
+
+2. **In Silex Visual Editor**, add Vue directives to HTML elements:
+   ```html
+   <div v-if="!empty" class="section">
+     <h1 v-text="title"></h1>
+     <button v-on:click="createWebsite">Create</button>
+   </div>
+
+   <div v-for="(website, index) in websites" :key="index">
+     <h3 v-text="website.name"></h3>
+     <p v-text="'Updated ' + new Date(website.updatedAt).toLocaleDateString()"></p>
+   </div>
+   ```
+
+3. **11ty Preserves** all Vue directives (they're just HTML attributes)
+
+4. **Browser Executes** Vue.js at runtime, making the page interactive
+
+### D. Dual Content Sources
+
+**Static Content** (from TinaCMS via Liquid):
+```html
+<button>
+  {% assign var = tina.homeConnection.edges | where: "node.lang", "en" | first %}
+  {{ var.node.add_button }}
+</button>
+<!-- Outputs: <button>Create website</button> -->
+```
+
+**Dynamic Content** (from Vue.js):
+```html
+<div v-for="website in websites">
+  <h3 v-text="website.name"></h3>
+  <!-- Outputs: <h3>My Project</h3> (from Silex API at runtime) -->
+</div>
+```
+
+**Why Both?**
+- **TinaCMS**: UI labels, navigation, footer (changes rarely, SEO-friendly, static)
+- **Vue.js**: User data, forms, API calls (changes frequently, requires authentication)
+
+---
+
+## Template System
+
+### Template Multiplication Process
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Silex Editor (1 page)                                  │
+│  - name: "Websites"                                     │
+│  - silexLanguagesList: "en,fr"                          │
+└────────────────────┬────────────────────────────────────┘
+                     │ Publish
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│  templates/websites.html (base)                         │
+│  - No frontmatter                                       │
+│  - All HTML/CSS/JS from Silex                           │
+└────────────────────┬────────────────────────────────────┘
+                     │ 11ty detects silexLanguagesList
+                     ▼
+         ┌───────────┴───────────┐
+         ▼                       ▼
+┌────────────────┐      ┌────────────────┐
+│ websites-      │      │ websites-      │
+│ en.html        │      │ fr.html        │
+├────────────────┤      ├────────────────┤
+│ ---            │      │ ---            │
+│ permalink:     │      │ permalink:     │
+│   "/en/"       │      │   "/fr/"       │
+│ lang: "en"     │      │ lang: "fr"     │
+│ ---            │      │ ---            │
+│                │      │                │
+│ (same HTML)    │      │ (same HTML)    │
+└────────┬───────┘      └────────┬───────┘
+         │                       │
+         │ 11ty + Liquid         │
+         ▼                       ▼
+┌────────────────┐      ┌────────────────┐
+│ _site/en/      │      │ _site/fr/      │
+│ index.html     │      │ index.html     │
+│                │      │                │
+│ (English       │      │ (French        │
+│  content)      │      │  content)      │
+└────────────────┘      └────────────────┘
+```
+
+### Content Resolution Flow
+
+```
+Template has Liquid tag:
+{{ tina.homeConnection.edges | where: "node.lang", page.lang | first | node.title }}
+                                                      ▲
+                                                      │
+                                                      │
+For websites-en.html:                    For websites-fr.html:
+    page.lang = "en"                         page.lang = "fr"
+          │                                        │
+          ▼                                        ▼
+Filters to en.md content              Filters to fr.md content
+          │                                        │
+          ▼                                        ▼
+Outputs: "Silex Dashboard"            Outputs: "Tableau de bord Silex"
+```
+
+### File Relationships
+
+```
+Silex Editor (Design)
+    ↓ publishes
+templates/websites.html ────┐
+                            │ copied + frontmatter added
+                            ├──→ templates/websites-en.html
+                            └──→ templates/websites-fr.html
+                                        ↓ 11ty + TinaCMS data
+                                        ↓
+                            ┌──→ _site/en/index.html
+                            └──→ _site/fr/index.html
+```
+
+---
+
+## Special Techniques
+
+### 1. Loading State Management
+
+**Problem**: Prevent flash of unstyled content before Vue.js loads
+
+**Solution**: CSS-based progressive enhancement
+
+```css
+/* In templates (added by Silex) */
+.before-js > * {
+  visibility: hidden;
+  opacity: 0;
+  transition: opacity .5s ease;
+}
+
+.after-js > * {
+  visibility: visible;
+  opacity: 1;
+}
+
+.before-js:before {
+  content: 'Loading';
+  position: absolute;
+  top: 49%;
+  left: 49%;
+}
+```
+
+```html
+<!-- Body has before-js class initially -->
+<body class="app before-js">
+  <!-- Content hidden until Vue loads -->
+</body>
+```
+
+```javascript
+// After Vue mounts
+setTimeout(() => {
+  document.querySelector('.before-js').classList.add('after-js')
+}, 100)
+```
+
+### 2. Skeleton Loaders
+
+**Problem**: Better UX while data is loading
+
+**Solution**: Show placeholder skeletons with CSS animation
+
+```html
+<!-- Loading state -->
+<div v-if="loading" class="skeleton-anim">
+  <h3 class="skeleton-text skeleton">Loading...</h3>
+  <p class="skeleton-text skeleton">Loading...</p>
+</div>
+
+<!-- Loaded state -->
+<div v-if="!loading" v-for="website in websites">
+  <h3 v-text="website.name"></h3>
+  <p v-text="website.updatedAt"></p>
+</div>
+```
+
+```css
+.skeleton-anim:after {
+  content: "";
+  position: absolute;
+  background: linear-gradient(
+    0.25turn,
+    transparent,
+    rgba(255,255,255,.75),
+    transparent
+  );
+  animation: loading 1.5s infinite;
+}
+
+@keyframes loading {
+  to { background-position: 200% 0; }
+}
+```
+
+### 3. Expression-Based Data Binding
+
+**Visual Builder for GraphQL Queries**:
+
+Instead of writing Liquid manually, Silex provides a dropdown UI:
+
+```
+Field Selector:
+┌─────────────────────────────┐
+│ homeConnection          [▼] │ ← Dropdown shows all GraphQL fields
+└─────────────────────────────┘
+         ↓
+┌─────────────────────────────┐
+│ edges                   [▼] │
+└─────────────────────────────┘
+         ↓
+Filter:
+┌─────────────────────────────┐
+│ where                   [▼] │
+│   key: node.lang            │
+│   value: en                 │
+└─────────────────────────────┘
+         ↓
+┌─────────────────────────────┐
+│ first                   [▼] │
+└─────────────────────────────┘
+         ↓
+┌─────────────────────────────┐
+│ node.title              [▼] │
+└─────────────────────────────┘
+```
+
+**Converts to**:
+```liquid
+{{ tina.homeConnection.edges | where: "node.lang", "en" | first | node.title }}
+```
+
+**Stored in website.json as**:
+```json
+{
+  "eleventySeoTitle": "[
+    {\"type\":\"property\",\"fieldId\":\"homeConnection\"},
+    {\"type\":\"property\",\"fieldId\":\"edges\"},
+    {\"type\":\"filter\",\"id\":\"where\",\"options\":{\"key\":\"node.lang\",\"value\":\"en\"}},
+    {\"type\":\"filter\",\"id\":\"first\"},
+    {\"type\":\"property\",\"fieldId\":\"node\"},
+    {\"type\":\"property\",\"fieldId\":\"title\"}
+  ]"
+}
+```
+
+### 4. API Translations Pattern
+
+**Problem**: Translate API error messages
+
+**Solution**: Centralized translation file + Liquid interpolation
+
+**File**: `11ty/_data/api-translations.json`
+```json
+{
+  "en": {
+    "Failed to start dashboard": "Failed to start dashboard",
+    "Website created successfully": "Website created successfully"
+  },
+  "fr": {
+    "Failed to start dashboard": "Erreur, impossible de démarrer",
+    "Website created successfully": "Le site a bien été créé"
+  }
+}
+```
+
+**Usage in Vue.js code**:
+```javascript
+this.error = `{{ api-translations[lang]["Failed to start dashboard"] }} - ${error.message}`
+this.message = '{{ api-translations[lang]["Website created successfully"] }}'
+```
+
+**After 11ty processing**:
+```javascript
+// In en/index.html
+this.error = `Failed to start dashboard - ${error.message}`
+
+// In fr/index.html
+this.error = `Erreur, impossible de démarrer - ${error.message}`
+```
+
+### 5. Locale Detection & Routing
+
+**Server-side routing** (`silex/server-config.js`):
+
+```javascript
+// Detect language from browser
+router.use(locale(languages.map(l => l.code), 'en'))
+
+// Redirect to user's language
+router.use('/', (req, res, next) => {
+  if (req.path === '/' && !req.query.id) {
+    res.redirect(`/${req.locale}/`)  // → /en/ or /fr/
+  } else {
+    next()
+  }
+})
+```
+
+**Client-side routing** (in Vue.js):
+```javascript
+openLogin() {
+  const path = `/{{lang}}/connectors/`
+  window.open(path, '_self')
+}
+
+openEditor(id) {
+  window.open(`/?id=${id}&lang={{lang}}&connectorId=${this.user.storage.connectorId}`, '_self')
+}
+```
+
+### 6. Hover Effects with CSS
+
+**Interactive buttons** without JavaScript:
+
+```css
+.fx-scale-round {
+  position: relative;
+  overflow: hidden;
+  transition: transform 0.2s cubic-bezier(0, -0.530, 0.405, 2.8);
+}
+
+.fx-scale-round::after {
+  content: "";
+  background: #ffffff;
+  position: absolute;
+  border-radius: 50%;
+  left: -50%;
+  right: -50%;
+  top: -100%;
+  bottom: -100%;
+  transform: scale(0);
+  transition: all 0.3s ease-out;
+}
+
+.fx-scale-round:hover {
+  transform: scale(1.1);
+}
+
+.fx-scale-round:hover::after {
+  transform: scale(1);
+}
+```
+
+---
+
+## Implementation Guide
+
+### Adding a New Page
+
+1. **In Silex Editor**:
+   ```
+   - Click "+" in Pages panel
+   - Name: "Settings"
+   - Design the page visually
+   - Configure page settings:
+     - General: name = "Settings"
+     - CMS: permalink = /{{lang}}/settings/
+     - Code: Add Vue.js if needed
+   - Click "Publish"
+   ```
+
+2. **In TinaCMS** (if page needs content):
+   ```typescript
+   // tina/config.ts
+   {
+     name: "settings_content",
+     path: "collections/settings_content",
+     fields: [
+       { name: 'title', type: 'string' },
+       // ... more fields
+     ]
+   }
+   ```
+
+3. **Create data file**:
+   ```javascript
+   // templates/settings-en.11tydata.mjs
+   export default async function() {
+     const response = await fetch('http://localhost:4001/graphql', {
+       body: JSON.stringify({
+         query: `{ settingsContentConnection { ... } }`
+       })
+     })
+     return { tina: response.data }
+   }
+   ```
+
+4. **11ty auto-generates**:
+   - `_site/en/settings/index.html`
+   - `_site/fr/settings/index.html`
+
+### Adding a New TinaCMS Field
+
+1. **Update schema** (`tina/config.ts`):
+   ```typescript
+   {
+     name: "home",
+     fields: [
+       // ... existing fields
+       {
+         label: 'Welcome Message',
+         name: 'welcome_message',
+         type: 'string'
+       }
+     ]
+   }
+   ```
+
+2. **Restart TinaCMS**:
+   ```bash
+   npm run tina:dev
+   ```
+
+3. **Edit content** in TinaCMS admin:
+   - Open http://localhost:4001/admin
+   - Edit `home/en.md`
+   - Add value for "Welcome Message"
+
+4. **Use in template** (via expression builder or Liquid):
+   ```liquid
+   {{ tina.homeConnection.edges | where: "node.lang", "en" | first | node.welcome_message }}
+   ```
+
+### Adding a New Vue.js Method
+
+1. **Open page settings** in Silex (Code tab)
+
+2. **Add method**:
+   ```javascript
+   methods: {
+     // ... existing methods
+
+     async archiveWebsite(websiteId) {
+       this.loading = true
+       try {
+         await websiteArchive({ websiteId, connectorId: this.user.storage.connectorId })
+         this.websites = await websiteList({ connectorId: this.user.storage.connectorId })
+         this.message = 'Website archived successfully'
+       } catch (error) {
+         this.error = `Failed to archive website - ${error.message}`
+       }
+       this.loading = false
+     }
+   }
+   ```
+
+3. **Add button** in Silex visual editor:
+   ```html
+   <button v-on:click="archiveWebsite(website.websiteId)">
+     Archive
+   </button>
+   ```
+
+4. **Publish** and test
+
+### Customizing Styles
+
+**Option 1: Visual Editor**
+- Select element in Silex
+- Use Style Manager panel (right side)
+- Apply styles visually
+
+**Option 2: CSS Classes**
+- Add class in Silex: `my-custom-button`
+- Define in page settings (Code tab):
+  ```html
+  <style>
+    .my-custom-button {
+      background: linear-gradient(45deg, #8873fe, #ff6b9d);
+      border-radius: 8px;
+      padding: 12px 24px;
+    }
+  </style>
+  ```
+
+**Option 3: Global Styles**
+- Edit `templates/websites.html` `<style>` section
+- Changes apply to all language versions
+
+---
+
+## Template/Fork Feature Design
+
+### Use Cases
+
+1. **Designer wants to share a template**:
+   - "Export my dashboard design as a reusable template"
+   - "Let others start from my design"
+
+2. **User wants to clone a site**:
+   - "Create a copy of this dashboard for another project"
+   - "Start from a template instead of blank"
+
+3. **Agency wants to offer templates**:
+   - "Pre-built dashboards for clients"
+   - "Customizable starting points"
+
+### What is a "Template"?
+
+A **complete, self-contained** Silex website package:
+
+```
+template-dashboard/
+├── metadata.json           # Template info (name, author, preview)
+├── website.json            # Silex pages, styles, components
+├── collections/            # TinaCMS content structure
+├── tina-schema.json        # TinaCMS schema (exported)
+├── assets/                 # Images, fonts
+└── config/
+    ├── client-config.js    # CMS datasource config
+    ├── server-config.js    # Server middleware (optional)
+    └── eleventy.config.mjs # 11ty config (optional)
+```
+
+### Template Metadata Format
+
+```json
+{
+  "id": "dashboard-v1",
+  "name": "Dashboard Template",
+  "description": "Multi-language dashboard with user management",
+  "author": "Silex Labs",
+  "version": "1.0.0",
+  "preview": "preview.png",
+  "tags": ["dashboard", "admin", "i18n", "vue"],
+  "technologies": ["TinaCMS", "Vue.js", "11ty"],
+  "languages": ["en", "fr"],
+  "pages": 2,
+  "features": [
+    "User authentication",
+    "Website CRUD",
+    "Multi-language support",
+    "Responsive design"
+  ],
+  "customization": {
+    "colors": ["primary", "secondary", "background"],
+    "texts": ["site_name", "tagline"],
+    "logo": true
+  }
+}
+```
+
+### Implementation Options
+
+#### Option A: Export/Import System
+
+**Export Flow**:
+```
+1. User clicks "Export as Template" in Silex
+2. Silex packages:
+   - website.json (from current site)
+   - collections/ (from disk)
+   - tina/config.ts → tina-schema.json
+   - assets/ (images, fonts)
+   - metadata.json (user fills form)
+3. Downloads template-dashboard.zip
+```
+
+**Import Flow**:
+```
+1. User clicks "Import Template" in Silex
+2. Uploads template-dashboard.zip
+3. Silex extracts and creates:
+   - New website ID
+   - Copies website.json to silex/websites/{newId}/
+   - Copies collections/ to project
+   - Sets up TinaCMS schema
+   - Imports assets
+4. Opens new site in editor
+```
+
+**Implementation**:
+```javascript
+// In Silex server
+router.post('/api/template/export', async (req, res) => {
+  const { websiteId } = req.body
+
+  // Read website.json
+  const website = await readWebsite(websiteId)
+
+  // Package files
+  const zip = new JSZip()
+  zip.file('website.json', JSON.stringify(website))
+  zip.file('metadata.json', JSON.stringify(req.body.metadata))
+
+  // Add collections
+  const collections = await fs.readdir('collections')
+  for (const col of collections) {
+    const files = await fs.readdir(`collections/${col}`)
+    for (const file of files) {
+      const content = await fs.readFile(`collections/${col}/${file}`)
+      zip.file(`collections/${col}/${file}`, content)
+    }
+  }
+
+  // Add assets
+  const assets = website.assets
+  for (const asset of assets) {
+    const file = await fs.readFile(`templates/${asset.src}`)
+    zip.file(`assets/${asset.src}`, file)
+  }
+
+  // Generate zip
+  const buffer = await zip.generateAsync({ type: 'nodebuffer' })
+  res.setHeader('Content-Disposition', `attachment; filename=${websiteId}.zip`)
+  res.send(buffer)
+})
+
+router.post('/api/template/import', upload.single('template'), async (req, res) => {
+  const zip = await JSZip.loadAsync(req.file.buffer)
+
+  // Extract metadata
+  const metadata = JSON.parse(await zip.file('metadata.json').async('string'))
+
+  // Generate new website ID
+  const newId = generateId()
+
+  // Extract website.json
+  const website = JSON.parse(await zip.file('website.json').async('string'))
+  await writeWebsite(newId, website)
+
+  // Extract collections
+  const collectionFiles = Object.keys(zip.files).filter(f => f.startsWith('collections/'))
+  for (const file of collectionFiles) {
+    const content = await zip.file(file).async('string')
+    await fs.writeFile(file, content)
+  }
+
+  // Extract assets
+  const assetFiles = Object.keys(zip.files).filter(f => f.startsWith('assets/'))
+  for (const file of assetFiles) {
+    const content = await zip.file(file).async('nodebuffer')
+    await fs.writeFile(`templates/${file}`, content)
+  }
+
+  res.json({ websiteId: newId, name: metadata.name })
+})
+```
+
+#### Option B: Template API (In-App)
+
+**Template Registry**:
+```javascript
+// In Silex server
+const TEMPLATES = [
+  {
+    id: 'dashboard',
+    name: 'Dashboard',
+    path: './templates/dashboard-template'
+  },
+  {
+    id: 'portfolio',
+    name: 'Portfolio',
+    path: './templates/portfolio-template'
+  }
+]
+
+router.get('/api/templates', (req, res) => {
+  res.json(TEMPLATES.map(t => ({
+    id: t.id,
+    ...require(`${t.path}/metadata.json`)
+  })))
+})
+
+router.post('/api/website/create-from-template', async (req, res) => {
+  const { templateId, websiteId, customizations } = req.body
+
+  const template = TEMPLATES.find(t => t.id === templateId)
+
+  // Load template
+  const website = require(`${template.path}/website.json`)
+
+  // Apply customizations
+  if (customizations.colors) {
+    applyColorCustomizations(website, customizations.colors)
+  }
+  if (customizations.texts) {
+    applyTextCustomizations(website, customizations.texts)
+  }
+
+  // Save new website
+  await writeWebsite(websiteId, website)
+
+  // Copy collections
+  await copyDir(`${template.path}/collections`, 'collections')
+
+  res.json({ websiteId })
+})
+```
+
+**UI Flow**:
+```
+1. User clicks "New Website from Template"
+2. Shows template gallery:
+   ┌─────────────┬─────────────┬─────────────┐
+   │  Dashboard  │  Portfolio  │    Blog     │
+   │   [Preview] │   [Preview] │   [Preview] │
+   │    [Use]    │    [Use]    │    [Use]    │
+   └─────────────┴─────────────┴─────────────┘
+3. User clicks "Use Dashboard"
+4. Customization dialog:
+   - Site name: [My Dashboard____]
+   - Primary color: [#8873fe]
+   - Logo: [Upload___]
+5. Creates website, opens in editor
+```
+
+#### Option C: Fork/Duplicate Feature
+
+**Simple duplication** (already possible in dashboard):
+
+```javascript
+// In Vue.js app
+async duplicateWebsite(websiteId) {
+  await websiteDuplicate({
+    websiteId,
+    connectorId: this.user.storage.connectorId
+  })
+  this.websites = await websiteList()
+}
+```
+
+**Enhanced with customization**:
+
+```javascript
+async forkWebsite(websiteId) {
+  // Show customization dialog
+  const customizations = await showForkDialog()
+
+  // Duplicate
+  const newId = await websiteDuplicate({ websiteId })
+
+  // Apply customizations via API
+  await websiteCustomize({
+    websiteId: newId,
+    name: customizations.name,
+    colors: customizations.colors,
+    logo: customizations.logo
+  })
+
+  // Open in editor
+  window.open(`/?id=${newId}`, '_self')
+}
+```
+
+### Customization System
+
+**Define customizable fields**:
+
+```json
+// In template metadata
+{
+  "customization": {
+    "schema": [
+      {
+        "id": "primary_color",
+        "label": "Primary Color",
+        "type": "color",
+        "default": "#8873fe",
+        "affects": [".button--primary", ".nav__item--active"]
+      },
+      {
+        "id": "site_name",
+        "label": "Site Name",
+        "type": "text",
+        "default": "My Dashboard",
+        "affects": ["collections/home/*/title"]
+      },
+      {
+        "id": "logo",
+        "label": "Logo",
+        "type": "image",
+        "default": "/assets/logo.svg",
+        "affects": [".nav__logo"]
+      }
+    ]
+  }
+}
+```
+
+**Apply customizations**:
+
+```javascript
+function applyCustomizations(website, customizations) {
+  // Replace colors in styles
+  website.styles.forEach(style => {
+    if (style.style['background-color'] === '#8873fe') {
+      style.style['background-color'] = customizations.primary_color
+    }
+  })
+
+  // Replace text in collections
+  collections.home.forEach(file => {
+    file.title = file.title.replace('My Dashboard', customizations.site_name)
+  })
+
+  // Replace logo
+  website.assets.forEach(asset => {
+    if (asset.src === '/assets/logo.svg') {
+      asset.src = customizations.logo
+    }
+  })
+}
+```
+
+### Recommended Approach
+
+**Phase 1: Simple Export/Import**
+- Export button in Silex dashboard
+- Downloads .zip with website.json + collections
+- Import uploads .zip, creates new site
+- No customization UI yet
+
+**Phase 2: Template Gallery**
+- Built-in templates in Silex
+- "New from Template" button
+- Gallery UI with previews
+- One-click creation
+
+**Phase 3: Customization**
+- Template metadata defines customizable fields
+- UI for color picker, text inputs, image upload
+- Live preview of customizations
+- Apply before creating site
+
+**Phase 4: Marketplace**
+- Community templates
+- Rating/reviews
+- Search/filter
+- Premium templates
+
+### Technical Considerations
+
+**Storage**:
+- Templates in filesystem: `templates/library/`
+- Or in database with version control
+- Or remote registry (npm-style)
+
+**Versioning**:
+- Template version in metadata
+- Migration scripts for breaking changes
+- Compatibility checks
+
+**Dependencies**:
+- TinaCMS schema changes
+- Required plugins
+- Node version requirements
+
+**Security**:
+- Validate uploaded templates
+- Sanitize user inputs
+- Prevent code injection in Vue.js snippets
+
+---
+
+## Summary
+
+The Silex Dashboard demonstrates a **triple-layer architecture**:
+
+1. **Design Layer** (Silex + GrapesJS):
+   - Visual editing
+   - Component structure
+   - CSS styling
+   - Page settings
+
+2. **Content Layer** (TinaCMS + 11ty):
+   - Static content management
+   - Multi-language support
+   - GraphQL API
+   - Static site generation
+
+3. **Application Layer** (Vue.js):
+   - Runtime interactivity
+   - API integration
+   - State management
+   - User interactions
+
+**Key Benefits**:
+- **Designers** work visually in Silex
+- **Content editors** use TinaCMS admin
+- **Developers** add features via Vue.js
+- **End result**: Fast, static, SEO-friendly, interactive site
+
+**For Template/Fork Features**:
+- Package: website.json + collections + assets
+- Export: Zip download or API
+- Import: Upload or template gallery
+- Customize: Colors, text, images via UI
+
+---
+
+## Quick Reference
+
+### Common Tasks
+
+| Task | Files to Edit | How |
+|------|---------------|-----|
+| **Change page design** | Use Silex Editor | Visual drag & drop |
+| **Update UI labels** | `collections/home/*.md` | Edit in TinaCMS or text editor |
+| **Add navigation link** | `collections/settings/*.json` | Edit `nav` array |
+| **Add new page** | Silex Editor | Pages panel → "+" button |
+| **Modify Vue.js logic** | Silex page settings (Code tab) | Edit `<script>` in HEAD |
+| **Add TinaCMS field** | `tina/config.ts` | Add to `fields` array |
+| **Change permalink** | Silex page settings (CMS tab) | Edit "Permalink" expression |
+| **Customize styles** | Silex Style Manager | Visual or CSS |
+
+### File Locations
+
+| Content | Path |
+|---------|------|
+| **Page structure** | `silex/websites/dashboard/website.json` |
+| **UI labels** | `collections/home/*.md` |
+| **Navigation** | `collections/settings/*.json` |
+| **TinaCMS schema** | `tina/config.ts` |
+| **11ty config** | `11ty/eleventy.config.mjs` |
+| **Templates** | `templates/*.html` |
+| **Final output** | `_site/` |
+
+### API Endpoints
+
+| Endpoint | Purpose |
+|----------|---------|
+| `http://localhost:6805/?id=dashboard` | Silex editor |
+| `http://localhost:4001/admin` | TinaCMS admin |
+| `http://localhost:4001/graphql` | GraphQL API |
+| `http://localhost:8080/en/` | Preview (English) |
+| `http://localhost:8080/fr/` | Preview (French) |
+
+---
+
+**Last Updated**: December 27, 2025
+**Maintainer**: Silex Team
+**Questions?**: https://docs.silex.me or https://community.silex.me