# Gonno — Functional & Technical Specification

Gonno is an offline-first iOS personal diary and micro-journaling application designed for instant note taking, photo attachments, automatic contextual metadata (location and weather), and synchronization with remote storage (ownCloud / OCIS / WebDAV or custom local/iCloud folders) using a transparent, human-readable file structure.

---

## 1. Storage & File Format Specification

The source of truth for all data is plain text markdown (`.md`) files and raw image files stored on the filesystem.

### 1.1 Directory Structure
```
Journal/
├── 2026-03-25T143000.md
├── 2026-03-25T164512.md
└── images/
    ├── 2026-03-25T143000.jpg
    └── 2026-03-25T164512-1.jpg
```

### 1.2 Note File Naming
- Filenames follow the UTC ISO 8601 compact timestamp: `YYYY-MM-DDTHHMMSS.md` (e.g. `2026-03-25T143000.md`).
- Lexicographical sorting corresponds to chronological sorting.

### 1.3 Note Content Format
Each note file consists of two sections separated by a markdown horizontal rule (`---`):
1. **Body Section**: Standard markdown text (paragraphs, quotes with `>`, inline formatting).
2. **Metadata Footer Section**: Key contextual attributes on separate lines:
   - **Hashtags**: Space-separated tags prefixed by `#` (e.g. `#journal #travel`).
   - **Location**: Format `@PlaceName / latitude,longitude` or `@latitude,longitude` (e.g. `@Paris / 48.8566,2.3522`).
   - **Weather**: Format `temperature°C, Condition` (e.g. `18°C, Partly Cloudy`).
   - **Embedded Images**: Markdown image syntax pointing to the relative image path (e.g. `![](/images/2026-03-25T143000.jpg)`).

#### Example File
```markdown
Enjoying a quiet afternoon walking through the park.

> "Keep a green tree in your heart and perhaps the singing bird will come."

![](/images/2026-03-25T143000.jpg)

---
#daily #walk
@Luxembourg Gardens / 48.8462,2.3371
19°C, Sunny
```

---

## 2. Architecture & Data Flow

```
┌──────────────────────────────────────────────────────────┐
│                         SwiftUI UI                       │
│      TimelineView  │  MemoryComposerView  │ DetailView   │
└────────────────────────────┬─────────────────────────────┘
                             │
                  ┌──────────▼──────────┐
                  │   JournalViewModel  │
                  └──────────┬──────────┘
                             │
     ┌───────────────────────┴───────────────────────┐
     ▼                                               ▼
┌───────────────────────────┐         ┌────────────────────────────┐
│   JournalStorageService   │         │       OCISSyncService      │
│ ───────────────────────── │         │ ────────────────────────── │
│ • In-Memory Swift Model   │         │ • ownCloud / OCIS WebDAV   │
│ • Snapshot Disk Cache     │         │ • Fast Incremental Sync    │
│ • Plain-Text .md I/O      │         │ • Keychain Auth Storage    │
└───────────────────────────┘         └────────────────────────────┘
```

### 2.1 Fast In-Memory Model & Snapshot Caching
- **0ms Cold Boot**:
  - The app serializes parsed note models into a lightweight cache snapshot on disk.
  - On launch, the snapshot is decoded immediately to display the timeline without loading spinners or SQLite startup latency.
- **Background Integrity**:
  - A background task silently checks for filesystem modifications or invokes incremental cloud sync, updating the in-memory state and snapshot without blocking UI interactions.

### 2.2 Metadata Automation
- **Location Service**: Uses CoreLocation to resolve GPS coordinates and reverse-geocode place/city names.
- **Weather Service**: Fetches current temperature and weather conditions (e.g. via Open-Meteo API) using coordinates and timestamp.
- **EXIF Extraction**: When importing photos, extracts original capture timestamp and embedded GPS location from image metadata.

---

## 3. Cloud & Storage Providers

