# Modyo Platform Architecture

## Overview

Modyo is a Digital Experience Platform (DXP) with four main modules:

```
Platform (Organization)
├── Content - Headless CMS
├── Channels - Website Builder
├── Customers - Identity & Forms
└── Core - Platform Management
```

## Core Concepts

### Platform/Organization
- Top-level container for all resources
- Configured via environment variables (MODYO_URL, MODYO_TOKEN)

### Publishing Workflow
All content follows a draft → publish workflow:
1. **Draft** - Initial creation, editable
2. **Review** - Pending approval (optional)
3. **Published** - Live, accessible via API/website
4. **Scheduled** - Future publish date

### ID vs UUID
- **IDs** change after publishing (new version created)
- **UUIDs** remain stable across versions
- Always use UUIDs for stable references

## API Authentication

All APIs use token-based auth:
```
Authorization: Bearer {api_token}
```

Token configured via MODYO_TOKEN environment variable.

## Resource URIs

Tool documentation accessed via:
```
modyo://mcp-{module}/tools/{tool-name}
```

## Common Patterns

### Smart Identifier Resolution
Most tools accept flexible identifiers:
- **Number** → Direct ID lookup
- **String** → Search by name/slug/host

### Verification Workflow
Add `verify: true` to get before/after comparison:
```json
{
  "before": {...},
  "after": {...},
  "changes": ["field1", "field2"],
  "verified": true
}
```

### Pagination
Standard pagination params:
- `page` - Page number (default: 1)
- `per_page` - Results per page (default: 30, max: 100)