# Import & Export Architecture & Plan

This document outlines the modular architecture and step-by-step technical roadmap for handling monster stat block imports, exports, and sharing across multiple formats in the **Monster Cards** application.

---

## 1. File Formats & Importer Architecture

Monster Cards separates canonical native formats from third-party import sources:

1. **Universal Native Format (`.card` / `.card.txt`)**:
   - Our native file format utilizing the **Universal 2-Tier Envelope Specification** (`$schema`, `uuid`, `ruleset_id`, `entity_type`, `display_name`, `template_id`, `properties`).
   - Uses the **Open5e Ruleset** (`ruleset_id: "open5e"`) which matches our app's 5e monster and character needs ([`entities/character.json`](file:///Users/tom/Projects/TTRPG/CharacterDataFiles/rulesets/open5e/entities/character.json)).
   - Supported for both **Export** and **Native Import**.
2. **Third-Party Import-Only Formats**:
   - `.monster` / `.monster.txt`: Tetra-cube generator stat block JSON format (Import-only).
   - D&D Beyond URLs / API payloads: D&D Beyond character web service format (Import-only).

All format parsers implement a shared interface:

```java
public interface EntityImporter<T> {
    /**
     * Determines whether the given input string or payload can be handled by this importer.
     */
    boolean canImport(@NonNull String input);

    /**
     * Parses the raw input string into internal domain memory objects (e.g., Monster).
     */
    @NonNull
    T parse(@NonNull String input) throws Exception;
}
```

The output of any `EntityImporter` is an in-memory domain model (such as `Monster`), which is then passed to `MonsterImportFragment` for UI preview and Room database persistence.

---

## 2. Step-by-Step Implementation Roadmap

```
  ┌────────────────----------------────────────────────────┐
  │ Step 0: Restrict File Extension Intent Filters         │
  └────────────────────────────────────────────────────────┘
                               │
                               v
  ┌────────────────----------------────────────────────────┐
  │ Step 1: Refactor Import Code to Shared Interface       │
  └────────────────────────────────────────────────────────┘
                               │
                               v
  ┌────────────────----------------────────────────────────┐
  │ Step 2: Update Tetra-cube Importer to Newest Format    │
  └────────────────────────────────────────────────────────┘
                               │
                               v
  ┌────────────────----------------────────────────────────┐
  │ Step 3: Import from D&D Beyond Character URL           │
  └────────────────────────────────────────────────────────┘
                               │
                               v
  ┌────────────────----------------────────────────────────┐
  │ Step 4: Export to Custom Internal Format (Open5e)      │
  └────────────────────────────────────────────────────────┘
                               │
                               v
  ┌────────────────----------------────────────────────────┐
  │ Step 5: Import from Custom Internal Format (Open5e)      │
  └────────────────────────────────────────────────────────┘
                               │
                               v
  ┌────────────────----------------────────────────────────┐
  │ Step 6: Generic Android Share Button Feature           │
  └────────────────────────────────────────────────────────┘
                               │
                               v
  ┌────────────────----------------────────────────────────┐
  │ Step 7: Specific Share Targets (NFC, Bluetooth, URL)   │
  └────────────────────────────────────────────────────────┘
```

---

### Step 0: File Extension Intent Filters (.monster & .card)

Restrict the Android app so it reacts to supported stat block file extensions (`.monster`, `.monster.txt` for Tetra-cube format; `.card`, `.card.txt` for internal Open5e card format) instead of all generic `.txt` files.

1. **`AndroidManifest.xml`**:
   Add `android:pathPattern` constraints (`.monster`, `.monster.txt`, `.card`, `.card.txt`) to the `<intent-filter>` for `MainActivity`.
2. **`MainActivity.java`**:
   Implement runtime display name validation querying `OpenableColumns.DISPLAY_NAME` via `ContentResolver` to filter out non-monster files passed via `content://` URIs.

---

### Step 1: Refactor Import Code into Importer Architecture

Extract the current parsing logic out of `MonsterImportHelper.java` into a standalone importer class implementing `EntityImporter<Monster>`.

