Formalizing FileKitty's Data Model

[banagale]

This plan introduces a structured data model to replace the implicit history logic in the PyQt5 version of FileKitty. It will support:

• Structured prompt composition and undo/redo history
• Session save/load with JSON
• Swift-native UI port via Codable models
• Future backend integration via Django or another layer

---

✅ Overview

We will proceed in two coordinated phases:

Phase 1: Python (Legacy App)

Formalize a structured data model in Python and use it to manage FileKitty’s session state and history.

Phase 2: SwiftUI (Native macOS App)

Create Swift Codable equivalents of the models, validate JSON compatibility, and build an in-memory prototype UI.

---

🧱 Phase 1 – Python Model Foundation

GitHub Issues

• #63: Define PromptSession data model with @dataclass for structured history tracking
• #64: Replace legacy history management with structured PromptSession model
• #65: Implement save/load for PromptSession to JSON with autosave support

Models

Model	Description	Scope
PromptSession	Root session controller (history stack, metadata)	✅ #63
SessionState	Single editable prompt instance with components/output	✅ #63
PromptComponent	A text, file, or special block within the prompt	✅ #63
PromptDataBlock	Rich metadata or file-tree insertable content	✅ #63
PromptTemplate	(Stub) reusable saved prompt structure	⚠️ Stub #63
PromptVariable	(Stub) runtime-resolved variables in templates	⚠️ Stub #63
PromptExecution	(Stub) model usage, latency, etc.	⚠️ Stub #63

---

🧩 Phase 2 – SwiftUI Port of Shared Model

Swift GitHub Issues (to be created)

• Create Swift Codable models mirroring Python PromptSession and related types
• Implement in-memory PromptSession history flow in SwiftUI prototype
• Validate Python-exported PromptSession JSON loads into Swift correctly

Notes

• Swift models should match Python field names and nesting
• App state will remain in-memory for now
• Token count can be tracked via a field in SessionState
• Import/export is internal only—no UI for JSON load needed in Swift yet

---

📌 Tracking Issue (to be created)

Title: Formalize FileKitty's data model for structured session, prompt, and history tracking

This top-level issue will:

• Summarize this plan
• Link to all subtasks (existing and future)
• Be marked complete when all issues are closed

---

✅ Benefits

• Enables consistent prompt-aware UX across platforms
• Shared JSON contract supports syncing and export
• Provides foundation for future SaaS or backend integration