feat(domains): ✨ add domain support for DrawDB integration

- Introduce Domain and DomainTable models for logical grouping of tables.
- Implement export and import functionality for domains in DrawDB format.
- Update template execution modes to include domain processing.
- Enhance documentation for domain features and usage.

docs/DOMAINS_DRAWDB.md

@@ -0,0 +1,149 @@
+# Domains and DrawDB Areas Integration
+
+## Overview
+
+Domains provide a way to organize tables from potentially multiple schemas into logical business groupings. When working with DrawDB format, domains are automatically imported/exported as **Subject Areas** - a native DrawDB feature for visually grouping tables.
+
+## How It Works
+
+### Writing Domains to DrawDB (Export)
+
+When you export a database with domains to DrawDB format:
+
+1. **Schema Areas** are created automatically for each schema (existing behavior)
+2. **Domain Areas** are created for each domain, calculated based on the positions of the tables they contain
+3. The domain area bounds are automatically calculated to encompass all its tables with a small padding
+
+```go
+// Example: Creating a domain and exporting to DrawDB
+db := models.InitDatabase("mydb")
+
+// Create an "authentication" domain
+authDomain := models.InitDomain("authentication")
+authDomain.Tables = append(authDomain.Tables,
+    models.InitDomainTable("users", "public"),
+    models.InitDomainTable("roles", "public"),
+    models.InitDomainTable("permissions", "public"),
+)
+db.Domains = append(db.Domains, authDomain)
+
+// Create a "financial" domain spanning multiple schemas
+finDomain := models.InitDomain("financial")
+finDomain.Tables = append(finDomain.Tables,
+    models.InitDomainTable("accounts", "public"),
+    models.InitDomainTable("transactions", "public"),
+    models.InitDomainTable("ledger", "finance"),  // Different schema!
+)
+db.Domains = append(db.Domains, finDomain)
+
+// Write to DrawDB - domains become subject areas
+writer := drawdb.NewWriter(&writers.WriterOptions{
+    OutputPath: "schema.json",
+})
+writer.WriteDatabase(db)
+```
+
+The resulting DrawDB JSON will have Subject Areas for both:
+- "authentication" area containing the auth tables
+- "financial" area containing the financial tables from both schemas
+
+### Reading Domains from DrawDB (Import)
+
+When you import a DrawDB file with Subject Areas:
+
+1. **Subject Areas** are automatically converted to **Domains**
+2. Tables are assigned to a domain if they fall within the area's visual bounds
+3. Table references include both the table name and schema name
+
+```go
+// Example: Reading DrawDB with areas
+reader := drawdb.NewReader(&readers.ReaderOptions{
+    FilePath: "schema.json",
+})
+
+db, err := reader.ReadDatabase()
+if err != nil {
+    log.Fatal(err)
+}
+
+// Access domains
+for _, domain := range db.Domains {
+    fmt.Printf("Domain: %s\n", domain.Name)
+    for _, domainTable := range domain.Tables {
+        fmt.Printf("  - %s.%s\n", domainTable.SchemaName, domainTable.TableName)
+        
+        // Access the actual table reference if loaded
+        if domainTable.RefTable != nil {
+            fmt.Printf("    Description: %s\n", domainTable.RefTable.Description)
+        }
+    }
+}
+```
+
+## Domain Structure
+
+```go
+type Domain struct {
+    Name        string         // Domain name (e.g., "authentication", "user_data")
+    Description string         // Optional human-readable description
+    Tables      []*DomainTable // Tables belonging to this domain
+    Comment     string         // Optional comment
+    Metadata    map[string]any // Extensible metadata
+    Sequence    uint           // Ordering hint
+}
+
+type DomainTable struct {
+    TableName  string // Table name
+    SchemaName string // Schema containing the table
+    Sequence   uint   // Ordering hint
+    RefTable   *Table // Pointer to actual table (in-memory only, not serialized)
+}
+```
+
+## Multi-Schema Domains
+
+One of the key features of domains is that they can span multiple schemas:
+
+```
+Domain: "user_data"
+├── public.users
+├── public.profiles
+├── public.user_preferences
+├── auth.user_sessions
+└── auth.mfa_devices
+```
+
+This allows you to organize related tables even when they're stored in different schemas.
+
+## Visual Organization in DrawDB
+
+When viewing the exported DrawDB file in DrawDB Editor:
+
+1. **Schema areas** appear in one color (original behavior)
+2. **Domain areas** appear in a different color
+3. Domain area bounds are calculated to fit all contained tables
+4. Areas can overlap - a table can visually belong to multiple areas
+
+## Integration with Other Formats
+
+Currently, domain/area integration is implemented for DrawDB format. 
+
+To implement similar functionality for other formats:
+
+1. Identify if the format has a native grouping/area feature
+2. Add conversion logic in the reader to map format areas → Domain model
+3. Add conversion logic in the writer to map Domain model → format areas
+
+Example formats that could support domains:
+- **DBML**: Could use DBML's `TableGroup` feature
+- **DrawDB**: ✅ Already implemented (Subject Areas)
+- **GraphQL**: Could use schema directives
+- **Custom formats**: Implement as needed
+
+## Tips and Best Practices
+
+1. **Keep domains focused**: Each domain should represent a distinct business area
+2. **Document purposes**: Use Description and Comment fields to explain each domain
+3. **Use meaningful names**: Domain names should clearly reflect their purpose
+4. **Maintain schema consistency**: Keep related tables together in the same schema when possible
+5. **Use metadata**: Store tool-specific information in the Metadata field