- **New Class**: `TetraCubeMonsterImporter implements EntityImporter<Monster>`
- **Responsibilities**:
  - `canImport(json)`: Validates that the JSON string contains Tetra-cube properties (e.g. `hitDice`, `armorName`, `strPoints`).
  - `parse(json)`: Converts the raw JSON payload into an in-memory `Monster` object.

---

### Step 2: Update Tetra-cube Importer to Newest Format

Update `TetraCubeMonsterImporter` to support newer fields from the Tetra-cube generator source (`js/statblock-script.js`):

- **New Fields to Parse**:
  - `bonusActions`: Array of `{ name, desc }` objects $\rightarrow$ mapped to `monster.actions` or bonus action structure.
  - `mythics` / `isMythic` / `mythicDescription`: Array of mythic action objects and intro text $\rightarrow$ mapped to `monster.legendaryActions`.
  - `blind`: Parse boolean flag to append `"(blind beyond this radius)"` to `blindsight`.
  - Section intro text: Parse `legendariesDescription`, `lairDescription`, `regionalDescription`.

---

### Step 3: Import from D&D Beyond URL & Web Services

Allow users to import characters, monsters, and future entity types directly from D&D Beyond URLs using a multi-channel ingestion architecture.

- **Primary Target Share Links**:
  - Site Share Link: `https://www.dndbeyond.com/characters/49074997/s7sLyX` (primary link copied when tapping "Share" on D&D Beyond; contains numeric character ID `49074997` and share token `s7sLyX`).
  - Standard Web Link: `https://www.dndbeyond.com/characters/49074997` (HTML page that loads background JavaScript to fetch stats).
  - URL Extractor Regex: `https?://(?:www\.)?dndbeyond\.com/characters/(\d+)(?:/([a-zA-Z0-9]+))?`

- **URL Ingestion Channels**:
  1. **Android Share Sheet (`ACTION_SEND`)**:
     - Register `intent-filter` for `ACTION_SEND` with `text/plain` in `AndroidManifest.xml`.
     - Tapping "Share" on D&D Beyond passes `https://www.dndbeyond.com/characters/49074997/s7sLyX` directly into Monster Cards.
  2. **Android Web Link Chooser (`ACTION_VIEW`)**:
     - Register `intent-filter` for `ACTION_VIEW` in `AndroidManifest.xml` with scheme `https`, host `www.dndbeyond.com`, and path prefixes `/characters/`, `/monsters/`, `/spells/`, etc.
     - Allows Monster Cards to appear in the Android "Open with..." link chooser dialog.
  3. **In-App Menu & Clipboard Auto-Detection**:
     - Add an "Import from URL..." menu item in `LibraryFragment` and `MonsterImportFragment`.
     - Displays a URL input dialog with automatic clipboard URL detection (`ClipboardManager`).

