obsidian-formfire/docs/plans/2026-02-13-formfire-design.md

Formfire Design Document

Date: 2026-02-13 Status: Approved Plugin: obsidian-formfire Suite: Fire-Suite (Promptfire = Output, Logfire = Observe, Formfire = Input)

Problem

Obsidian has no native solution for structured data input. Every vault power user reaches a point where they want a form instead of manually typing frontmatter. Existing community solutions (Templater, MetaEdit) solve this only fragmentarily.

Formfire closes the Input gap in the Fire-Suite triangle: Input (Formfire) -> Observe (Logfire) -> Output (Promptfire).

Decisions

Aspect	Decision
Form Storage	Plugin Settings
Output Mode	Both: create new note OR update existing frontmatter
Access	Command Palette + Sidebar View
Field Types	Text, Textarea, Number, Toggle, Date, Dropdown, Tags, Note-Link, Folder-Picker, Rating
Body Template	Yes, with {{variable}} substitution
Form Editor	Visual Form Builder in Settings Tab
Architecture	A+B Hybrid (pragmatic with clean separation)

Data Model

interface FormDefinition {
  id: string;                          // UUID
  name: string;                        // "Meeting-Notiz", "Buchrezension"
  icon: string;                        // Obsidian icon name
  mode: "create" | "update";

  // mode: "create" only
  targetFolder?: string;
  fileNameTemplate?: string;           // e.g. "{{datum}}-{{titel}}"
  bodyTemplate?: string;               // Markdown with {{variables}}

  // mode: "update" only
  targetFile?: "active" | "prompt";

  fields: FormField[];
}

interface FormField {
  id: string;                          // Unique key (becomes frontmatter property)
  label: string;                       // Display name
  type: FieldType;
  required: boolean;
  defaultValue?: any;
  placeholder?: string;
  options?: string[];                  // For dropdown/tags
  folder?: string;                     // For note-link: which folder to search
}

type FieldType =
  | "text" | "textarea" | "number" | "toggle"
  | "date" | "dropdown" | "tags"
  | "note-link" | "folder-picker" | "rating";

Architecture

obsidian-formfire/
├── src/
│   ├── main.ts                    // Plugin class, commands, view registration
│   ├── types.ts                   // All interfaces
│   ├── core/
│   │   ├── form-store.ts          // CRUD for FormDefinitions in Settings
│   │   └── form-processor.ts      // Create note / update frontmatter
│   ├── ui/
│   │   ├── settings-tab.ts        // Settings tab with form builder
│   │   ├── form-builder.ts        // Visual form builder (add/edit fields)
│   │   ├── form-modal.ts          // The form modal for filling out
│   │   ├── form-sidebar.ts        // Sidebar view with form list
│   │   └── field-renderers.ts     // Renderer per field type
│   └── utils/
│       ├── template-engine.ts     // {{variable}} substitution
│       └── validators.ts          // Field validation
├── styles.css
├── manifest.json
├── package.json
├── tsconfig.json
└── esbuild.config.mjs

Data Flow

User opens form (Command/Sidebar)
        |
FormStore loads FormDefinition from Settings
        |
FormModal renders fields via FieldRenderers
        |
User fills out -> Submit
        |
FormProcessor:
  mode:"create" -> Template Engine -> vault.create()
  mode:"update" -> processFrontMatter() on active/chosen note

UI Concept

A) Settings Tab: Visual Form Builder

• Top: List of all forms (name, mode, field count) with Add/Edit/Delete/Duplicate buttons
• Bottom / Modal: Form builder opens on edit with:
  • Name, Icon, Mode selector (create/update)
  • Field list with reorder (up/down buttons)
  • Per field: type dropdown, label, key, required toggle, type-specific options
  • For create mode: target folder, filename template, body template textarea

B) Form Modal (for filling out)

• Title: form name + icon
• Fields rendered vertically by type:
  • text -> Obsidian Setting with text input
  • textarea -> Multi-line text field
  • number -> Number input
  • toggle -> Obsidian Toggle component
  • date -> Native HTML date picker
  • dropdown -> Obsidian Dropdown component
  • tags -> Multi-select with autocomplete (from existing vault tags)
  • note-link -> Text input with vault file suggest
  • folder-picker -> Text input with folder suggest
  • rating -> 5 clickable stars
• Bottom: Submit button + validation feedback for required fields
• For mode: "update" + targetFile: "prompt": File picker first, then form (pre-filled with existing frontmatter values)

C) Sidebar View

• Simple list of all forms with icon + name
• Click -> opens FormModal
• Gear icon -> opens Settings directly

Note: Detailed UI will be designed using the frontend-design skill during implementation.

Commands

Command	Description
formfire:open-form	Opens picker modal with all forms, then the chosen FormModal
formfire:open-form-<name>	Dynamically registered commands per form (direct access)
formfire:open-sidebar	Open/focus sidebar view
formfire:open-settings	Jump directly to Formfire settings

Ribbon Icon: Form icon in left sidebar, opens form picker.

Template Engine

Intentionally simple:

{{fieldname}}    -> Value of the field
{{date}}         -> Current date (YYYY-MM-DD)
{{time}}         -> Current time (HH:mm)
{{datetime}}     -> Date + time

Used in:

• fileNameTemplate (filename for new notes)
• bodyTemplate (markdown content of new notes)

Out of Scope for V1

• No conditional logic (show field X only if field Y = ...)
• No multi-step wizard
• No export/import of form definitions
• No computed fields
• No custom CSS per form
• No API for other plugins

Technical Conventions (from Fire-Suite)

• Build: esbuild, ES2022 target
• Settings: deep merge pattern (from Logfire)
• Plugin lifecycle: standard Obsidian pattern (loadSettings -> register -> start)
• Feedback: Obsidian Notice API
• File access: vault.create(), processFrontMatter(), metadataCache