update docs.

docs/design/data-model.md

@@ -242,9 +242,10 @@ Folders with `folder_type = 'tidy'` are source folders that contain emails waiti
 - Example: Inbox folder
 
 **UI Representation:**
-- Shows "pending count" and "processed count" badges
+- Shows "total", "pending", and "processed" count badges
 - Includes "View Pending" button if there are pending emails
 - May include priority indicators
+- Located in "Emails to organize" section
 
 ### Destination Folders
 
@@ -260,6 +261,7 @@ Folders with `folder_type = 'destination'` are target folders where emails are m
 - Shows "emails count" badge
 - Simpler interface without pending/processed indicators
 - Focus on folder management and viewing contents
+- Located in "Destination Folders" section
 
 ### Ignore Folders
 
@@ -276,6 +278,7 @@ Folders with `folder_type = 'ignore'` are folders that are stored in the databas
 - Hidden by default unless "Show Hidden" checkbox is checked
 - When visible, shows minimal information
 - No action buttons for organization or processing
+- Located in "Hidden Folders" section
 
 ### Folder Type Determination
 
@@ -287,17 +290,50 @@ Folder types are determined as follows:
     - Inbox: Tidy
     - Archive/Spam/Drafts: Ignore
     - All others: Destination
-- Manually created folders default to 'destination'
-- Folder type can be changed through the user interface
+- Manually created folders default to 'destination' (except 'inbox' which defaults to 'tidy')
+- Folder type can be changed through the user interface via dropdown
 - When changing to 'ignore', emails_count is reset to 0
 
+## ProcessedEmail Model
+
+The `ProcessedEmail` entity tracks email processing status to avoid reprocessing the same emails during synchronization and provide accurate pending email counts.
+
+### Attributes
+
+| Column Name | Data Type | Constraints | Description |
+|-------------|------------|--------------|-------------|
+| id | Integer | Primary Key, Autoincrement | Unique identifier for each processed email record |
+| user_id | Integer | Foreign Key to User, Not Null | Reference to the user who owns this email |
+| folder_id | Integer | Foreign Key to Folder, Not Null | Reference to the folder this email belongs to |
+| email_uid | String(255) | Not Null | Unique ID of the email from IMAP server |
+| folder_name | String(255) | Not Null | Name of the IMAP folder (for redundancy) |
+| is_processed | Boolean | Default: False | Processing status (false=pending, true=processed) |
+| first_seen_at | DateTime | Default: datetime.utcnow | First time this email was detected during sync |
+| processed_at | DateTime | Nullable | When the email was marked as processed |
+| created_at | DateTime | Default: datetime.utcnow | Record creation timestamp |
+| updated_at | DateTime | Default: datetime.utcnow, On Update | Record update timestamp |
+
+### Relationships
+
+- **Many-to-One**: Each `ProcessedEmail` belongs to one `User`
+- **Many-to-One**: Each `ProcessedEmail` belongs to one `Folder`
+- **Composite Key**: The combination of (user_id, folder_name, email_uid) should be unique to prevent duplicate records
+
+### Business Rules
+
+- Each processed email record must belong to a user and folder
+- Email UID must be unique per user and folder to prevent duplicates
+- Processing status tracks whether an email has been processed
+- First seen timestamp tracks when the email was first discovered
+- Processed timestamp is set when email is marked as processed
+
 ## Future Data Model Considerations
 
 ### Potential Enhancements
 
-1. **Email Entity**
-   - Store email metadata for better analytics
-   - Track email movement between folders
+1. **Email Movement Tracking**
+   - Store email movement history between folders
+   - Track source and destination folder for each moved email
 
 2. **Rule Engine**
    - Store parsed rule structures for better processing
@@ -309,4 +345,5 @@ Folder types are determined as follows:
 
 4. **Audit Log**
    - Track changes to user data
-   - Monitor folder operations
+   - Monitor folder operations
+   - Log email processing actions