- **Known Endpoints & Web Asset Structure**:
  - **Main Character Service Endpoint**:
    - `https://character-service.dndbeyond.com/character/v5/character/49074997?includeCustomItems=true`
    - Returns JSON payload containing full character statistics, attributes, modifiers, classes, race, inventory, and spells.
    - Full reference sample JSON payload extracted to: [`docs/dndbeyond-character-sample.json`](file:///Users/tom/Projects/Apps/MonsterCards/docs/dndbeyond-character-sample.json).
  - **Auxiliary Service Endpoints**:
    - Vehicles: `https://character-service.dndbeyond.com/character/v5/vehicles?characterId=49074997`
    - Vehicle Components: `https://character-service.dndbeyond.com/character/v5/vehicle/components?characterId=49074997`
    - Known Infusions: `https://character-service.dndbeyond.com/character/v5/known-infusions?characterId=49074997`
    - Infusion Items: `https://character-service.dndbeyond.com/character/v5/infusion/items?characterId=49074997`
  - **Image & Avatar Assets**:
    - Default Builder Avatar: `https://www.dndbeyond.com/Content/Skins/Waterdeep/images/characters/default-avatar-builder.png`
    - Race Portrait Avatar: `portraitAvatarUrl` (e.g., `https://www.dndbeyond.com/avatars/2489/881/636680412207671648.jpeg`)
    - Item / Attunement Icons: Returned in `inventory[].definition.avatarUrl` (e.g. `https://www.dndbeyond.com/avatars/19/144/636382339478303209.jpeg`, `https://www.dndbeyond.com/avatars/9249/564/637203446409923453.jpeg`).
  - **Analytics / Telemetry**:
    - `https://global.ketchcdn.com/web/v2/log...` (returns 204 No Content; user consent log endpoint ignored by importer).

- **Architecture (`DnDBeyondImporter implements EntityImporter<Monster>`)**:
  - **URL Extractor**: Extracts `{characterId}` (`49074997`) from shared URLs (`https://www.dndbeyond.com/characters/49074997/s7sLyX`), trimming optional share tokens.
  - **HTTP Service Client**: Performs an asynchronous HTTP GET request (via OkHttp/Retrofit) to `character-service.dndbeyond.com/character/v5/character/{characterId}?includeCustomItems=true`.
  - **Domain Mapper**: Maps D&D Beyond JSON fields (stats, modifiers, AC, HP, speed, proficiencies, actions, bonus actions, reactions, spells, traits, avatar URLs) into the internal `Monster` domain model (`sourceUrl = "https://www.dndbeyond.com/characters/49074997/s7sLyX"`).
  - **UI Preview**: Passes the generated `Monster` object to `MonsterImportFragment` for review and persistence.

---

### Step 4: Export to Custom Internal Format (Open5e Specification)

Implement export capability to output monsters and collections using our two-tier Open5e JSON specification (detailed in [`/Users/tom/Projects/TTRPG/CharacterDataFiles/rulesets/open5e/import-export.md`](file:///Users/tom/Projects/TTRPG/CharacterDataFiles/rulesets/open5e/import-export.md)).

- **New Class**: `Open5eExporter`

#### Open5e Ruleset Architecture & Schema Specification
The Open5e ruleset is part of a modular, versioned ruleset framework located at [`/Users/tom/Projects/TTRPG/CharacterDataFiles/rulesets/open5e/`](file:///Users/tom/Projects/TTRPG/CharacterDataFiles/rulesets/open5e/). In the future, this ruleset will be embedded directly into the application assets and versioned as our canonical model reference.

1. **Ruleset & Entity Identifiers**:
   - Every ruleset defines a short string ID (`ruleset_id: "open5e"`) and a unique UUID (`uuid: "7a35e4d2-f67b-4890-a292-6a7593c72b21"`), declared in the ruleset manifest [`manifest.json`](file:///Users/tom/Projects/TTRPG/CharacterDataFiles/rulesets/open5e/manifest.json).
   - Exported entities contain top-level identifiers (`uuid`, `ruleset_id`, `entity_type`, `display_name`) wrapped in a universal envelope.
   - When importing a JSON payload like [`examples/character/goblin.json`](file:///Users/tom/Projects/TTRPG/CharacterDataFiles/rulesets/open5e/examples/character/goblin.json), importers inspect `ruleset_id == "open5e"` to match the registered ruleset parser.

2. **Base Schemas ([`/Users/tom/Projects/TTRPG/CharacterDataFiles/schema/*.json`](file:///Users/tom/Projects/TTRPG/CharacterDataFiles/schema/))**:
   - **[`schema/entity.json`](file:///Users/tom/Projects/TTRPG/CharacterDataFiles/schema/entity.json)**: The universal envelope schema wrapping all exported entities (`uuid`, `ruleset_id`, `entity_type`, `display_name`, `description`, `version`, `tags`, `template_id`, `properties`).
   - **[`schema/manifest.json`](file:///Users/tom/Projects/TTRPG/CharacterDataFiles/schema/manifest.json)**: Schema defining ruleset manifest metadata, registered entity types, and sheet templates.
   - **[`schema/entity-definition.json`](file:///Users/tom/Projects/TTRPG/CharacterDataFiles/schema/entity-definition.json)**: Meta-schema describing how entity types and property schemas are declared.

3. **Character Entity Schema ([`entities/character.json`](file:///Users/tom/Projects/TTRPG/CharacterDataFiles/rulesets/open5e/entities/character.json))**:
   - Defines the `properties` payload for Player Characters (PCs), NPCs, and Monsters/Creatures.
   - Core fields in `properties`:
     - **Identity & Vitals**: `size`, `type`, `subtype`, `alignment`, `armor_class`, `armor_description`, `hit_points` (`current`, `max`, `formula`, `hit_dice`), `speed`, `speed_desc`, `challenge_rating`, `cr`.
     - **Ability Scores**: `abilities` (`strength`, `dexterity`, `constitution`, `intelligence`, `wisdom`, `charisma`).
     - **Proficiencies & Senses**: `saving_throws`, `skills`, `senses`, `languages`.
     - **Actions & Traits**: `traits`, `actions`, `reactions`, `legendary_actions`, `lair_actions`, `regional_effects`, and `spellcasting`.

4. **Rendering Templates (`template_id`)**:
   - The `template_id` field in the universal envelope specifies how the entity should be rendered in external or host applications.
   - Registered templates in [`manifest.json`](file:///Users/tom/Projects/TTRPG/CharacterDataFiles/rulesets/open5e/manifest.json):
     - `"stat_block"`: Monster Manual style stat block (`templates/stat_block.html`).
     - `"character_card"`: Compact NPC summary card (`templates/character_card.html`).
     - `"character_list_item"`: Fixed-height quick-reference list item (`templates/character_list_item.html`).
     - `"character_sheet"` / `"character_sheet_alt"`: Full 5e interactive character sheets.

#### Exporter Output Requirements (`Open5eExporter`)
- **Envelope Generation**:
  - Emits `$schema: "../../../schema/entity.json"`.
  - Populates `uuid` (random UUID v4), `ruleset_id: "open5e"`, `entity_type: "character"`, `display_name: monster.name`, `template_id: "stat_block"`.
- **Payload Mapping**:
  - Maps `Monster` fields to Open5e character properties in `properties` object conforming to [`entities/character.json`](file:///Users/tom/Projects/TTRPG/CharacterDataFiles/rulesets/open5e/entities/character.json).

#### Open5e vs. Monster Cards Database Schema Comparison & Final Mappings
- **Database Storage Architecture (Room SQLite vs. Open5e JSON)**:
  - **Ability Scores**: Kept as flat integer columns in Room (`strength_score`, `dexterity_score`, etc.) for maximum query performance. When exporting to Open5e JSON, `Open5eExporter` packages these into a `properties.abilities` JSON object `{ "strength": 12, ... }`. Modifiers are calculated dynamically using `floor((score - 10) / 2)`.
  - **Variable-Length Lists (`traits`, `actions`, `skills`, `languages`)**: Stored as text columns using Room `@TypeConverter` JSON converters. In Open5e JSON export, traits and actions are formatted as `{ "name": "...", "desc": "..." }` arrays.
  - **PC Identity Fields**: Added PC identity columns (`player_name`, `background`, `personality_traits`, `ideals`, `bonds`, `flaws`, `age`, `height`, `weight`, `eyes`, `skin`, `hair`, `appearance`, `backstory`, `allies_and_organizations`) directly to `Monster.java` (`Database version 7`, `MIGRATION_6_7`).
  - **Omitted PC Fields**: `currency`, `inventory`, `death_saves`, and `spellcasting.slots` are ignored/omitted in monster stat block exports.

---

### Step 5: Import from Custom Internal Format (Open5e Specification)

Implement import capability for custom Open5e JSON files.

- **New Class**: `Open5eImporter implements EntityImporter<Monster>`
- **Pipeline**:
  - `canImport(json)`: Validates `"ruleset_id": "open5e"` and `"entity_type": "character"`.
  - `parse(json)`: Unpacks `properties` into internal `Monster` domain models.

---

### Step 6: Generic Android Share Button Feature

Implement a generic "Share" feature allowing users to export and share monsters or collections from detail screens.

- **UI Action**: Add a "Share" item to action menus in `MonsterDetailFragment` and `CollectionDetailFragment`.
- **Android Intent**: Uses standard Android `ACTION_SEND` intent with `Intent.EXTRA_STREAM` or `Intent.EXTRA_TEXT` to pass exported files to other apps (e.g. Email, Drive, Messaging, Files).

---

### Step 7: Specific Share Targets & Channels

Extend the generic sharing feature with specialized, direct sharing channels (to be implemented as individual sub-steps):

- **Sub-Step 7.1 (NFC Sharing)**: Share monster data directly between devices via NFC (NDEF records / Android Beam).
- **Sub-Step 7.2 (Bluetooth / Wi-Fi Direct)**: Share monster files directly between nearby Android devices via Bluetooth / Wi-Fi.
- **Sub-Step 7.3 (Web URL with Embedded Payload)**: Generate a shareable Web URL containing compressed/base64-encoded monster JSON data.

---

## 3. Implementation Checklist & Status

- [x] **Step 0**: Restrict app intent filters in `AndroidManifest.xml` (`.monster` & `.monster.txt`) and add runtime filename validation in `MainActivity.java`.
- [x] **Step 1**: Refactor import & conversion code into a shared `EntityImporter<T>` interface and `TetraCubeMonsterImporter` class.
- [x] **Step 2**: Update Tetra-cube importer class to support the newest Tetra-cube format (`bonusActions`, `mythics`, `blind`, intro descriptions).
- [x] **Step 3**: Import from D&D Beyond URL (`https://www.dndbeyond.com/characters/49074997` fetching from v5 character service endpoint).
- [x] **Step 4**: Export to internal format described by Open5e document (`Open5eExporter`).
- [x] **Step 5**: Import from internal format described by Open5e document (`Open5eImporter`).
- [x] **Step 6**: Generic Android Share button feature (`ACTION_SEND`).
- [ ] **Step 7**: Specific share targets (7.1 NFC, 7.2 Bluetooth, 7.3 Embedded Web URL).

---

## 4. Schema Planning & Text Formatting Notes

### 4.1 Schema Architecture Considerations
- **Unified Action Entity / Type Column**:
  - Instead of maintaining separate `List<Trait>` columns for each category (`actions`, `reactions`, `legendaryActions`, `lairActions`, `regionalActions`, etc.), a unified `monster_actions` table (or model list) with an `action_type` column (`ABILITY`, `ACTION`, `BONUS_ACTION`, `REACTION`, `LEGENDARY_ACTION`, `MYTHIC_ACTION`, `LAIR_ACTION`, `REGIONAL_EFFECT`) simplifies Room DB queries and enables a single reusable editor UI component.
  - **Section Intro & End Note Metadata**:  
    - Store section-level intro text and end notes (e.g. `legendaryActionsDescription`, `lairActionsDescription`, `lairActionsEndNote`, `regionalActionsDescription`, `regionalActionsEndNote`, `mythicActionsDescription`) as dedicated metadata fields on the `Monster` entity rather than as artificial action traits.

### 4.2 Markdown & Content Formatting Support
- **Supported Markdown Syntax**:
  - **Emphasis**: Italics (`_text_` or `*text*`) and Bold (`__text__` or `**text**`).
  - **Lists**: Bulleted lists (`- `, `* `) and Numbered lists (`1. `, `2. `).
  - **External Links**: Standard markdown links `[Text](https://...)`.
  - **Internal Links (Future Deep Linking)**: Custom URI scheme `[Label](mc://<type>/<id>)` (e.g., `[Fireball](mc://spell/fireball)`) reserved for in-app navigation.
- **Data Model & Import/Export Handling**:
  - All text fields across domain models, Room persistence, and import/export payloads store raw CommonMark markdown strings.
  - Importers preserve raw markdown syntax as exported by source formats (Tetra-cube, Open5e, D&D Beyond).
  - UI rendering layers handle conversion from CommonMark to Android Spanned text at display time.