# Card Subdomain (DDD)

This document outlines the domain model for the Card feature, following Domain-Driven Design principles.

## Bounded Context

The Card context represents a system where users can save various types of content (URLs, notes, highlights, screenshots, files) to their personal libraries and collections.

## Domain Model

### Aggregates

1. **Card Aggregate**
   - Represents a saveable item (URL, note, highlight, screenshot, file)
   - Responsible for maintaining its own integrity
   - Contains references to related cards (highlights, notes, screenshots)
   - Does NOT directly manage which collections it belongs to

2. **Collection Aggregate**
   - Represents a user-defined grouping of cards
   - Manages which cards belong to it
   - Responsible for maintaining collection membership

### Entities

1. **Card** (Aggregate Root)
   - Has identity through CardId
   - Properties: type, content, metadata, creation date
   - May reference other cards (for highlights, notes, screenshots)

2. **Collection** (Aggregate Root)
   - Has identity through CollectionId
   - Properties: name, description, creation date
   - Contains references to member cards

### Value Objects

1. **CardId**
   - Unique identifier for a card

2. **CardType**
   - Enumeration of possible card types (URL, Note, Highlight)

3. **CardContent**
   - Value object representing the content of a card with type-specific validation
   - URL cards contain URL and optional UrlMetadata
   - Note cards contain text and optional title
   - Highlight cards contain highlighted text with robust anchoring using multiple selectors (TextQuote, TextPosition, Range) following Hypothes.is approach for reliable re-anchoring

4. **CollectionId**
   - Unique identifier for a collection

5. **CuratorId**
   - References the user who owns/created the card or collection

6. **URL**
   - Value object representing a valid URL

7. **UrlMetadata**
   - Value object containing metadata about a URL (title, description, author, etc.)

## Domain Services

1. **LibraryService**
   - Coordinates operations that span multiple aggregates
   - Handles adding cards to a user's library and collections
   - Provides access to a user's entire content (their "library")

## Infrastructure Services

1. **IMetadataService**
   - Interface for external metadata retrieval services
   - Abstracts the details of specific metadata providers (Citoid, etc.)

2. **IUrlMetadataRepository**
   - Repository interface for storing and retrieving URL metadata
   - Provides caching layer for metadata to avoid repeated API calls

## Relationships and Boundaries

- **Card-Collection Relationship**: This is a many-to-many relationship. A card can be in multiple collections, and a collection can contain multiple cards.
- **Aggregate Boundaries**:
  - The Card aggregate is responsible for its own data and direct relationships to other cards.
  - The Collection aggregate manages which cards are members of the collection.
  - When adding a card to a collection, the operation is handled by the Collection aggregate.

- **Card-to-Card Relationships**:
  - URL cards are standalone and do not reference other cards
  - Note cards can be standalone or reference other cards via parentCardId
  - Highlight cards must reference a parent card (the content being highlighted) via parentCardId
  - These relationships are maintained within the Card aggregate with validation rules

## Use Cases

1. **AddCardToLibrary**
   - Adds a new card to a user's library
   - May also add the card to one or more collections
   - May create related cards (notes, highlights, screenshots)

2. **AddCardToCollection**
   - Adds an existing card to a collection

3. **AnnotateCard**
   - Creates annotation cards (notes, highlights) linked to an existing card

4. **GetUrlMetadataUseCase**
   - Retrieves metadata for a given URL
   - First checks if metadata already exists in the repository
   - If not found, fetches from external metadata service (e.g., Citoid API)
   - Stores retrieved metadata for future use

## Implementation Considerations

- When a card is added to multiple collections, this should be handled as separate operations on each Collection aggregate.
- The LibraryService domain service coordinates operations that span multiple aggregates.
- Card-to-card relationships (like highlights of a URL) are maintained within the Card aggregate.
- "Library" is a conceptual grouping of a user's content rather than an aggregate with its own identity and lifecycle.
- A user's library is accessed through repository methods (e.g., `findByCuratorId()`) and coordinated through the LibraryService.

### External API Integration Patterns

- **Repository Pattern**: Use `IUrlMetadataRepository` to abstract metadata storage and provide caching
- **Service Interface**: Use `IMetadataService` to abstract external API calls (Citoid, etc.)
- **Dependency Inversion**: Domain layer depends on interfaces, infrastructure layer implements them
- **Caching Strategy**: Check repository first before making external API calls to reduce latency and API usage
- **Error Handling**: External API failures should be handled gracefully with fallback strategies