diff --git a/Architecture.md b/Architecture.md
new file mode 100644
index 0000000..9b58d9f
--- /dev/null
+++ b/Architecture.md
@@ -0,0 +1,63 @@
+# Architecture
+
+## Package Structure
+
+```
+pkg_mokoog
+  com_mokoog            -- Admin component (dashboard, CRUD, batch, CSV)
+  plg_system_mokoog     -- System plugin (frontend meta tag injection)
+  plg_content_mokoog    -- Content plugin (editor form fields, live preview)
+  plg_webservices_mokoog -- WebServices plugin (REST API routes)
+```
+
+## Data Flow
+
+### Frontend (onBeforeCompileHead)
+1. System plugin detects current page (`option`, `view`, `id`)
+2. Loads custom OG data from `#__mokoog_tags` (language-aware)
+3. Falls back to category/menu OG data if available
+4. Auto-generates missing fields from article/product content
+5. Resolves image URL, auto-resizes if enabled
+6. Emits OG, Twitter, LinkedIn, Discord, Telegram meta tags
+7. Builds JSON-LD schema (Article, Product, or WebPage)
+8. Fires `onMokoOGAfterRender` for third-party extensions
+
+### Admin (content plugin)
+1. Content plugin adds OG fields tab to article/menu/category editor forms
+2. On save, stores custom OG data to `#__mokoog_tags` with language
+3. Live preview updates Facebook/Twitter card preview in real-time
+
+### API
+1. WebServices plugin registers routes on `onBeforeApiRoute`
+2. JSON:API controller provides full CRUD + content lookup endpoint
+3. Field whitelist prevents information leakage
+
+## Key Classes
+
+| Class | Location | Purpose |
+|-------|----------|---------|
+| MokoOG | plg_system_mokoog | Main system plugin, meta tag injection |
+| MokoOGContent | plg_content_mokoog | Editor form injection, OG data save/load |
+| MokoOGWebServices | plg_webservices_mokoog | API route registration |
+| TagsController | com_mokoog (admin) | Admin list publish/delete operations |
+| BatchController | com_mokoog | Batch OG generation for existing articles |
+| ImportExportController | com_mokoog | CSV import/export with language support |
+| TagTable | com_mokoog | DB table with field validation |
+| ImageHelper | plg_system_mokoog | Image resize, center-crop, validation |
+| ImageGenerator | plg_system_mokoog | Text overlay image generation (GD) |
+| JsonLdBuilder | plg_system_mokoog | Article, Product, WebPage, Breadcrumb schemas |
+
+## Database
+
+Single table: `#__mokoog_tags`
+
+- Unique key: `(content_type, content_id, language)`
+- Supports: `com_content`, `com_content.category`, `menu`, `com_mokoshop`
+- Language-aware queries prefer specific language over `*` wildcard
+
+## Performance
+
+- `loadArticle()` and `loadShopProduct()` use static per-request caching
+- Article pages: 1 DB query instead of 5 (consolidated in v1.0)
+- Batch processing capped at 200 per request
+- Generated images cached by content hash in `images/mokoog/generated/`