### 3.1 ownCloud / OCIS (WebDAV) Sync
- Direct HTTP WebDAV client (`PROPFIND`, `GET`, `PUT`, `DELETE`, `MKCOL`).
- Credentials (Server URL, Username, Password / App Token) stored securely in the iOS Keychain.
- **Incremental Sync (Pull-to-Refresh & App Resume)**:
  - Executes a single `PROPFIND` against the remote journal folder.
  - Filters for files modified after the latest local timestamp.
  - Downloads only new/updated `.md` notes and referenced missing images.
- **Automatic Upload**: Notes and attached photos are automatically uploaded to WebDAV upon save. Remote deletions are triggered upon note deletion.

### 3.2 Local & File Provider Storage
- Supports operating out of the default local app sandbox or a user-selected folder (iCloud Drive, external File Provider) via security-scoped bookmarks.
- Real-time directory watching detects external changes.

---

## 4. UI & Layout Specifications

Styling follows a clean, minimalist card aesthetic with dynamic support for Light and Dark themes.

### 4.1 Timeline View (Main Screen)
- **Top Navigation Bar**:
  - App title and folder name.
  - Cloud sync activity indicator.
  - Settings button (gear icon).
- **Horizontal Tag Filter Bar**:
  - Pill buttons displaying available hashtags, plus an "All" option to filter cards.
- **Timeline Feed**:
  - Vertical list of note cards grouped chronologically.
  - **Month/Year Separators**: Displayed when traversing calendar month boundaries.
  - **Location Jump Banners**: A full-width static map banner with a bottom-right location badge inserted between consecutive notes when the travel distance exceeds 50 km.
- **Note Cards**:
  - **Left Column**: Short uppercase weekday (sans-serif) above bold day number.
  - **Main Body**:
    - For text notes: Markdown body text with floated thumbnail preview on the right (if photos attached).
    - For photo notes: Full-width top photo banner with caption text below.
  - **Card Footer**: Horizontal row with timestamp on the left, location with location SF Symbol in the middle, and temperature with multicolor weather SF Symbol on the right.
- **Bottom Action Bar**:
  - **Expandable Search**: A compact search button that expands into an interactive search bar on tap.
  - **Add Text Note Button**: Direct button opening the note composer.
  - **Add Photo Button**: Direct photo picker opening the image composer.

### 4.2 Note Composer (Creation & Editing)
- Presented as a sheet modal.
- **Text Editor**: Full-width markdown editor automatically focused on presentation with keyboard raised.
- **Header / Footer Info**: Displays creation date/time, live location name, and temperature with weather symbol.
- **Attached Images Strip**: Horizontal scroll of attached photos with removal buttons.
- **Action Toolbar**: Quick buttons to attach photos, refresh GPS/weather, or open the detailed metadata editor sheet (for manual date, tag, location, and weather overrides).

### 4.3 Detail View
- Displays full-resolution images, complete markdown text, and hashtag chips.
- Interactive MapKit card view displaying note location pin.
- Footer with full timestamp and weather.
- Edit and Delete actions in the navigation bar.

### 4.4 Settings View
- **Appearance Switcher**: Segmented selector for Light, Dark, or System mode.
- **ownCloud / OCIS WebDAV Settings**: Inputs for Server URL, Username, Password/Token, and Remote Path with a live "Test Connection" button.
- **Storage Location Picker**: Option to select a custom folder via Document Picker or reset to local sandbox.

---

## 5. System Integration & Deep Linking

### 5.1 URL Schemes & Shortcuts Integration
The app registers the custom URL scheme `gonno://` to allow logging from iOS Shortcuts, Siri, or Action Button:
- `gonno://new?text={content}`: Opens composer with pre-filled text.
- `gonno://sync`: Triggers immediate background synchronization.

### 5.2 Lifecycle Events
- Transitioning to `.active` scene phase automatically triggers non-blocking incremental cloud synchronization.