Mike/RSSuper
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Design shared data models for native platforms

Browse Source 
- Define core entities: FeedItem, FeedSubscription, SearchHistoryItem
- Document entity relationships with diagram
- Create database schema with SQLite and FTS5
- Provide type mapping guide for Swift/Kotlin/C
- Define value types vs reference types
- Document enumeration types for all platforms
- Specify serialization/deserialization requirements
- Outline indexing strategy for performance
- Include memory considerations and future extensibility
This commit is contained in:
Michael Freno
2026-03-29 14:02:34 -04:00
parent 5f4d5a52e8
commit af87f9f571
1 changed files with 506 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

506
tasks/native-business-logic-migration/02-design-shared-data-models.md Normal file
View File

@@ -0,0 +1,506 @@
# 02. Design shared data models for all platforms
meta:
id: native-business-logic-migration-02
feature: native-business-logic-migration
priority: P0
depends_on: [native-business-logic-migration-01]
tags: [design, data-models]
objective:
- Design platform-agnostic data models that can be implemented natively on each platform
deliverables:
- Data model specification document
- Entity relationship diagram
- Type mapping guide (TypeScript → Swift/Kotlin/C)
- Database schema design
steps:
- Review TypeScript types from src/types/feed.ts
- Identify core entities: Feed, FeedItem, FeedSubscription, SearchResult
- Design normalized database schema
- Create type mapping documentation
- Define value types vs reference types
- Design enumeration types for each platform
- Document serialization/deserialization requirements
acceptance_criteria:
- All data models documented with properties and types
- Entity relationships clearly defined
- Type mapping guide complete for all three platforms
- Database schema designed with proper indexing
- Value types identified (Date, UUID, Enums)
notes:
- Use UUID for identifiers across all platforms
- Date handling needs platform-specific implementation
- Consider memory footprint for large feed items
- Plan for future extensibility
---
# Shared Data Models Design
## Overview
This document defines platform-agnostic data models for RSSuper, enabling native implementations on iOS (Swift), Android (Kotlin), and Linux (C). The models are designed for SQLite persistence with full-text search support.
---
## 1. Core Entities
### 1.1 FeedItem
Represents a single article or episode from a feed.
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| id | UUID | Yes | Unique identifier |
| title | String | Yes | Item title |
| link | String | No | URL to full article |
| description | String | No | Short summary |
| content | String | No | Full content (may be large) |
| author | String | No | Author name |
| published | DateTime | No | Publication date |
| updated | DateTime | No | Last update date |
| categories | String[] | No | Category tags |
| enclosure | Enclosure | No | Media attachment |
| guid | String | No | Global unique identifier from feed |
| subscriptionId | UUID | Yes | Parent subscription |
| subscriptionTitle | String | No | Denormalized for display |
#### Enclosure (nested)
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| url | String | Yes | Media URL |
| type | String | Yes | MIME type (audio/mpeg, image/jpeg, etc.) |
| length | Int64 | No | File size in bytes |
### 1.2 FeedSubscription
Represents a feed subscription with configuration.
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| id | UUID | Yes | Unique identifier |
| url | String | Yes | Feed URL (unique) |
| title | String | Yes | Display title |
| category | String | No | User-defined category |
| enabled | Boolean | Yes | Active/inactive |
| fetchInterval | Int32 | Yes | Fetch interval in minutes |
| createdAt | DateTime | Yes | Creation timestamp |
| updatedAt | DateTime | Yes | Last modification |
| lastFetchedAt | DateTime | No | Last successful fetch |
| nextFetchAt | DateTime | No | Next scheduled fetch |
| error | String | No | Last error message |
| httpAuth | HttpAuth | No | HTTP authentication |
#### HttpAuth (nested)
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| username | String | Yes | Username |
| password | String | Yes | Password (should be encrypted) |
### 1.3 SearchHistoryItem
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| id | UUID | Yes | Unique identifier |
| query | String | Yes | Search query text |
| timestamp | DateTime | Yes | When query was executed |
---
## 2. Entity Relationship Diagram
```
┌─────────────────────┐ ┌─────────────────────┐
│ FeedSubscription │ │ SearchHistory │
├─────────────────────┤ ├─────────────────────┤
│ id (PK) │ │ id (PK) │
│ url (UNIQUE) │ │ query │
│ title │ │ timestamp │
│ category │ └─────────────────────┘
│ enabled │
│ fetch_interval │ ┌─────────────────────┐
│ created_at │ │ FeedItem │
│ updated_at │ ├─────────────────────┤
│ last_fetched_at │ │ id (PK) │
│ next_fetch_at │──────┐ │ subscription_id(FK)│◄──┐
│ error │ │ │ title │ │
│ http_auth_username │ │ │ link │ │
│ http_auth_password │ │ │ description │ │
└─────────────────────┘ │ │ content │ │
│ │ author │ │
│ │ published │ │
│ │ updated │ │
│ │ guid (UNIQUE) │ │
│ │ enclosure_url │ │
│ │ enclosure_type │ │
│ │ enclosure_length │ │
│ │ categories (JSON) │ │
│ │ created_at │ │
│ └─────────────────────┘ │
│ │
└────────────────────────────────┘
```
---
## 3. Database Schema Design
### 3.1 subscriptions
```sql
CREATE TABLE subscriptions (
id TEXT PRIMARY KEY,
url TEXT UNIQUE NOT NULL,
title TEXT NOT NULL,
category TEXT,
enabled INTEGER NOT NULL DEFAULT 1,
fetch_interval INTEGER NOT NULL DEFAULT 60,
created_at INTEGER NOT NULL,
updated_at INTEGER NOT NULL,
last_fetched_at INTEGER,
next_fetch_at INTEGER,
error TEXT,
http_auth_username TEXT,
http_auth_password TEXT
);
CREATE INDEX idx_subscriptions_url ON subscriptions(url);
CREATE INDEX idx_subscriptions_category ON subscriptions(category);
CREATE INDEX idx_subscriptions_next_fetch ON subscriptions(next_fetch_at) WHERE enabled = 1;
CREATE INDEX idx_subscriptions_enabled ON subscriptions(enabled);
```
### 3.2 feed_items
```sql
CREATE TABLE feed_items (
id TEXT PRIMARY KEY,
subscription_id TEXT NOT NULL,
title TEXT NOT NULL,
link TEXT,
description TEXT,
content TEXT,
author TEXT,
published INTEGER,
updated INTEGER,
guid TEXT,
enclosure_url TEXT,
enclosure_type TEXT,
enclosure_length INTEGER,
categories TEXT,
created_at INTEGER NOT NULL,
FOREIGN KEY (subscription_id) REFERENCES subscriptions(id) ON DELETE CASCADE
);
CREATE UNIQUE INDEX idx_feed_items_guid ON feed_items(guid) WHERE guid IS NOT NULL;
CREATE INDEX idx_feed_items_subscription ON feed_items(subscription_id);
CREATE INDEX idx_feed_items_published ON feed_items(published DESC);
CREATE INDEX idx_feed_items_created ON feed_items(created_at DESC);
```
### 3.3 search_history
```sql
CREATE TABLE search_history (
id TEXT PRIMARY KEY,
query TEXT NOT NULL,
timestamp INTEGER NOT NULL
);
CREATE INDEX idx_search_history_timestamp ON search_history(timestamp DESC);
```
### 3.4 Full-Text Search (FTS5)
```sql
CREATE VIRTUAL TABLE feed_items_fts USING fts5(
title,
description,
content,
author,
categories,
content='feed_items',
content_rowid='rowid'
);
CREATE VIRTUAL TABLE subscriptions_fts USING fts5(
title,
url,
category,
content='subscriptions',
content_rowid='rowid'
);
```
---
## 4. Type Mapping Guide
### 4.1 Primitive Types
| TypeScript | Swift (Kotlin/C) | SQLite | Notes |
|------------|------------------|--------|-------|
| `string` | `String` (`String`/`char*`) | TEXT | UTF-8 encoded |
| `number` | `Int`/`Double` (`Int`/`Double`/`int64_t`) | INTEGER/REAL | Use REAL for decimals |
| `boolean` | `Bool` (`Boolean`/`int`) | INTEGER | 0 or 1 |
| `Date` | `Date` (`LocalDateTime`/`time_t`) | INTEGER | Unix timestamp (milliseconds) |
| `UUID` | `UUID` (`UUID`/`uuid_t`) | TEXT | String format: "550e8400-e29b-41d4-a716-446655440000" |
| `string[]` | `[String]` (`List<String>`/`char**`) | TEXT | JSON array |
### 4.2 Core Model Mapping
#### FeedItem
| Property | TypeScript | Swift | Kotlin | C (struct) |
|----------|------------|-------|--------|------------|
| id | `string` | `String` | `String` | `char id[37]` |
| title | `string` | `String` | `String` | `char title[512]` |
| link | `string?` | `String?` | `String?` | `char* link` |
| description | `string?` | `String?` | `String?` | `char* description` |
| content | `string?` | `String?` | `String?` | `char* content` |
| author | `string?` | `String?` | `String?` | `char* author` |
| published | `Date?` | `Date?` | `Long?` | `int64_t published` |
| updated | `Date?` | `Date?` | `Long?` | `int64_t updated` |
| categories | `string[]?` | `[String]?` | `String?` | `char* categories` |
| enclosure | `Enclosure?` | `Enclosure?` | `Enclosure?` | `Enclosure* enclosure` |
| guid | `string?` | `String?` | `String?` | `char* guid` |
| subscriptionId | `string` | `String` | `String` | `char subscription_id[37]` |
#### FeedSubscription
| Property | TypeScript | Swift | Kotlin | C (struct) |
|----------|------------|-------|--------|------------|
| id | `string` | `String` | `String` | `char id[37]` |
| url | `string` | `String` | `String` | `char url[2048]` |
| title | `string` | `String` | `String` | `char title[512]` |
| category | `string?` | `String?` | `String?` | `char* category` |
| enabled | `boolean` | `Bool` | `Boolean` | `int enabled` |
| fetchInterval | `number` | `Int` | `Int` | `int fetch_interval` |
| createdAt | `Date` | `Date` | `Long` | `int64_t created_at` |
| updatedAt | `Date` | `Date` | `Long` | `int64_t updated_at` |
| lastFetchedAt | `Date?` | `Date?` | `Long?` | `int64_t last_fetched_at` |
| nextFetchAt | `Date?` | `Date?` | `Long?` | `int64_t next_fetch_at` |
| error | `string?` | `String?` | `String?` | `char* error` |
| httpAuth | `HttpAuth?` | `HttpAuth?` | `HttpAuth?` | `HttpAuth* http_auth` |
---
## 5. Value Types vs Reference Types
### 5.1 Value Types (Copy on assign)
All primitive types should be treated as **value types**:
- UUID (string representation)
- Date (Unix timestamp)
- Boolean
- Integer
- Float
### 5.2 Reference Types (Pointer/Heap)
Complex types should be **reference types**:
- FeedItem (stored by ID reference)
- FeedSubscription (stored by ID reference)
- Enclosure (inline in FeedItem)
- HttpAuth (inline in FeedSubscription)
### 5.3 Implementation Notes
**Swift**: Use `struct` for value types, `class` for reference types
**Kotlin**: Use `data class` for all models, pass by value
**C**: Use struct with explicit memory management
---
## 6. Enumeration Types
### 6.1 ContentType
```typescript
type ContentType = 'article' | 'audio' | 'video';
```
| TypeScript | Swift | Kotlin | C |
|------------|-------|--------|---|
| `'article'` | `ContentType.article` | `ContentType.ARTICLE` | `CONTENT_TYPE_ARTICLE` |
| `'audio'` | `ContentType.audio` | `ContentType.AUDIO` | `CONTENT_TYPE_AUDIO` |
| `'video'` | `ContentType.video` | `ContentType.VIDEO` | `CONTENT_TYPE_VIDEO` |
### 6.2 Theme
```typescript
type Theme = 'system' | 'light' | 'dark';
```
| TypeScript | Swift | Kotlin | C |
|------------|-------|--------|---|
| `'system'` | `Theme.system` | `Theme.SYSTEM` | `THEME_SYSTEM` |
| `'light'` | `Theme.light` | `Theme.LIGHT` | `THEME_LIGHT` |
| `'dark'` | `Theme.dark` | `Theme.DARK` | `THEME_DARK` |
### 6.3 Privacy
```typescript
type Privacy = 'public' | 'private' | 'anonymous';
```
| TypeScript | Swift | Kotlin | C |
|------------|-------|--------|---|
| `'public'` | `Privacy.public` | `Privacy.PUBLIC` | `PRIVACY_PUBLIC` |
| `'private'` | `Privacy.private` | `Privacy.PRIVATE` | `PRIVACY_PRIVATE` |
| `'anonymous'` | `Privacy.anonymous` | `Privacy.ANONYMOUS` | `PRIVACY_ANONYMOUS` |
### 6.4 NotificationType
```typescript
enum NotificationType {
NEW_ARTICLE = 'NEW_ARTICLE',
EPISODE_RELEASE = 'EPISODE_RELEASE',
CUSTOM_ALERT = 'CUSTOM_ALERT',
UPGRADE_PROMO = 'UPGRADE_PROMO'
}
```
| TypeScript | Swift | Kotlin | C |
|------------|-------|--------|---|
| `NEW_ARTICLE` | `NotificationType.newArticle` | `NotificationType.NEW_ARTICLE` | `NOTIFICATION_TYPE_NEW_ARTICLE` |
| `EPISODE_RELEASE` | `NotificationType.episodeRelease` | `NotificationType.EPISODE_RELEASE` | `NOTIFICATION_TYPE_EPISODE_RELEASE` |
| `CUSTOM_ALERT` | `NotificationType.customAlert` | `NotificationType.CUSTOM_ALERT` | `NOTIFICATION_TYPE_CUSTOM_ALERT` |
| `UPGRADE_PROMO` | `NotificationType.upgradePromo` | `NotificationType.UPGRADE_PROMO` | `NOTIFICATION_TYPE_UPGRADE_PROMO` |
---
## 7. Serialization/Deserialization
### 7.1 Date Handling
All dates stored as **Unix timestamp (milliseconds)** in SQLite. Convert to/from platform-specific types:
| Platform | Conversion |
|----------|------------|
| Swift | `Date(timeIntervalSince1970: timestamp / 1000)` |
| Kotlin | `Date(timestamp)` |
| C | `time_t` with `timestamp / 1000` |
### 7.2 JSON Fields
Arrays and nested objects stored as JSON strings:
```sql
-- Categories stored as JSON array
categories = '["tech", "programming", "rust"]'
-- Enclosure stored as JSON object
enclosure = '{"url": "...", "type": "audio/mpeg", "length": 1234567}'
```
### 7.3 UUID Handling
Store UUIDs as strings in canonical format:
```
550e8400-e29b-41d4-a716-446655440000
```
Generate using platform UUID libraries:
- Swift: `UUID().uuidString`
- Kotlin: `UUID.randomUUID().toString()`
- C: Use `uuid_generate()` from libuuid
---
## 8. Indexing Strategy
### 8.1 Primary Indexes
- `subscriptions.id` (auto-created for PRIMARY KEY)
- `feed_items.id` (auto-created for PRIMARY KEY)
### 8.2 Secondary Indexes
| Table | Index | Purpose |
|-------|-------|---------|
| subscriptions | `idx_subscriptions_url` | URL lookups |
| subscriptions | `idx_subscriptions_category` | Category filtering |
| subscriptions | `idx_subscriptions_next_fetch` | Sync scheduling |
| feed_items | `idx_feed_items_guid` | Deduplication |
| feed_items | `idx_feed_items_subscription` | Feed-specific items |
| feed_items | `idx_feed_items_published` | Sorting by date |
| search_history | `idx_search_history_timestamp` | History sorting |
### 8.3 FTS Indexes
| Virtual Table | Purpose |
|---------------|---------|
| `feed_items_fts` | Full-text search on articles |
| `subscriptions_fts` | Full-text search on subscriptions |
---
## 9. Memory Considerations
### 9.1 Large Content Handling
- `content` field can be very large (full article HTML)
- Use lazy loading for content display
- Consider compressing content with zlib for storage
- Limit in-memory cache to N most recent items
### 9.2 Streaming for Large Result Sets
Use cursor-based pagination:
```sql
-- Instead of OFFSET
SELECT * FROM feed_items
WHERE subscription_id = ?
ORDER BY published DESC
LIMIT 20;
-- Use last_published as cursor for next page
```
---
## 10. Future Extensibility
### 10.1 Schema Versioning
Add version table for migrations:
```sql
CREATE TABLE schema_version (
version INTEGER PRIMARY KEY,
applied_at INTEGER NOT NULL
);
```
### 10.2 Adding New Fields
- New optional fields: Add column with NULL default
- New required fields: Use migration with DEFAULT values
- Breaking changes: New table with shared ID
### 10.3 Feed Extensions
Support for future feed types:
- Podcast: Already supported via enclosure
- Video feeds: Use content type detection
- Media RSS: Extend enclosure model
---
## 11. Implementation Checklist
- [ ] Define UUID type alias for each platform
- [ ] Create Date conversion utilities
- [ ] Implement FeedItem model (struct/class)
- [ ] Implement FeedSubscription model
- [ ] Implement SearchHistoryItem model
- [ ] Create SQLite table definitions
- [ ] Implement FTS5 triggers for feed_items
- [ ] Implement FTS5 triggers for subscriptions
- [ ] Add database indexes
- [ ] Write serialization/deserialization code
- [ ] Implement pagination helpers