docs/TEMPLATE_MODE.md

@@ -44,12 +44,13 @@ The `--mode` flag controls how the template is executed:
 |------|-------------|--------|-------------|
 | `database` | Execute once for entire database | Single file | Documentation, reports, overview files |
 | `schema` | Execute once per schema | One file per schema | Schema-specific documentation |
+| `domain` | Execute once per domain | One file per domain | Domain-based documentation, domain exports |
 | `script` | Execute once per script | One file per script | Script processing |
 | `table` | Execute once per table | One file per table | Model generation, table docs |
 
 ### Filename Patterns
 
-For multi-file modes (`schema`, `script`, `table`), use `--filename-pattern` to control output filenames:
+For multi-file modes (`schema`, `domain`, `script`, `table`), use `--filename-pattern` to control output filenames:
 
 ```bash
 # Default pattern
@@ -296,6 +297,13 @@ The data available in templates depends on the execution mode:
 .Metadata          // map[string]interface{} - User metadata
 ```
 
+### Domain Mode
+```go
+.Domain            // *models.Domain - Current domain
+.ParentDatabase    // *models.Database - Parent database context
+.Metadata          // map[string]interface{} - User metadata
+```
+
 ### Table Mode
 ```go
 .Table             // *models.Table - Current table
@@ -317,6 +325,7 @@ The data available in templates depends on the execution mode:
 **Database:**
 - `.Name` - Database name
 - `.Schemas` - List of schemas
+- `.Domains` - List of domains (business domain groupings)
 - `.Description`, `.Comment` - Documentation
 
 **Schema:**
@@ -325,6 +334,17 @@ The data available in templates depends on the execution mode:
 - `.Views`, `.Sequences`, `.Scripts` - Other objects
 - `.Enums` - Enum types
 
+**Domain:**
+- `.Name` - Domain name
+- `.Tables` - List of DomainTable references
+- `.Description`, `.Comment` - Documentation
+- `.Metadata` - Custom metadata map
+
+**DomainTable:**
+- `.TableName` - Name of the table
+- `.SchemaName` - Schema containing the table
+- `.RefTable` - Pointer to actual Table object (if loaded)
+
 **Table:**
 - `.Name` - Table name
 - `.Schema` - Schema name